class Collection
extends
Map<Key, Value>export declare class Collection<Key, Value> extends Map<Key, Value>
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.
Type Parameters
Key
Value
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.
cloneCollection<Key, Value> () :
Creates an identical shallow copy of this collection.
const newColl = someColl.clone();
static combineEntriesKey
Value
>(entries: Iterable<[Key, Value]>combine: (firstValue: Value, secondValue: Value, key: Key) => Value) : Collection<Key, Value> <
Key
Value
Creates a Collection from a list of entries.
Collection.combineEntries([["a", 1], ["b", 2], ["a", 2]], (x, y) => x + y);
// returns Collection { "a" => 3, "b" => 2 }
concat...collections: ReadonlyCollection<Key, Value>[]) : Collection<Key, Value> (
Combines this collection with others into a new collection. None of the source collections are modified.
const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
differenceother: ReadonlyCollection<Key, any>) : Collection<Key, Value> (
Returns a new collection containing the items where the key is present in this collection but not the other.
const col1 = new Collection([['a', 1], ['b', 2]]);
const col2 = new Collection([['a', 1], ['c', 3]]);
console.log(col1.difference(col2));
// => Collection { 'b' => 2 }
console.log(col2.difference(col1));
// => Collection { 'c' => 3 }
eachfn: (value: Value, key: Key, collection: this) => void) : this (
Identical to Map.forEach(), but returns the collection instead of undefined.
collection
.each(user => console.log(user.username))
.filter(user => user.bot)
.each(user => console.log(user.username));
Obtains the value of the given key if it exists, otherwise sets and returns the value provided by the default value generator.
collection.ensure(guildId, () => defaultGuildConfig);
equalscollection: ReadonlyCollection<Key, Value>) : 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.
Returns: Whether the collections have identical contents
everyNewKey extends Key
>(fn: (value: Value, key: Key, collection: this) => key is NewKey) : this is Collection<NewKey, Value> <
NewKey extends Key
Checks if all items passes a test. Identical in behavior to Array.every().
collection.every(user => !user.bot);
filterNewKey extends Key
>(fn: (value: Value, key: Key, collection: this) => key is NewKey) : Collection<NewKey, Value> <
NewKey extends Key
Identical to Array.filter(), but returns a Collection instead of an Array.
collection.filter(user => user.username === 'Bob');
findNewValue extends Value
>(fn: (value: Value, key: Key, collection: this) => value is NewValue) : NewValue | undefined <
NewValue extends Value
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.
collection.find(user => user.username === 'Bob');
findKeyNewKey extends Key
>(fn: (value: Value, key: Key, collection: this) => key is NewKey) : NewKey | undefined <
NewKey extends Key
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.
collection.findKey(user => user.username === 'Bob');
findLastNewValue extends Value
>(fn: (value: Value, key: Key, collection: this) => value is NewValue) : NewValue | undefined <
NewValue extends Value
Searches for a last item where the given function returns a truthy value. This behaves like Array.findLast().
findLastKeyNewKey extends Key
>(fn: (value: Value, key: Key, collection: this) => key is NewKey) : NewKey | undefined <
NewKey extends Key
Searches for the key of a last item where the given function returns a truthy value. This behaves like Array.findLastIndex(), but returns the key rather than the positional index.
firstValue | undefined () :
Obtains the first value(s) in this collection.
Returns: A single value if no amount is provided or an array of values, starting from the end if amount is negative
firstKeyKey | undefined () :
Obtains the first key(s) in this collection.
Returns: A single key if no amount is provided or an array of keys, starting from the end if amount is negative
flatMapNewValue
>(fn: (value: Value, key: Key, collection: this) => Collection<Key, NewValue>) : Collection<Key, NewValue> <
NewValue
Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to Array.flatMap().
collection.flatMap(guild => guild.members.cache);
hasAll...keys: Key[]) : boolean (
Checks if all of the elements exist in the collection.
Returns: true
if all of the elements exist, false
if at least one does not exist.
hasAny...keys: Key[]) : boolean (
Checks if any of the elements exist in the collection.
Returns: true
if any of the elements exist, false
if none exist.
intersectionother: ReadonlyCollection<Key, any>) : Collection<Key, Value> (
The intersection method returns a new collection containing the items where the key is present in both collections.
const col1 = new Collection([['a', 1], ['b', 2]]);
const col2 = new Collection([['a', 1], ['c', 3]]);
const intersection = col1.intersection(col2);
console.log(col1.intersection(col2));
// => Collection { 'a' => 1 }
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.
lastValue | undefined () :
Obtains the last value(s) in this collection.
Returns: A single value if no amount is provided or an array of values, starting from the start if amount is negative
lastKeyKey | undefined () :
Obtains the last key(s) in this collection.
Returns: A single key if no amount is provided or an array of keys, starting from the start if amount is negative
Maps each item to another value into an array. Identical in behavior to Array.map().
collection.map(user => user.tag);
mapValuesNewValue
>(fn: (value: Value, key: Key, collection: this) => NewValue) : Collection<Key, NewValue> <
NewValue
Maps each item to another value into a collection. Identical in behavior to Array.map().
collection.mapValues(user => user.tag);
mergeOtherValue
ResultValue
>(other: ReadonlyCollection<Key, OtherValue>whenInSelf: (value: Value, key: Key) => Keep<ResultValue>whenInOther: (valueOther: OtherValue, key: Key) => Keep<ResultValue>whenInBoth: (value: Value, valueOther: OtherValue, key: Key) => Keep<ResultValue>) : Collection<Key, ResultValue> <
OtherValue
ResultValue
Merges two Collections together into a new Collection.
// 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 }),
);
// Intersects two collections in a left-biased manner.
coll.merge(
other,
x => ({ keep: false }),
y => ({ keep: false }),
(x, _) => ({ keep: true, value: x }),
);
partitionNewKey extends Key
>(fn: (value: Value, key: Key, collection: this) => key is NewKey) : [Collection<NewKey, Value>, Collection<Exclude<Key, NewKey>, Value>] <
NewKey extends Key
Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.
const [big, small] = collection.partition(guild => guild.memberCount > 250);
randomValue | undefined () :
Obtains unique random value(s) from this collection.
Returns: A single value if no amount is provided or an array of values
randomKeyKey | undefined () :
Obtains unique random key(s) from this collection.
Returns: A single key if no amount is provided or an array
reducefn: (accumulator: Value, value: Value, key: Key, collection: this) => ValueinitialValue?: Value) : Value (
Applies a function to produce a single value. Identical in behavior to Array.reduce().
collection.reduce((acc, guild) => acc + guild.memberCount, 0);
reduceRightfn: (accumulator: Value, value: Value, key: Key, collection: this) => ValueinitialValue?: Value) : Value (
Applies a function to produce a single value. Identical in behavior to Array.reduceRight().
Identical to Array.reverse() but returns a Collection instead of an Array.
Checks if there exists an item that passes a test. Identical in behavior to Array.some().
collection.some(user => user.discriminator === '0000');
sortcompareFunction?: Comparator<Key, Value>) : 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.
collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
symmetricDifferenceOtherValue
>(other: ReadonlyCollection<Key, OtherValue>) : Collection<Key, OtherValue | Value> <
OtherValue
Returns a new collection containing only the items where the keys are present in either collection, but not both.
const col1 = new Collection([['a', 1], ['b', 2]]);
const col2 = new Collection([['a', 1], ['c', 3]]);
const symmetricDifference = col1.symmetricDifference(col2);
console.log(col1.symmetricDifference(col2));
// => Collection { 'b' => 2, 'c' => 3 }
tapfn: (collection: this) => void) : this (
Runs a function on the collection and returns the collection.
collection
.tap(coll => console.log(coll.size))
.filter(user => user.bot)
.tap(coll => console.log(coll.size))
toReversedCollection<Key, Value> () :
Identical to Array.toReversed() but returns a Collection instead of an Array.
toSortedcompareFunction?: Comparator<Key, Value>) : Collection<Key, Value> (
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.
collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
unionOtherValue
>(other: ReadonlyCollection<Key, OtherValue>) : Collection<Key, OtherValue | Value> <
OtherValue
Returns a new collection containing the items where the key is present in either of the collections.
const col1 = new Collection([['a', 1], ['b', 2]]);
const col2 = new Collection([['a', 1], ['b', 3], ['c', 3]]);
const union = col1.union(col2);
console.log(union);
// => Collection { 'a' => 1, 'b' => 2, 'c' => 3 }