@screamingvoid/collections v0.1.2

@screamingvoid/collections

Tiny extension classes, bringing additional features and more convenient usage patterns, to Javascript's built in collections.

API

BetterMap

Wrapper around global.Map. Throws if attempting to set non-primitive as key.

new BetterMap<K, V>(other?: BetterMap<K, V>)

Create a new instance. If other is provided, it is shallow cloned.

size: number

Number of items in this map.

set(key: K, value: V, update?: boolean): boolean

Set key to value. Returns if key was created (true) or updated (false). If optional update if false and the key already exists, no changes are made.

get(key: K): V | undefined

Returns value for given key. If key is not set, returns undefined.

has(key: K): boolean

Check if key is set.

delete(key: K): boolean

Delete given key. If key has not been previously set, returns false

clear(): number

Remove all items from this map. Returns number of items cleared.

for (const [K, V] of map)

Iterate over [key, value] pairs stored in this map.

entries(): IterableIterator<[K, V]>

Iterate over [key, value] pairs stored in this map. Built-in Map compat.

keys(): IterableIterator<K>

Iterate over all keys.

values(): IterableIterator<V>

Iterate over all values.

BufferMap

BetterMap extension that transparently serializes keys to allow (and enforce) TypedArray keys. For usage see BetterMap.

BetterSet

Wrapper around global.Set providing convenience methods that should've been part of Set spec.

new BetterSet<V>(other?: Iterable<V>)

Create new instance, and if given, populate it with items from other.

size: number

Number of items in this set.

add(value: V): boolean

Add unique value to set. Returns whether value was added.

clear(): number

Remove all values from this set. Returns number of values cleared.

delete(value: V): boolean

Remove given value from this set. Return whether value was removed or not present to begin with.

has(value: V): boolean

Check if this set contains value

for (const V of set)

Iterate over all values in the set.

entries(): IterableIterator<[V, V]>

Iterate over [value, value] pairs. global.Set compat.

keys(): IterableIterator<V>, values(): IterableIterator<V>

Iterate over all values in the set. global.Set compat.

superset(subset: BetterSet<V>): boolean

Check if subset is a valid subset of this set.

union(other: BetterSet<V>): BetterSet<V>

Create a new set with all the value from this set and other.

intersection(other: BetterSet<V>): BetterSet<V>

Create a new set with values common to both this set and other.

difference(other: BetterSet<V>): BetterSet<V>

Create a new set containing items from this set that are not present in other.

symmetric(other: BetterSet<V>): BetterSet<V>

Create symmetric difference of this set and other. The resulting set will contain items from this set that are not present in other and items from other that are not present in this set.

BufferSet

BetterSet extension that adds transparent serialization, allowing (and enforcing) TypedArray values. See BetterSet for API.

WeakMap

A map with weak references to it's values. Unlike global.WeakMap, the keys are strongly referenced and instead the values are kept as weak references, by wrapping them with global.WeakRef instances. When values are garbage collected, hanging keys are cleaned up on next access. Implements BetterMap API. Size is calculated on the fly and always represents the number of values that have not been garbage collected.

BufferWeakMap

A map with TypedArray keys (strong references) and any garbage collectable values. Extends WeakMap from this module. Implements BetterMap API.

LRU

This one doesn't extend a built-in type, but it's based on a module commonly used through Void project. LRU updated with modern code and a couple convenience changes based on our usage. The biggest change is that the version included in this package is backed by a Map, rather that object, which allows to use any primitive as cache keys. I also added buffer constructor option to allow TypedArray keys.

new LRU<K, V>(maxOrOptions: { max?: number, maxAge?: number, buffer?: boolean })

Create new instance. maxOrOptions can be a number, specifying the number of items to keep or object. In case of object, max key has same meaning. maxAge is the number of milliseconds before dropping keys. buffer allows using TypedArrays as keys.

lenght: number

The number of entries currently in cache.

keys(): IterableIterator<K>

Iterate over all cache keys.

clear(): number

Clear all entries. Returns number of entries cleared.

remove(key: K): V | undefined

Remove entry at key. Returns value at key or undefined.

peek(key: K): V | undefined

Get the value at key or undefined. Does not bump entries.

set(key: K, value: V): boolen

Create and/or bump value at key. Returns whether entry was created or bumped.

get(key: K): V | undefined

Get the value at key or undefined. Bumps entry if found.

on("evict", ({ key: K, value: V }) => void)

Emitted when entry expires. Note that entries are expired lazily on access.

License

Apache-2.0