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
RecordType