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 withmaxSizeit counts toward the cap.setWithoutTTL(key, value)never expires: no deadline, no heap record, no timer, and exempt frommaxSizeeviction. Resource managers store Discord state this way, so it leaves only through an explicit delete.
Without options, a Collection behaves like a plain Map.
Extends
Section titled “Extends”Map<K,V>
Type Parameters
Section titled “Type Parameters”K
V
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new Collection<
K,V>(entries?,options?):Collection<K,V>
Defined in: packages/collection/src/index.ts:181
Parameters
Section titled “Parameters”entries?
Section titled “entries?”Iterable<readonly [K, V], any, any> | null
Initial entries, stored with set().
options?
Section titled “options?”CollectionOptions<K, V> = {}
TTL and size policy.
Returns
Section titled “Returns”Collection<K, V>
Throws
Section titled “Throws”On a non-positive TTL or non-integer maxSize.
Overrides
Section titled “Overrides”Map<K, V>.constructor
Properties
Section titled “Properties”[toStringTag]
Section titled “[toStringTag]”
readonly[toStringTag]:string
Defined in: lunibee.js.org/node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:135
Inherited from
Section titled “Inherited from”Map.[toStringTag]
[species]
Section titled “[species]”
readonlystatic[species]:MapConstructor
Defined in: lunibee.js.org/node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:317
Inherited from
Section titled “Inherited from”Map.[species]
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get size():
number
Defined in: packages/collection/src/index.ts:345
Returns
Section titled “Returns”number
the number of elements in the Map.
Overrides
Section titled “Overrides”Map.size
Get Signature
Section titled “Get Signature”get stats():
CollectionStats
Defined in: packages/collection/src/index.ts:313
Cumulative hit, miss, expiry and eviction counters (a copy).
Returns
Section titled “Returns”Methods
Section titled “Methods”[iterator]()
Section titled “[iterator]()”[iterator]():
MapIterator<[K,V]>
Defined in: packages/collection/src/index.ts:365
Returns
Section titled “Returns”MapIterator<[K, V]>
Overrides
Section titled “Overrides”Map.[iterator]
array()
Section titled “array()”array():
V[]
Defined in: packages/collection/src/index.ts:793
Returns an array containing all stored values.
Returns
Section titled “Returns”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).
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”V | undefined
clear()
Section titled “clear()”clear():
void
Defined in: packages/collection/src/index.ts:332
Removes all elements from the Map.
Returns
Section titled “Returns”void
Overrides
Section titled “Overrides”Map.clear
clone()
Section titled “clone()”clone():
this
Defined in: packages/collection/src/index.ts:805
Returns a new collection with the same entries.
Returns
Section titled “Returns”this
concat()
Section titled “concat()”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.
Parameters
Section titled “Parameters”collections
Section titled “collections”…ReadonlyCollection<K, V>[]
Returns
Section titled “Returns”this
delete()
Section titled “delete()”delete(
key):boolean
Defined in: packages/collection/src/index.ts:326
Parameters
Section titled “Parameters”K
Returns
Section titled “Returns”boolean
true if an element in the Map existed and has been removed, or false if the element does not exist.
Overrides
Section titled “Overrides”Map.delete
difference()
Section titled “difference()”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.
Parameters
Section titled “Parameters”ReadonlyCollection<K, V>
Returns
Section titled “Returns”this
each()
Section titled “each()”each(
callback):this
Defined in: packages/collection/src/index.ts:784
Runs a callback for each stored value.
Parameters
Section titled “Parameters”callback
Section titled “callback”(value, key, collection) => unknown
Returns
Section titled “Returns”this
ensure()
Section titled “ensure()”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.
Parameters
Section titled “Parameters”K
factory
Section titled “factory”(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.
Returns
Section titled “Returns”V
entries()
Section titled “entries()”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.
Returns
Section titled “Returns”MapIterator<[K, V]>
Overrides
Section titled “Overrides”Map.entries
entriesArray()
Section titled “entriesArray()”entriesArray(): [
K,V][]
Defined in: packages/collection/src/index.ts:801
Returns a plain array of entries.
Returns
Section titled “Returns”[K, V][]
equals()
Section titled “equals()”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.
Parameters
Section titled “Parameters”ReadonlyCollection<K, V> | null | undefined
Returns
Section titled “Returns”boolean
every()
Section titled “every()”every(
predicate):boolean
Defined in: packages/collection/src/index.ts:775
Returns whether every stored value satisfies a predicate.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”boolean
filter()
Section titled “filter()”filter(
predicate):this
Defined in: packages/collection/src/index.ts:747
Returns all values matching a predicate.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”this
find()
Section titled “find()”find(
predicate):V|undefined
Defined in: packages/collection/src/index.ts:718
Finds the first value matching a predicate.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”V | undefined
findKey()
Section titled “findKey()”findKey(
predicate):K|undefined
Defined in: packages/collection/src/index.ts:827
Returns the first key whose value matches a predicate.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”K | undefined
findLast()
Section titled “findLast()”findLast(
predicate):V|undefined
Defined in: packages/collection/src/index.ts:727
Finds the last value (in insertion order) matching a predicate.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”V | undefined
findLastKey()
Section titled “findLastKey()”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.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”K | undefined
first()
Section titled “first()”first():
V|undefined
Defined in: packages/collection/src/index.ts:696
Returns the first stored value.
Returns
Section titled “Returns”V | undefined
firstEntry()
Section titled “firstEntry()”firstEntry(): [
K,V] |undefined
Defined in: packages/collection/src/index.ts:852
Returns the collection’s first matching entry as a tuple.
Returns
Section titled “Returns”[K, V] | undefined
firstKey()
Section titled “firstKey()”firstKey():
K|undefined
Defined in: packages/collection/src/index.ts:701
Returns the first stored key.
Returns
Section titled “Returns”K | undefined
flatMap()
Section titled “flatMap()”flatMap<
T>(transform):T[]
Defined in: packages/collection/src/index.ts:1016
Maps every entry to an array of items and flattens the results.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”transform
Section titled “transform”(value, key, collection) => T[]
Returns
Section titled “Returns”T[]
forEach()
Section titled “forEach()”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.
Parameters
Section titled “Parameters”callback
Section titled “callback”(value, key, map) => void
thisArg?
Section titled “thisArg?”unknown
Returns
Section titled “Returns”void
Overrides
Section titled “Overrides”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.
Parameters
Section titled “Parameters”K
Returns
Section titled “Returns”V | undefined
Overrides
Section titled “Overrides”Map.get
getOrInsert()
Section titled “getOrInsert()”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.
Parameters
Section titled “Parameters”K
defaultValue
Section titled “defaultValue”V
Returns
Section titled “Returns”V
The element associated with the specified key, which will be defaultValue if no element previously existed.
Inherited from
Section titled “Inherited from”Map.getOrInsert
getOrInsertComputed()
Section titled “getOrInsertComputed()”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.
Parameters
Section titled “Parameters”K
callback
Section titled “callback”(key) => V
Returns
Section titled “Returns”V
The element associated with the specific key, which will be the newly computed value if no element previously existed.
Inherited from
Section titled “Inherited from”Map.getOrInsertComputed
has(
key):boolean
Defined in: packages/collection/src/index.ts:322
Parameters
Section titled “Parameters”K
Returns
Section titled “Returns”boolean
boolean indicating whether an element with the specified key exists or not.
Overrides
Section titled “Overrides”Map.has
hasAll()
Section titled “hasAll()”hasAll(…
keys):boolean
Defined in: packages/collection/src/index.ts:813
Returns whether all supplied keys are present.
Parameters
Section titled “Parameters”…K[]
Returns
Section titled “Returns”boolean
hasAny()
Section titled “hasAny()”hasAny(…
keys):boolean
Defined in: packages/collection/src/index.ts:820
Returns whether at least one supplied key is present.
Parameters
Section titled “Parameters”…K[]
Returns
Section titled “Returns”boolean
intersection()
Section titled “intersection()”intersection(
other):this
Defined in: packages/collection/src/index.ts:869
Returns a new Collection containing only elements present in both collections.
Parameters
Section titled “Parameters”ReadonlyCollection<K, V>
Returns
Section titled “Returns”this
keyArray()
Section titled “keyArray()”keyArray():
K[]
Defined in: packages/collection/src/index.ts:797
Returns an array containing all stored keys.
Returns
Section titled “Returns”K[]
keyAt()
Section titled “keyAt()”keyAt(
index):K|undefined
Defined in: packages/collection/src/index.ts:1112
Returns the key at a given insertion-order index (supports negative indices).
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”K | undefined
keys()
Section titled “keys()”keys():
MapIterator<K>
Defined in: packages/collection/src/index.ts:355
Returns an iterable of keys in the map
Returns
Section titled “Returns”MapIterator<K>
Overrides
Section titled “Overrides”Map.keys
last()
Section titled “last()”last():
V|undefined
Defined in: packages/collection/src/index.ts:706
Returns the last stored value.
Returns
Section titled “Returns”V | undefined
lastEntry()
Section titled “lastEntry()”lastEntry(): [
K,V] |undefined
Defined in: packages/collection/src/index.ts:857
Returns the collection’s last matching entry as a tuple.
Returns
Section titled “Returns”[K, V] | undefined
lastKey()
Section titled “lastKey()”lastKey():
K|undefined
Defined in: packages/collection/src/index.ts:712
Returns the last stored key.
Returns
Section titled “Returns”K | undefined
map<
T>(transform):T[]
Defined in: packages/collection/src/index.ts:758
Transforms every stored value into an array.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”transform
Section titled “transform”(value, key, collection) => T
Returns
Section titled “Returns”T[]
mapValues()
Section titled “mapValues()”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.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”transform
Section titled “transform”(value, key, collection) => T
Returns
Section titled “Returns”Collection<K, T>
merge()
Section titled “merge()”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.
Type Parameters
Section titled “Type Parameters”T
R
Parameters
Section titled “Parameters”ReadonlyCollection<K, T>
whenInSelf
Section titled “whenInSelf”(value, key) => Keep<R>
Called for a key only in this collection.
whenInOther
Section titled “whenInOther”(valueOther, key) => Keep<R>
Called for a key only in other.
whenInBoth
Section titled “whenInBoth”(value, valueOther, key) => Keep<R>
Called for a key in both.
Returns
Section titled “Returns”Collection<K, R>
A new collection of the entries the callbacks kept, in this collection’s order, then other’s new keys.
partition()
Section titled “partition()”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.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”[Collection<K, V>, Collection<K, V>]
[passing, failing] — entries satisfying the predicate, then those that don’t.
peek()
Section titled “peek()”peek(
key):V|undefined
Defined in: packages/collection/src/index.ts:303
Reads a value without restarting its TTL or promoting it.
Parameters
Section titled “Parameters”K
Returns
Section titled “Returns”V | undefined
purge()
Section titled “purge()”purge():
number
Defined in: packages/collection/src/index.ts:387
Drops every lapsed TTL entry now.
Returns
Section titled “Returns”number
How many were dropped.
random()
Section titled “random()”Call Signature
Section titled “Call Signature”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.
Returns
Section titled “Returns”V | undefined
Throws
Section titled “Throws”If amount is not a non-negative integer.
Call Signature
Section titled “Call Signature”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.
Parameters
Section titled “Parameters”amount
Section titled “amount”number
How many values to pick.
Returns
Section titled “Returns”V[]
Throws
Section titled “Throws”If amount is not a non-negative integer.
randomKey()
Section titled “randomKey()”Call Signature
Section titled “Call Signature”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.
Returns
Section titled “Returns”K | undefined
Call Signature
Section titled “Call Signature”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.
Parameters
Section titled “Parameters”amount
Section titled “amount”number
How many keys to pick.
Returns
Section titled “Returns”K[]
reduce()
Section titled “reduce()”reduce<
T>(fn,initialValue):T
Defined in: packages/collection/src/index.ts:1026
Reduces the collection to a single value.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”(accumulator, value, key, collection) => T
initialValue
Section titled “initialValue”T
Returns
Section titled “Returns”T
reduceRight()
Section titled “reduceRight()”reduceRight<
T>(fn,initialValue):T
Defined in: packages/collection/src/index.ts:1035
Like reduce, but from the last entry to the first.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”(accumulator, value, key, collection) => T
initialValue
Section titled “initialValue”T
Returns
Section titled “Returns”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.
Parameters
Section titled “Parameters”K
V
number
Returns
Section titled “Returns”this
Overrides
Section titled “Overrides”Map.set
setWithoutTTL()
Section titled “setWithoutTTL()”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().
Parameters
Section titled “Parameters”K
V
Returns
Section titled “Returns”this
some()
Section titled “some()”some(
predicate):boolean
Defined in: packages/collection/src/index.ts:766
Returns whether at least one stored value satisfies a predicate.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”boolean
someEntry()
Section titled “someEntry()”someEntry(
predicate):boolean
Defined in: packages/collection/src/index.ts:836
Returns whether a predicate matches at least one entry.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”boolean
sorted()
Section titled “sorted()”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.
Parameters
Section titled “Parameters”comparator?
Section titled “comparator?”(a, b, aKey, bKey) => number
Returns
Section titled “Returns”this
sweep()
Section titled “sweep()”sweep(
predicate):number
Defined in: packages/collection/src/index.ts:842
Removes every entry matching a predicate and returns the number removed.
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value, key, collection) => boolean
Returns
Section titled “Returns”number
symmetricDifference()
Section titled “symmetricDifference()”symmetricDifference(
other):this
Defined in: packages/collection/src/index.ts:899
Returns the entries of both collections that are in only one of them.
Parameters
Section titled “Parameters”ReadonlyCollection<K, V>
Returns
Section titled “Returns”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.
Parameters
Section titled “Parameters”(collection) => unknown
Returns
Section titled “Returns”this
toJSON()
Section titled “toJSON()”toJSON(): [
K,V][]
Defined in: packages/collection/src/index.ts:1119
Serializes the collection to a plain [key, value] array.
Returns
Section titled “Returns”[K, V][]
toReversed()
Section titled “toReversed()”toReversed():
this
Defined in: packages/collection/src/index.ts:964
Returns a new collection with the entries in reverse order.
Returns
Section titled “Returns”this
toSorted()
Section titled “toSorted()”toSorted(
comparator?):this
Defined in: packages/collection/src/index.ts:972
Same as sorted, under the name the standard Array uses.
Parameters
Section titled “Parameters”comparator?
Section titled “comparator?”(a, b, aKey, bKey) => number
Returns
Section titled “Returns”this
ttlRemaining()
Section titled “ttlRemaining()”ttlRemaining(
key):number|undefined
Defined in: packages/collection/src/index.ts:378
Milliseconds until a key lapses, or undefined if absent or never expiring.
Parameters
Section titled “Parameters”K
Returns
Section titled “Returns”number | undefined
union()
Section titled “union()”union(
other):this
Defined in: packages/collection/src/index.ts:863
Returns a new Collection containing elements from both collections.
Parameters
Section titled “Parameters”ReadonlyCollection<K, V>
Returns
Section titled “Returns”this
values()
Section titled “values()”values():
MapIterator<V>
Defined in: packages/collection/src/index.ts:360
Returns an iterable of values in the map
Returns
Section titled “Returns”MapIterator<V>
Overrides
Section titled “Overrides”Map.values
combineEntries()
Section titled “combineEntries()”
staticcombineEntries<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.
Type Parameters
Section titled “Type Parameters”K
V
Parameters
Section titled “Parameters”entries
Section titled “entries”Iterable<readonly [K, V]>
combine
Section titled “combine”(firstValue, secondValue, key) => V
Called with the value stored so far, the new one and the key; its result is stored.
Returns
Section titled “Returns”Collection<K, V>
groupBy()
Section titled “groupBy()”
staticgroupBy<K,V>(items,keySelector):Collection<K,V[]>
Defined in: packages/collection/src/index.ts:982
Groups items by the key keySelector returns for each.
Type Parameters
Section titled “Type Parameters”K
V
Parameters
Section titled “Parameters”Iterable<V>
keySelector
Section titled “keySelector”(item, index) => K
Called with each item and its index.
Returns
Section titled “Returns”Collection<K, V[]>
A new collection from each key to its items, in input order.
Overrides
Section titled “Overrides”Map.groupBy