Skip to content

Collection

Defined in: packages/collection/src/index.ts:170

A keyed collection for Lunibee resource and application state.

  • set(key, value, ttl?) is TTL/LRU-aware: with a TTL (the default from options, or per call) the entry expires after that window of inactivity, and with maxSize it counts toward the cap.
  • setWithoutTTL(key, value) never expires: no deadline, no heap record, no timer, and exempt from maxSize eviction. Resource managers store Discord state this way, so it leaves only through an explicit delete.

Without options, a Collection behaves like a plain Map.

  • Map<K, V>

K

V

new Collection<K, V>(entries?, options?): Collection<K, V>

Defined in: packages/collection/src/index.ts:181

Iterable<readonly [K, V], any, any> | null

Initial entries, stored with set().

CollectionOptions<K, V> = {}

TTL and size policy.

Collection<K, V>

On a non-positive TTL or non-integer maxSize.

Map<K, V>.constructor

readonly [toStringTag]: string

Defined in: lunibee.js.org/node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:135

Map.[toStringTag]


readonly static [species]: MapConstructor

Defined in: lunibee.js.org/node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:317

Map.[species]

get size(): number

Defined in: packages/collection/src/index.ts:345

number

the number of elements in the Map.

Map.size


get stats(): CollectionStats

Defined in: packages/collection/src/index.ts:313

Cumulative hit, miss, expiry and eviction counters (a copy).

CollectionStats

[iterator](): MapIterator<[K, V]>

Defined in: packages/collection/src/index.ts:365

MapIterator<[K, V]>

Map.[iterator]


array(): V[]

Defined in: packages/collection/src/index.ts:793

Returns an array containing all stored values.

V[]


at(index): V | undefined

Defined in: packages/collection/src/index.ts:1105

Returns the value at a given insertion-order index (supports negative indices).

number

V | undefined


clear(): void

Defined in: packages/collection/src/index.ts:332

Removes all elements from the Map.

void

Map.clear


clone(): this

Defined in: packages/collection/src/index.ts:805

Returns a new collection with the same entries.

this


concat(…collections): this

Defined in: packages/collection/src/index.ts:908

Returns a new Collection with this one’s entries followed by each of collections’; a later collection wins a shared key.

…ReadonlyCollection<K, V>[]

this


delete(key): boolean

Defined in: packages/collection/src/index.ts:326

K

boolean

true if an element in the Map existed and has been removed, or false if the element does not exist.

Map.delete


difference(other): this

Defined in: packages/collection/src/index.ts:877

Returns a new Collection containing elements present in this collection but not the other.

ReadonlyCollection<K, V>

this


each(callback): this

Defined in: packages/collection/src/index.ts:784

Runs a callback for each stored value.

(value, key, collection) => unknown

this


ensure(key, factory, ttl?): V

Defined in: packages/collection/src/index.ts:290

Returns the value for key, or stores and returns what factory makes. Reading counts as a get() (restarts the TTL, marks it recently used); creating stores with set(), so ttl applies.

K

(key, collection) => V

Called with the key and this collection only when the key is missing; if it throws, nothing is stored.

number

TTL in ms for a created entry; defaults to the collection’s.

V


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

Defined in: packages/collection/src/index.ts:350

Returns an iterable of key, value pairs for every entry in the map.

MapIterator<[K, V]>

Map.entries


entriesArray(): [K, V][]

Defined in: packages/collection/src/index.ts:801

Returns a plain array of entries.

[K, V][]


equals(other): boolean

Defined in: packages/collection/src/index.ts:944

Returns whether other holds the same keys with === equal values. Neither side’s TTL or recency is touched.

ReadonlyCollection<K, V> | null | undefined

boolean


every(predicate): boolean

Defined in: packages/collection/src/index.ts:775

Returns whether every stored value satisfies a predicate.

(value, key, collection) => boolean

boolean


filter(predicate): this

Defined in: packages/collection/src/index.ts:747

Returns all values matching a predicate.

(value, key, collection) => boolean

this


find(predicate): V | undefined

Defined in: packages/collection/src/index.ts:718

Finds the first value matching a predicate.

(value, key, collection) => boolean

V | undefined


findKey(predicate): K | undefined

Defined in: packages/collection/src/index.ts:827

Returns the first key whose value matches a predicate.

(value, key, collection) => boolean

K | undefined


findLast(predicate): V | undefined

Defined in: packages/collection/src/index.ts:727

Finds the last value (in insertion order) matching a predicate.

(value, key, collection) => boolean

V | undefined


findLastKey(predicate): K | undefined

Defined in: packages/collection/src/index.ts:737

Finds the key of the last entry (in insertion order) matching a predicate.

(value, key, collection) => boolean

K | undefined


