@discordjs/collection

  • Version 0.6.0
  • Published
  • 131 kB
  • No dependencies
  • Apache-2.0 license

Install

npm i @discordjs/collection
yarn add @discordjs/collection
pnpm add @discordjs/collection

Overview

Utility data structure used in discord.js

Index

Classes

class Collection

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.

property default

static readonly default: typeof Collection;

    method at

    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.

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

      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()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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) => boolean): 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) => boolean,
    thisArg: This
    ): boolean;
    };
    • 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).

      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) => boolean): 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) => boolean,
    thisArg: This
    ): Collection<K, 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.

      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) => boolean): 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) => boolean,
    thisArg: This
    ): V;
    };
    • 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.

      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) => boolean): 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) => boolean,
    thisArg: This
    ): K;
    };
    • 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.

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

      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()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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) => boolean): [
    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) => boolean,
    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()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) but returns a Collection instead of an Array.

    method some

    some: {
    (fn: (value: V, key: K, collection: this) => boolean): boolean;
    <T>(
    fn: (this: T, value: V, key: K, collection: this) => boolean,
    thisArg: T
    ): 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).

      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 sweep

    sweep: {
    (fn: (value: V, key: K, collection: this) => boolean): number;
    <T>(
    fn: (this: T, value: V, key: K, collection: this) => boolean,
    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[];

      Type Aliases

      type ReadonlyCollection

      type ReadonlyCollection<K, V> = ReadonlyMap<K, V> &
      Omit<
      Collection<K, V>,
      | 'forEach'
      | 'ensure'
      | 'reverse'
      | 'sweep'
      | 'sort'
      | 'get'
      | 'set'
      | 'delete'
      >;
      • Represents an immutable version of a collection

      Package Files (1)

      Dependencies (0)

      No dependencies.

      Dev Dependencies (17)

      Peer Dependencies (0)

      No peer dependencies.

      Badge

      To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

      You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@discordjs/collection.

      • Markdown
        [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@discordjs/collection)
      • HTML
        <a href="https://www.jsdocs.io/package/@discordjs/collection"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>