class Collection

extends

Map
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.

Type Parameters

K

V

at(
index: number
) : V | undefined

Identical to [Array.at()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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.

clone() : Collection<K, V>

Creates an identical shallow copy of this collection.

Examples:const newColl = someColl.clone();

static
combineEntries<

K

V

>(
entries: Iterable<[K, V]>
combine: (firstValue: V, secondValue: V, key: K) => V
) : Collection<K, V>

Creates a Collection from a list of entries.

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

concat(
collections: ReadonlyCollection<K, V>[]
) : Collection<K, V>

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

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

difference<

T

>(
other: ReadonlyCollection<K, T>
) : Collection<K, V | T>

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

each(
fn: (value: V, key: K, collection: this) => void
) : this

Identical to [Map.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/forEach), but returns the collection instead of undefined.

Examples:collection .each(user = console.log(user.username)) .filter(user = user.bot) .each(user = console.log(user.username));

ensure(
key: K
defaultValueGenerator: (key: K, collection: this) => V
) : V

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

Examples:collection.ensure(guildId, () = defaultGuildConfig);

equals(
collection: ReadonlyCollection<K, V>
) : 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

every<

K2 extends K

>(
fn: (value: V, key: K, collection: this) => key is K2
) : this is Collection<K2, V>

Checks if all items passes a test. Identical in behavior to [Array.every()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every).

Examples:collection.every(user = !user.bot);

filter<

K2 extends K

>(
fn: (value: V, key: K, collection: this) => key is K2
) : Collection<K2, V>

Identical to [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), but returns a Collection instead of an Array.

Examples:collection.filter(user = user.username === 'Bob');

find<

V2 extends V

>(
fn: (value: V, key: K, collection: this) => value is V2
) : V2 | undefined

Searches for a single item where the given function returns a truthy value. This behaves like [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details.

Examples:collection.find(user = user.username === 'Bob');

findKey<

K2 extends K

>(
fn: (value: V, key: K, collection: this) => key is K2
) : K2 | undefined

Searches for the key of a single item where the given function returns a truthy value. This behaves like [Array.findIndex()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex), but returns the key rather than the positional index.

Examples:collection.findKey(user = user.username === 'Bob');

first() : V | 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

firstKey() : K | 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

flatMap<

T

>(
fn: (value: V, key: K, collection: this) => Collection<K, T>
) : Collection<K, T>

Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to [Array.flatMap()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap).

Examples:collection.flatMap(guild = guild.members.cache);

hasAll(
keys: K[]
) : 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: K[]
) : boolean

Checks if any of the elements exist in the collection.

Returns: true if any of the elements exist, false if none exist.

intersect<

T

>(
other: ReadonlyCollection<K, T>
) : Collection<K, T>

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

keyAt(
index: number
) : K | undefined

Identical to [Array.at()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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.

last() : V | 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

lastKey() : K | 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

map<

T

>(
fn: (value: V, key: K, collection: this) => T
) : T[]

Maps each item to another value into an array. Identical in behavior to [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).

Examples:collection.map(user = user.tag);

mapValues<

T

>(
fn: (value: V, key: K, collection: this) => T
) : Collection<K, T>

Maps each item to another value into a collection. Identical in behavior to [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).

Examples:collection.mapValues(user = user.tag);

merge<

T

R

>(
other: ReadonlyCollection<K, T>
whenInSelf: (value: V, key: K) => Keep<R>
whenInOther: (valueOther: T, key: K) => Keep<R>
whenInBoth: (value: V, valueOther: T, key: K) => Keep<R>
) : Collection<K, R>

Merges two Collections together into a new Collection.

Examples:// 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 ), );

partition<

K2 extends K

>(
fn: (value: V, key: K, collection: this) => key is K2
) : [Collection<K2, V>, Collection<Exclude<K, K2>, V>]

Partitions the collection into two collections where the first collection contains the items that passed and the second contains the items that failed.

Examples:const [big, small] = collection.partition(guild = guild.memberCount 250);

random() : V | undefined

Obtains unique random value(s) from this collection.

Returns: A single value if no amount is provided or an array of values

randomKey() : K | undefined

Obtains unique random key(s) from this collection.

Returns: A single key if no amount is provided or an array

reduce<

T

>(
fn: (accumulator: T, value: V, key: K, collection: this) => T
initialValue?: T
) : T

Applies a function to produce a single value. Identical in behavior to [Array.reduce()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce).

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

reverse() : this

Identical to [Array.reverse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) but returns a Collection instead of an Array.

some(
fn: (value: V, key: K, collection: this) => boolean
) : boolean

Checks if there exists an item that passes a test. Identical in behavior to [Array.some()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some).

Examples:collection.some(user = user.discriminator === '0000');

sort(
compareFunction?: Comparator<K, V>
) : 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.

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

sorted(
compareFunction?: Comparator<K, V>
) : 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.

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

sweep(
fn: (value: V, key: K, collection: this) => boolean
) : number

Removes items that satisfy the provided filter function.

Returns: The number of removed entries

tap(
fn: (collection: this) => void
) : this

Runs a function on the collection and returns the collection.

Examples:collection .tap(coll = console.log(coll.size)) .filter(user = user.bot) .tap(coll = console.log(coll.size))

toJSON() : V[]