first(): V | undefined

Defined in: packages/collection/src/index.ts:696

Returns the first stored value.

V | undefined


firstEntry(): [K, V] | undefined

Defined in: packages/collection/src/index.ts:852

Returns the collection’s first matching entry as a tuple.

[K, V] | undefined


firstKey(): K | undefined

Defined in: packages/collection/src/index.ts:701

Returns the first stored key.

K | undefined


flatMap<T>(transform): T[]

Defined in: packages/collection/src/index.ts:1016

Maps every entry to an array of items and flattens the results.

T

(value, key, collection) => T[]

T[]


forEach(callback, thisArg?): void

Defined in: packages/collection/src/index.ts:369

Executes a provided function once per each key/value pair in the Map, in insertion order.

(value, key, map) => void

unknown

void

Map.forEach


get(key): V | undefined

Defined in: packages/collection/src/index.ts:258

Reads a value; restarts a TTL entry’s window and promotes it.

K

V | undefined

Map.get


getOrInsert(key, defaultValue): V

Defined in: lunibee.js.org/node_modules/typescript/lib/lib.esnext.collection.d.ts:25

Returns a specified element from the Map object. If no element is associated with the specified key, a new element with the value defaultValue will be inserted into the Map and returned.

K

V

V

The element associated with the specified key, which will be defaultValue if no element previously existed.

Map.getOrInsert


getOrInsertComputed(key, callback): V

Defined in: lunibee.js.org/node_modules/typescript/lib/lib.esnext.collection.d.ts:31

Returns a specified element from the Map object. If no element is associated with the specified key, the result of passing the specified key to the callback function will be inserted into the Map and returned.

K

(key) => V

V

The element associated with the specific key, which will be the newly computed value if no element previously existed.

Map.getOrInsertComputed


has(key): boolean

Defined in: packages/collection/src/index.ts:322

K

boolean

boolean indicating whether an element with the specified key exists or not.

Map.has


hasAll(…keys): boolean

Defined in: packages/collection/src/index.ts:813

Returns whether all supplied keys are present.

…K[]

boolean


hasAny(…keys): boolean

Defined in: packages/collection/src/index.ts:820

Returns whether at least one supplied key is present.

…K[]

boolean


intersection(other): this

Defined in: packages/collection/src/index.ts:869

Returns a new Collection containing only elements present in both collections.

ReadonlyCollection<K, V>

this


keyArray(): K[]

Defined in: packages/collection/src/index.ts:797

Returns an array containing all stored keys.

K[]


keyAt(index): K | undefined

Defined in: packages/collection/src/index.ts:1112

Returns the key at a given insertion-order index (supports negative indices).

number

K | undefined


keys(): MapIterator<K>

Defined in: packages/collection/src/index.ts:355

Returns an iterable of keys in the map

MapIterator<K>

Map.keys


last(): V | undefined

Defined in: packages/collection/src/index.ts:706

Returns the last stored value.

V | undefined


lastEntry(): [K, V] | undefined

Defined in: packages/collection/src/index.ts:857

Returns the collection’s last matching entry as a tuple.

[K, V] | undefined


lastKey(): K | undefined

Defined in: packages/collection/src/index.ts:712

Returns the last stored key.

K | undefined


map<T>(transform): T[]

Defined in: packages/collection/src/index.ts:758

Transforms every stored value into an array.

T

(value, key, collection) => T

T[]


mapValues<T>(transform): Collection<K, T>

Defined in: packages/collection/src/index.ts:955

Returns a new collection with the same keys and each value passed through transform.

T

(value, key, collection) => T

Collection<K, T>


merge<T, R>(other, whenInSelf, whenInOther, whenInBoth): Collection<K, R>

Defined in: packages/collection/src/index.ts:921

Combines this collection with other, deciding per key what to keep.

T

R

ReadonlyCollection<K, T>

(value, key) => Keep<R>

Called for a key only in this collection.

(valueOther, key) => Keep<R>

Called for a key only in other.

(value, valueOther, key) => Keep<R>

Called for a key in both.

Collection<K, R>

A new collection of the entries the callbacks kept, in this collection’s order, then other’s new keys.


partition(predicate): [Collection<K, V>, Collection<K, V>]

Defined in: packages/collection/src/index.ts:887

Splits the collection into two collections based on a predicate.

(value, key, collection) => boolean

[Collection<K, V>, Collection<K, V>]

[passing, failing] — entries satisfying the predicate, then those that don’t.


peek(key): V | undefined

Defined in: packages/collection/src/index.ts:303

Reads a value without restarting its TTL or promoting it.

K

V | undefined


purge(): number

Defined in: packages/collection/src/index.ts:387

Drops every lapsed TTL entry now.

number

How many were dropped.


random(): V | undefined

