@discordjs/collection

method at

at: (index: number) => 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.

  Parameter index

  The index of the element to obtain

method clone

clone: () => Collection<K, V>;

• Creates an identical shallow copy of this collection.

  Example 1

  const newColl = someColl.clone();

method combineEntries

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.

  Parameter entries

  The list of entries

  Parameter combine

  Function to combine an existing entry with a new one

  Example 1

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

method concat

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

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

  Parameter collections

  Collections to merge

  Example 1

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

method difference

difference: <T>(other: ReadonlyCollection<K, T>) => 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.

  Parameter other

  The other Collection to filter against

method each

each: {
    (fn: (value: V, key: K, collection: this) => void): this;
    <T>(
        fn: (this: T, value: V, key: K, collection: this) => void,
        thisArg: T
    ): this;
};

• Identical to Map.forEach(), but returns the collection instead of undefined.

  Parameter fn

  Function to execute for each element

  Parameter thisArg

  Value to use as this when executing function

  Example 1

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

method ensure

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.

  Parameter key

  The key to get if it exists, or set otherwise

  Parameter defaultValueGenerator

  A function that generates the default value

  Example 1

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

method equals

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.

  Parameter collection

  Collection to compare with

  Returns

  Whether the collections have identical contents

method every

every: {
    <K2 extends K>(
        fn: (value: V, key: K, collection: this) => key is K2
    ): this is Collection<K2, V>;
    <V2 extends V>(
        fn: (value: V, key: K, collection: this) => value is V2
    ): this is Collection<K, V2>;
    (fn: (value: V, key: K, collection: this) => unknown): boolean;
    <This, K2 extends K>(
        fn: (this: This, value: V, key: K, collection: this) => key is K2,
        thisArg: This
    ): this is Collection<K2, V>;
    <This, V2 extends V>(
        fn: (this: This, value: V, key: K, collection: this) => value is V2,
        thisArg: This
    ): this is Collection<K, V2>;
    <This>(
        fn: (this: This, value: V, key: K, collection: this) => unknown,
        thisArg: This
    ): boolean;
};

• Checks if all items passes a test. Identical in behavior to Array.every().

  Parameter fn

  Function used to test (should return a boolean)

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.every(user => !user.bot);

method filter

filter: {
    <K2 extends K>(
        fn: (value: V, key: K, collection: this) => key is K2
    ): Collection<K2, V>;
    <V2 extends V>(
        fn: (value: V, key: K, collection: this) => value is V2
    ): Collection<K, V2>;
    (fn: (value: V, key: K, collection: this) => unknown): Collection<K, V>;
    <This, K2 extends K>(
        fn: (this: This, value: V, key: K, collection: this) => key is K2,
        thisArg: This
    ): Collection<K2, V>;
    <This, V2 extends V>(
        fn: (this: This, value: V, key: K, collection: this) => value is V2,
        thisArg: This
    ): Collection<K, V2>;
    <This>(
        fn: (this: This, value: V, key: K, collection: this) => unknown,
        thisArg: This
    ): Collection<K, V>;
};

• Identical to Array.filter(), but returns a Collection instead of an Array.

  Parameter fn

  The function to test with (should return boolean)

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.filter(user => user.username === 'Bob');

method find

find: {
    <V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2):
        | V2
        | undefined;
    (fn: (value: V, key: K, collection: this) => unknown): V;
    <This, V2 extends V>(
        fn: (this: This, value: V, key: K, collection: this) => value is V2,
        thisArg: This
    ): V2;
    <This>(
        fn: (this: This, value: V, key: K, collection: this) => unknown,
        thisArg: This
    ): V;
};

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

  Parameter fn

  The function to test with (should return boolean)

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.find(user => user.username === 'Bob');

method findKey

findKey: {
    <K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2):
        | K2
        | undefined;
    (fn: (value: V, key: K, collection: this) => unknown): K;
    <This, K2 extends K>(
        fn: (this: This, value: V, key: K, collection: this) => key is K2,
        thisArg: This
    ): K2;
    <This>(
        fn: (this: This, value: V, key: K, collection: this) => unknown,
        thisArg: This
    ): K;
};

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

  Parameter fn

  The function to test with (should return boolean)

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.findKey(user => user.username === 'Bob');

method first

first: { (): V | undefined; (amount: number): V[] };

• Obtains the first value(s) in this collection.

  Parameter amount

  Amount of values to obtain from the beginning

  Returns

  A single value if no amount is provided or an array of values, starting from the end if amount is negative

method firstKey

firstKey: { (): K | undefined; (amount: number): K[] };

• Obtains the first key(s) in this collection.

  Parameter amount

  Amount of keys to obtain from the beginning

  Returns

  A single key if no amount is provided or an array of keys, starting from the end if amount is negative

method flatMap

flatMap: {
    <T>(
        fn: (value: V, key: K, collection: this) => Collection<K, T>
    ): Collection<K, T>;
    <T, This>(
        fn: (this: This, value: V, key: K, collection: this) => Collection<K, T>,
        thisArg: This
    ): Collection<K, T>;
};

• Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to Array.flatMap().

  Parameter fn

  Function that produces a new Collection

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.flatMap(guild => guild.members.cache);

method hasAll

hasAll: (...keys: K[]) => boolean;

• Checks if all of the elements exist in the collection.

  Parameter keys

  The keys of the elements to check for

  Returns

  true if all of the elements exist, false if at least one does not exist.

