AtomMap

See source code
Table of contents

A drop-in replacement for Map that stores values in atoms and can be used in reactive contexts.

class AtomMap<K, V> implements Map<K, V> {}

Constructor

Creates a new AtomMap instance.

name - A unique name for this map, used for atom identification entries - Optional initial entries to populate the map with

Example

// Create an empty map
const map = new AtomMap("userMap");

// Create a map with initial data
const initialData: [string, number][] = [
  ["a", 1],
  ["b", 2],
];
const mapWithData = new AtomMap("numbersMap", initialData);

Parameters

NameDescription

name

string;

entries

Iterable<readonly [K, V]>;

Properties

[Symbol.toStringTag]

The string tag used by Object.prototype.toString for this class.

[Symbol.toStringTag]: string;

Example

const map = new AtomMap("myMap");
console.log(Object.prototype.toString.call(map)); // '[object AtomMap]'

size

readonly

The number of key-value pairs in the map. This property is reactive and will cause reactive contexts to update when the size changes.

get size(): number;

Example

const map = new AtomMap("myMap");
console.log(map.size); // 0
map.set("a", 1);
console.log(map.size); // 1

Methods

[Symbol.iterator]( )

Returns the default iterator for the map, which is the same as entries(). This allows the map to be used in for...of loops and other iterable contexts.

[Symbol.iterator](): Generator<[K, V], undefined, unknown>;

Example

const map = new AtomMap("myMap");
map.set("a", 1).set("b", 2);

// These are equivalent:
for (const [key, value] of map) {
  console.log(`${key}: ${value}`);
}

for (const [key, value] of map.entries()) {
  console.log(`${key}: ${value}`);
}

clear( )

Removes all key-value pairs from the map.

clear(): void;

Example

const map = new AtomMap("myMap");
map.set("a", 1).set("b", 2);
map.clear();
console.log(map.size); // 0

delete( )

Removes a key-value pair from the map.

delete(key: K): boolean;

Example

const map = new AtomMap("myMap");
map.set("temp", "value");
console.log(map.delete("temp")); // true
console.log(map.delete("missing")); // false

Parameters

NameDescription

key

K;

The key to remove

Returns

boolean;

True if the key existed and was removed, false if it didn't exist

deleteMany( )

Removes multiple key-value pairs from the map in a single transaction.

deleteMany(keys: Iterable<K>): [K, V][];

Example

const map = new AtomMap("myMap");
map.set("a", 1).set("b", 2).set("c", 3);
const deleted = map.deleteMany(["a", "c", "missing"]);
console.log(deleted); // [['a', 1], ['c', 3]]

Parameters

NameDescription

keys

Iterable<K>;

An iterable of keys to remove

Returns

[K, V][];

An array of [key, value] pairs that were actually deleted

entries( )

Returns an iterator that yields [key, value] pairs for each entry in the map. This method is reactive and will cause reactive contexts to update when entries change.

entries(): Generator<[K, V], undefined, unknown>;

Example

const map = new AtomMap("myMap");
map.set("a", 1).set("b", 2);
for (const [key, value] of map.entries()) {
  console.log(`${key}: ${value}`);
}

forEach( )

Executes a provided function once for each key-value pair in the map. This method is reactive and will cause reactive contexts to update when entries change.

forEach(
  callbackfn: (value: V, key: K, map: AtomMap<K, V>) => void,
  thisArg?: any,
): void;

Example

const map = new AtomMap("myMap");
map.set("a", 1).set("b", 2);
map.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});

Parameters

NameDescription

callbackfn

(
  value: V,
  key: K,
  map: AtomMap<K, V>,
) => void;

Function to execute for each entry - value - The value of the current entry - key - The key of the current entry - map - The AtomMap being traversed

thisArg

any;

Value to use as this when executing the callback

Returns

void;

get( )

Gets the value associated with a key. Returns undefined if the key doesn't exist. This method is reactive and will cause reactive contexts to update when the value changes.

get(key: K): undefined | V;

Example

const map = new AtomMap("myMap");
map.set("name", "Alice");
console.log(map.get("name")); // 'Alice'
console.log(map.get("missing")); // undefined

Parameters

NameDescription

key

K;

The key to retrieve the value for

Returns

undefined | V;

The value associated with the key, or undefined if not found

getOrInsert( )

Gets the value associated with a key, inserting defaultValue first if the key doesn't exist. This method is reactive and will cause reactive contexts to update when the value changes.

getOrInsert(key: K, defaultValue: V): V;

Example

const map = new AtomMap("myMap");
console.log(map.getOrInsert("count", 0)); // 0, and 'count' is now set
console.log(map.getOrInsert("count", 10)); // 0

Parameters

NameDescription

key

K;

The key to retrieve the value for

defaultValue

V;

The value to insert if the key doesn't exist

Returns

V;

The existing value, or defaultValue if the key was missing

getOrInsertComputed( )

Gets the value associated with a key, inserting the result of callback first if the key doesn't exist. The callback only runs when the key is missing. This method is reactive and will cause reactive contexts to update when the value changes.

getOrInsertComputed(key: K, callback: (key: K) => V): V;

Example

const map = new AtomMap<string, string[]>("myMap");
map.getOrInsertComputed("tags", () => []).push("new");

Parameters

NameDescription

key

K;

The key to retrieve the value for

callback

(key: K) => V;

Called with the key to produce the value to insert

Returns

V;

The existing value, or the newly computed value if the key was missing

has( )

Checks whether a key exists in the map. This method is reactive and will cause reactive contexts to update when keys are added or removed.

has(key: K): boolean;

Example

const map = new AtomMap("myMap");
console.log(map.has("name")); // false
map.set("name", "Alice");
console.log(map.has("name")); // true

Parameters

NameDescription

key

K;

The key to check for

Returns

boolean;

True if the key exists in the map, false otherwise

keys( )

Returns an iterator that yields all keys in the map. This method is reactive and will cause reactive contexts to update when keys change.

keys(): Generator<K, undefined, unknown>;

Example

const map = new AtomMap("myMap");
map.set("name", "Alice").set("age", 30);
for (const key of map.keys()) {
  console.log(key); // 'name', 'age'
}

set( )

Sets a value for the given key. If the key already exists, its value is updated. If the key doesn't exist, a new entry is created.

set(key: K, value: V): this;

Example

const map = new AtomMap("myMap");
map.set("name", "Alice").set("age", 30);

Parameters

NameDescription

key

K;

The key to set the value for

value

V;

The value to associate with the key

Returns

this;

This AtomMap instance for method chaining

update( )

Updates an existing value using an updater function.

update(key: K, updater: (value: V) => V): void;

Example

const map = new AtomMap("myMap");
map.set("count", 5);
map.update("count", (count) => count + 1); // count is now 6

Parameters

NameDescription

key

K;

The key of the value to update

updater

(value: V) => V;

A function that receives the current value and returns the new value

Returns

void;

values( )

Returns an iterator that yields all values in the map. This method is reactive and will cause reactive contexts to update when values change.

values(): Generator<V, undefined, unknown>;

Example

const map = new AtomMap("myMap");
map.set("name", "Alice").set("age", 30);
for (const value of map.values()) {
  console.log(value); // 'Alice', 30
}
Prev
MermaidDiagramError
Next
AtomSet