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

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
Vec
Next
AtomSet