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 |
Creates an identical shallow copy of this collection.
Example
const newColl = someColl.clone();
const newColl = someColl.clone();
Static
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 |
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 |
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 |
each(fn)
:
this
Identical to Map.forEach(), but returns the collection instead of undefined.
Example
collection
.each(user => console.log(user.username))
.filter(user => user.bot)
.each(user => console.log(user.username));
collection
.each(user => console.log(user.username))
.filter(user => user.bot)
.each(user => console.log(user.username));
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => void | No | Function to execute for each element |
each(fn, thisArg)
:
this
Identical to Map.forEach(), but returns the collection instead of undefined.
Example
collection
.each(user => console.log(user.username))
.filter(user => user.bot)
.each(user => console.log(user.username));
collection
.each(user => console.log(user.username))
.filter(user => user.bot)
.each(user => console.log(user.username));
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => void | No | Function to execute for each element |
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 |
Checks if all items passes a test. Identical in behavior to Array.every().
Example
collection.every(user => !user.bot);
collection.every(user => !user.bot);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Checks if all items passes a test. Identical in behavior to Array.every().
Example
collection.every(user => !user.bot);
collection.every(user => !user.bot);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
every(fn)
:
boolean
Checks if all items passes a test. Identical in behavior to Array.every().
Example
collection.every(user => !user.bot);
collection.every(user => !user.bot);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Checks if all items passes a test. Identical in behavior to Array.every().
Example
collection.every(user => !user.bot);
collection.every(user => !user.bot);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Checks if all items passes a test. Identical in behavior to Array.every().
Example
collection.every(user => !user.bot);
collection.every(user => !user.bot);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
every(fn, thisArg)
:
boolean
Checks if all items passes a test. Identical in behavior to Array.every().
Example
collection.every(user => !user.bot);
collection.every(user => !user.bot);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Identical to Array.filter(), but returns a Collection instead of an Array.
Example
collection.filter(user => user.username === 'Bob');
collection.filter(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
Identical to Array.filter(), but returns a Collection instead of an Array.
Example
collection.filter(user => user.username === 'Bob');
collection.filter(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
Identical to Array.filter(), but returns a Collection instead of an Array.
Example
collection.filter(user => user.username === 'Bob');
collection.filter(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
Identical to Array.filter(), but returns a Collection instead of an Array.
Example
collection.filter(user => user.username === 'Bob');
collection.filter(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
Identical to Array.filter(), but returns a Collection instead of an Array.
Example
collection.filter(user => user.username === 'Bob');
collection.filter(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
Identical to Array.filter(), but returns a Collection instead of an Array.
Example
collection.filter(user => user.username === 'Bob');
collection.filter(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
find(fn)
:
V2 | undefined
Searches for a single item where the given function returns a truthy value. This behaves like Array.find(). All collections used in Discord.js are mapped using their
id property, and if you want to find by id you should use the get method. See MDN for details.Example
collection.find(user => user.username === 'Bob');
collection.find(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => value is V2 | No | The function to test with (should return boolean) |
find(fn)
:
V | undefined
Searches for a single item where the given function returns a truthy value. This behaves like Array.find(). All collections used in Discord.js are mapped using their
id property, and if you want to find by id you should use the get method. See MDN for details.Example
collection.find(user => user.username === 'Bob');
collection.find(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => value is V2 | No | The function to test with (should return boolean) |
find(fn, thisArg)
:
V2 | undefined
Searches for a single item where the given function returns a truthy value. This behaves like Array.find(). All collections used in Discord.js are mapped using their
id property, and if you want to find by id you should use the get method. See MDN for details.Example
collection.find(user => user.username === 'Bob');
collection.find(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => value is V2 | No | The function to test with (should return boolean) |
find(fn, thisArg)
:
V | undefined
Searches for a single item where the given function returns a truthy value. This behaves like Array.find(). All collections used in Discord.js are mapped using their
id property, and if you want to find by id you should use the get method. See MDN for details.Example
collection.find(user => user.username === 'Bob');
collection.find(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => value is V2 | No | The function to test with (should return boolean) |
findKey(fn)
:
K2 | undefined
Searches for the key of a single item where the given function returns a truthy value. This behaves like Array.findIndex(), but returns the key rather than the positional index.
Example
collection.findKey(user => user.username === 'Bob');
collection.findKey(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
findKey(fn)
:
K | undefined
Searches for the key of a single item where the given function returns a truthy value. This behaves like Array.findIndex(), but returns the key rather than the positional index.
Example
collection.findKey(user => user.username === 'Bob');
collection.findKey(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
findKey(fn, thisArg)
:
K2 | undefined
Searches for the key of a single item where the given function returns a truthy value. This behaves like Array.findIndex(), but returns the key rather than the positional index.
Example
collection.findKey(user => user.username === 'Bob');
collection.findKey(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
findKey(fn, thisArg)
:
K | undefined
Searches for the key of a single item where the given function returns a truthy value. This behaves like Array.findIndex(), but returns the key rather than the positional index.
Example
collection.findKey(user => user.username === 'Bob');
collection.findKey(user => user.username === 'Bob');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | The function to test with (should return boolean) |
first()
:
V | undefined
Obtains the first value(s) in this collection.
first(amount)
:
V[]
Obtains the first value(s) in this collection.
firstKey()
:
K | undefined
Obtains the first key(s) in this collection.
firstKey(amount)
:
K[]
Obtains the first key(s) in this collection.
Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to Array.flatMap().
Example
collection.flatMap(guild => guild.members.cache);
collection.flatMap(guild => guild.members.cache);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => Collection<K, T> | No | Function that produces a new Collection |
Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to Array.flatMap().
Example
collection.flatMap(guild => guild.members.cache);
collection.flatMap(guild => guild.members.cache);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => Collection<K, T> | No | Function that produces a new Collection |
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 |
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 |
last()
:
V | undefined
Obtains the last value(s) in this collection.
last(amount)
:
V[]
Obtains the last value(s) in this collection.
lastKey()
:
K | undefined
Obtains the last key(s) in this collection.
lastKey(amount)
:
K[]
Obtains the last key(s) in this collection.
map(fn)
:
T[]
Maps each item to another value into an array. Identical in behavior to Array.map().
Example
collection.map(user => user.tag);
collection.map(user => user.tag);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => T | No | Function that produces an element of the new array, taking three arguments |
map(fn, thisArg)
:
T[]
Maps each item to another value into an array. Identical in behavior to Array.map().
Example
collection.map(user => user.tag);
collection.map(user => user.tag);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => T | No | Function that produces an element of the new array, taking three arguments |
Maps each item to another value into a collection. Identical in behavior to Array.map().
Example
collection.mapValues(user => user.tag);
collection.mapValues(user => user.tag);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => T | No | Function that produces an element of the new collection, taking three arguments |
Maps each item to another value into a collection. Identical in behavior to Array.map().
Example
collection.mapValues(user => user.tag);
collection.mapValues(user => user.tag);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => T | No | Function that produces an element of the new collection, taking three arguments |
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 |
Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.
Example
const [big, small] = collection.partition(guild => guild.memberCount > 250);
const [big, small] = collection.partition(guild => guild.memberCount > 250);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.
Example
const [big, small] = collection.partition(guild => guild.memberCount > 250);
const [big, small] = collection.partition(guild => guild.memberCount > 250);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.
Example
const [big, small] = collection.partition(guild => guild.memberCount > 250);
const [big, small] = collection.partition(guild => guild.memberCount > 250);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.
Example
const [big, small] = collection.partition(guild => guild.memberCount > 250);
const [big, small] = collection.partition(guild => guild.memberCount > 250);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.
Example
const [big, small] = collection.partition(guild => guild.memberCount > 250);
const [big, small] = collection.partition(guild => guild.memberCount > 250);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.
Example
const [big, small] = collection.partition(guild => guild.memberCount > 250);
const [big, small] = collection.partition(guild => guild.memberCount > 250);
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => key is K2 | No | Function used to test (should return a boolean) |
random()
:
V | undefined
Obtains unique random value(s) from this collection.
random(amount)
:
V[]
Obtains unique random value(s) from this collection.
randomKey()
:
K | undefined
Obtains unique random key(s) from this collection.
randomKey(amount)
:
K[]
Obtains unique random key(s) from this collection.
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.
some(fn)
:
boolean
Checks if there exists an item that passes a test. Identical in behavior to Array.some().
Example
collection.some(user => user.discriminator === '0000');
collection.some(user => user.discriminator === '0000');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => unknown | No | Function used to test (should return a boolean) |
some(fn, thisArg)
:
boolean
Checks if there exists an item that passes a test. Identical in behavior to Array.some().
Example
collection.some(user => user.discriminator === '0000');
collection.some(user => user.discriminator === '0000');
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => unknown | No | Function used to test (should return a boolean) |
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. |
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. |
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 |
sweep(fn)
:
number
Removes items that satisfy the provided filter function.
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => unknown | No | Function used to test (should return a boolean) |
sweep(fn, thisArg)
:
number
Removes items that satisfy the provided filter function.
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (value: V, key: K, collection: this) => unknown | No | Function used to test (should return a boolean) |
tap(fn)
:
this
Runs a function on the collection and returns the collection.
Example
collection
.tap(coll => console.log(coll.size))
.filter(user => user.bot)
.tap(coll => console.log(coll.size))
collection
.tap(coll => console.log(coll.size))
.filter(user => user.bot)
.tap(coll => console.log(coll.size))
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (collection: this) => void | No | Function to execute |
tap(fn, thisArg)
:
this
Runs a function on the collection and returns the collection.
Example
collection
.tap(coll => console.log(coll.size))
.filter(user => user.bot)
.tap(coll => console.log(coll.size))
collection
.tap(coll => console.log(coll.size))
.filter(user => user.bot)
.tap(coll => console.log(coll.size))
| Name | Type | Optional | Description |
|---|---|---|---|
| fn | (collection: this) => void | No | Function to execute |