discord.js | Collection

Collection

export declare class Collection<K, V> extends Map<K, V>

export declare class Collection<K, V> extends Map<K, V>

A Map with additional utility methods. This is used throughout discord.js rather than Arrays for anything that has an ID, for significantly improved performance and ease-of-use.

Extends

Map<K, V>

Name	Constraints	Optional	Default	Description
K		No		The key type this collection holds
V		No		The value type this collection holds

at(index)

:

V | undefined

Identical to Array.at(). Returns the item at a given index, allowing for positive and negative integers. Negative integers count back from the last item in the collection.

Name	Type	Optional	Description
index	number	No	The index of the element to obtain

clone()

:

combineEntries(entries, combine)

:

Collection<K, V>

Creates a Collection from a list of entries.

Example

Collection.combineEntries([["a", 1], ["b", 2], ["a", 2]], (x, y) => x + y);
// returns Collection { "a" => 3, "b" => 2 }

Collection.combineEntries([["a", 1], ["b", 2], ["a", 2]], (x, y) => x + y);
// returns Collection { "a" => 3, "b" => 2 }

Name	Type	Optional	Description
entries	Iterable<[K, V]>	No	The list of entries
combine	(firstValue: V, secondValue: V, key: K) => V	No	Function to combine an existing entry with a new one

concat(collections)

:

Collection<K, V>

Combines this collection with others into a new collection. None of the source collections are modified.

Example

const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);

const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);

Name	Type	Optional	Description
collections	ReadonlyCollection<K, V>[]	No	Collections to merge

difference(other)

:

Collection<K, T | V>

The difference method returns a new structure containing items where the key is present in one of the original structures but not the other.

Name	Type	Optional	Description
other	ReadonlyCollection<K, T>	No	The other Collection to filter against

ensure(key, defaultValueGenerator)

:

V

Obtains the value of the given key if it exists, otherwise sets and returns the value provided by the default value generator.

Example

collection.ensure(guildId, () => defaultGuildConfig);

collection.ensure(guildId, () => defaultGuildConfig);

Name	Type	Optional	Description
key	K	No	The key to get if it exists, or set otherwise
defaultValueGenerator	(key: K, collection: this) => V	No	A function that generates the default value

equals(collection)

:

boolean

Checks if this collection shares identical items with another. This is different to checking for equality using equal-signs, because the collections may be different objects, but contain the same data.

Name	Type	Optional	Description
collection	ReadonlyCollection<K, V>	No	Collection to compare with

hasAll(keys)

:

boolean

Checks if all of the elements exist in the collection.

Name	Type	Optional	Description
keys	K[]	No	The keys of the elements to check for

hasAny(keys)

:

boolean

Checks if any of the elements exist in the collection.

Name	Type	Optional	Description
keys	K[]	No	The keys of the elements to check for

intersect(other)

:

Collection<K, T>

The intersect method returns a new structure containing items where the keys and values are present in both original structures.

Name	Type	Optional	Description
other	ReadonlyCollection<K, T>	No	The other Collection to filter against

keyAt(index)

:

K | undefined

Identical to Array.at(). Returns the key at a given index, allowing for positive and negative integers. Negative integers count back from the last item in the collection.

Name	Type	Optional	Description
index	number	No	The index of the key to obtain

merge(other, whenInSelf, whenInOther, whenInBoth)

:

Collection<K, R>

Merges two Collections together into a new Collection.

Example

// Sums up the entries in two collections.
coll.merge(
 other,
 x => ({ keep: true, value: x }),
 y => ({ keep: true, value: y }),
 (x, y) => ({ keep: true, value: x + y }),
);

// Sums up the entries in two collections.
coll.merge(
 other,
 x => ({ keep: true, value: x }),
 y => ({ keep: true, value: y }),
 (x, y) => ({ keep: true, value: x + y }),
);

Example

// Intersects two collections in a left-biased manner.
coll.merge(
 other,
 x => ({ keep: false }),
 y => ({ keep: false }),
 (x, _) => ({ keep: true, value: x }),
);

// Intersects two collections in a left-biased manner.
coll.merge(
 other,
 x => ({ keep: false }),
 y => ({ keep: false }),
 (x, _) => ({ keep: true, value: x }),
);

Name	Type	Optional	Description
other	ReadonlyCollection<K, T>	No	The other Collection to merge with
whenInSelf	(value: V, key: K) => Keep<R>	No	Function getting the result if the entry only exists in this Collection
whenInOther	(valueOther: T, key: K) => Keep<R>	No	Function getting the result if the entry only exists in the other Collection
whenInBoth	(value: V, valueOther: T, key: K) => Keep<R>	No	Function getting the result if the entry exists in both Collections

reduce(fn, initialValue?)

:

T

Applies a function to produce a single value. Identical in behavior to Array.reduce().

Example

collection.reduce((acc, guild) => acc + guild.memberCount, 0);

collection.reduce((acc, guild) => acc + guild.memberCount, 0);

Name	Type	Optional	Description
fn	(accumulator: T, value: V, key: K, collection: this) => T	No	Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`, and `collection`
initialValue	T	Yes	Starting value for the accumulator

reverse()

:

this

Identical to Array.reverse() but returns a Collection instead of an Array.

sort(compareFunction?)

:

this

The sort method sorts the items of a collection in place and returns it. The sort is not necessarily stable in Node 10 or older. The default sort order is according to string Unicode code points.

Example

collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);

collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);

Name	Type	Optional	Description
compareFunction	Comparator<K, V>	Yes	Specifies a function that defines the sort order. If omitted, the collection is sorted according to each character's Unicode code point value, according to the string conversion of each element.

sorted(compareFunction?)

:

Collection<K, V>

The sorted method sorts the items of a collection and returns it. The sort is not necessarily stable in Node 10 or older. The default sort order is according to string Unicode code points.

Example

collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);

collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);

Name	Type	Optional	Description
compareFunction	Comparator<K, V>	Yes	Specifies a function that defines the sort order. If omitted, the collection is sorted according to each character's Unicode code point value, according to the string conversion of each element.

subtract(other)

:

Collection<K, V>

The subtract method returns a new structure containing items where the keys and values of the original structure are not present in the other.

Name	Type	Optional	Description
other	ReadonlyCollection<K, T>	No	The other Collection to filter against

Collection

Extends

at(index)

:

V | undefined

clone()

:

Collection<K, V>

Example

combineEntries(entries, combine)

:

Collection<K, V>

Example

concat(collections)

:

Collection<K, V>

Example

difference(other)

:

Collection<K, T | V>

ensure(key, defaultValueGenerator)

:

V

Example

equals(collection)

:

boolean

hasAll(keys)

:

boolean

hasAny(keys)

:

boolean

intersect(other)

:

Collection<K, T>

keyAt(index)

:

K | undefined

merge(other, whenInSelf, whenInOther, whenInBoth)

:

Collection<K, R>

Example

Example

reduce(fn, initialValue?)

:

T

Example

reverse()

:

this

sort(compareFunction?)

:

this

Example

sorted(compareFunction?)

:

Collection<K, V>

Example

subtract(other)

:

Collection<K, V>

toJSON()

:

V[]