method hasAny

hasAny: (...keys: K[]) => boolean;

• Checks if any of the elements exist in the collection.

  Parameter keys

  The keys of the elements to check for

  Returns

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

method intersect

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.

  Parameter other

  The other Collection to filter against

method keyAt

keyAt: (index: number) => 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.

  Parameter index

  The index of the key to obtain

method last

last: { (): V | undefined; (amount: number): V[] };

• Obtains the last value(s) in this collection.

  Parameter amount

  Amount of values to obtain from the end

  Returns

  A single value if no amount is provided or an array of values, starting from the start if amount is negative

method lastKey

lastKey: { (): K | undefined; (amount: number): K[] };

• Obtains the last key(s) in this collection.

  Parameter amount

  Amount of keys to obtain from the end

  Returns

  A single key if no amount is provided or an array of keys, starting from the start if amount is negative

method map

map: {
    <T>(fn: (value: V, key: K, collection: this) => T): T[];
    <This, T>(
        fn: (this: This, value: V, key: K, collection: this) => T,
        thisArg: This
    ): T[];
};

• Maps each item to another value into an array. Identical in behavior to Array.map().

  Parameter fn

  Function that produces an element of the new array, taking three arguments

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.map(user => user.tag);

method mapValues

mapValues: {
    <T>(fn: (value: V, key: K, collection: this) => T): Collection<K, T>;
    <This, T>(
        fn: (this: This, value: V, key: K, collection: this) => T,
        thisArg: This
    ): Collection<K, T>;
};

• Maps each item to another value into a collection. Identical in behavior to Array.map().

  Parameter fn

  Function that produces an element of the new collection, taking three arguments

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.mapValues(user => user.tag);

method merge

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.

  Parameter other

  The other Collection to merge with

  Parameter whenInSelf

  Function getting the result if the entry only exists in this Collection

  Parameter whenInOther

  Function getting the result if the entry only exists in the other Collection

  Parameter whenInBoth

  Function getting the result if the entry exists in both Collections

  Example 1

  // 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 2

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

method partition

partition: {
    <K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): [
        Collection<K2, V>,
        Collection<Exclude<K, K2>, V>
    ];
    <V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): [
        Collection<K, V2>,
        Collection<K, Exclude<V, V2>>
    ];
    (fn: (value: V, key: K, collection: this) => unknown): [
        Collection<K, V>,
        Collection<K, V>
    ];
    <This, K2 extends K>(
        fn: (this: This, value: V, key: K, collection: this) => key is K2,
        thisArg: This
    ): [Collection<K2, V>, Collection<Exclude<K, K2>, V>];
    <This, V2 extends V>(
        fn: (this: This, value: V, key: K, collection: this) => value is V2,
        thisArg: This
    ): [Collection<K, V2>, Collection<K, Exclude<V, V2>>];
    <This>(
        fn: (this: This, value: V, key: K, collection: this) => unknown,
        thisArg: This
    ): [Collection<K, V>, Collection<K, V>];
};

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

  Parameter fn

  Function used to test (should return a boolean)

  Parameter thisArg

  Value to use as this when executing function

  Example 1

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

method random

random: { (): V | undefined; (amount: number): V[] };

• Obtains unique random value(s) from this collection.

  Parameter amount

  Amount of values to obtain randomly

  Returns

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

method randomKey

randomKey: { (): K | undefined; (amount: number): K[] };

• Obtains unique random key(s) from this collection.

  Parameter amount

  Amount of keys to obtain randomly

  Returns

  A single key if no amount is provided or an array

method reduce

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().

  Parameter fn

  Function used to reduce, taking four arguments; accumulator, currentValue, currentKey, and collection

  Parameter initialValue

  Starting value for the accumulator

  Example 1

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

method reverse

reverse: () => this;

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

method some

some: {
    (fn: (value: V, key: K, collection: this) => unknown): boolean;
    <T>(
        fn: (this: T, value: V, key: K, collection: this) => unknown,
        thisArg: T
    ): boolean;
};

• Checks if there exists an item that passes a test. Identical in behavior to Array.some().

  Parameter fn

  Function used to test (should return a boolean)

  Parameter thisArg

  Value to use as this when executing function

  Example 1

  collection.some(user => user.discriminator === '0000');

method sort

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.

  Parameter compareFunction

  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.

  Example 1

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

method sorted

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.

  Parameter compareFunction

  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.

  Example 1

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

method subtract

subtract: <T>(other: ReadonlyCollection<K, T>) => 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.

  Parameter other

  The other Collection to filter against

method sweep

sweep: {
    (fn: (value: V, key: K, collection: this) => unknown): number;
    <T>(
        fn: (this: T, value: V, key: K, collection: this) => unknown,
        thisArg: T
    ): number;
};

• Removes items that satisfy the provided filter function.

  Parameter fn

  Function used to test (should return a boolean)

  Parameter thisArg

  Value to use as this when executing function

  Returns

  The number of removed entries

method tap

tap: {
    (fn: (collection: this) => void): this;
    <T>(fn: (this: T, collection: this) => void, thisArg: T): this;
};

• Runs a function on the collection and returns the collection.

  Parameter fn

  Function to execute

  Parameter thisArg

  Value to use as this when executing function

  Example 1

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

method toJSON

toJSON: () => V[];