Defined in: packages/collection/src/index.ts:1079

Returns a random value, or undefined if empty. With amount, returns that many different values (all of them, shuffled, when amount is at least the size). Uses Math.random() (fast, non-cryptographic): do not use it for security-sensitive selection such as tokens or secrets.

V | undefined

If amount is not a non-negative integer.

random(amount): V[]

Defined in: packages/collection/src/index.ts:1080

Returns a random value, or undefined if empty. With amount, returns that many different values (all of them, shuffled, when amount is at least the size). Uses Math.random() (fast, non-cryptographic): do not use it for security-sensitive selection such as tokens or secrets.

number

How many values to pick.

V[]

If amount is not a non-negative integer.


randomKey(): K | undefined

Defined in: packages/collection/src/index.ts:1094

Returns a random key, or undefined if empty. With amount, returns that many different keys. Same randomness and errors as random.

K | undefined

randomKey(amount): K[]

Defined in: packages/collection/src/index.ts:1095

Returns a random key, or undefined if empty. With amount, returns that many different keys. Same randomness and errors as random.

number

How many keys to pick.

K[]


reduce<T>(fn, initialValue): T

Defined in: packages/collection/src/index.ts:1026

Reduces the collection to a single value.

T

(accumulator, value, key, collection) => T

T

T


reduceRight<T>(fn, initialValue): T

Defined in: packages/collection/src/index.ts:1035

Like reduce, but from the last entry to the first.

T

(accumulator, value, key, collection) => T

T

T


set(key, value, ttl?): this

Defined in: packages/collection/src/index.ts:213

Stores an entry with the default TTL (or ttl), marks it most recently used, and enforces maxSize. Turns a setWithoutTTL() entry back into a TTL/LRU entry.

K

V

number

this

Map.set


setWithoutTTL(key, value): this

Defined in: packages/collection/src/index.ts:251

Stores an entry that never expires: no deadline, heap record, timer or LRU eviction. It leaves only through delete, sweep, clear, or a later set().

K

V

this


some(predicate): boolean

Defined in: packages/collection/src/index.ts:766

Returns whether at least one stored value satisfies a predicate.

(value, key, collection) => boolean

boolean


someEntry(predicate): boolean

Defined in: packages/collection/src/index.ts:836

Returns whether a predicate matches at least one entry.

(value, key, collection) => boolean

boolean


sorted(comparator?): this

Defined in: packages/collection/src/index.ts:1048

Returns a new Collection with entries sorted by comparator (non-mutating). Defaults to insertion order if no comparator is provided.

(a, b, aKey, bKey) => number

this


sweep(predicate): number

Defined in: packages/collection/src/index.ts:842

Removes every entry matching a predicate and returns the number removed.

(value, key, collection) => boolean

number


symmetricDifference(other): this

Defined in: packages/collection/src/index.ts:899

Returns the entries of both collections that are in only one of them.

ReadonlyCollection<K, V>

this


tap(fn): this

Defined in: packages/collection/src/index.ts:1011

Calls fn with this collection and returns the collection unchanged. Useful for inserting debug side-effects in a chain without breaking the flow.

(collection) => unknown

this


toJSON(): [K, V][]

Defined in: packages/collection/src/index.ts:1119

Serializes the collection to a plain [key, value] array.

[K, V][]


toReversed(): this

Defined in: packages/collection/src/index.ts:964

Returns a new collection with the entries in reverse order.

this


toSorted(comparator?): this

Defined in: packages/collection/src/index.ts:972

Same as sorted, under the name the standard Array uses.

(a, b, aKey, bKey) => number

this


ttlRemaining(key): number | undefined

Defined in: packages/collection/src/index.ts:378

Milliseconds until a key lapses, or undefined if absent or never expiring.

K

number | undefined


union(other): this

Defined in: packages/collection/src/index.ts:863

Returns a new Collection containing elements from both collections.

ReadonlyCollection<K, V>

this


values(): MapIterator<V>

Defined in: packages/collection/src/index.ts:360

Returns an iterable of values in the map

MapIterator<V>

Map.values


static combineEntries<K, V>(entries, combine): Collection<K, V>

Defined in: packages/collection/src/index.ts:996

Builds a collection from entries, merging values that share a key.

K

V

Iterable<readonly [K, V]>

(firstValue, secondValue, key) => V

Called with the value stored so far, the new one and the key; its result is stored.

Collection<K, V>


static groupBy<K, V>(items, keySelector): Collection<K, V[]>

Defined in: packages/collection/src/index.ts:982

Groups items by the key keySelector returns for each.

K

V

Iterable<V>

(item, index) => K

Called with each item and its index.

Collection<K, V[]>

A new collection from each key to its items, in input order.

Map.groupBy