@discordjs/collection 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,111 +1,115 @@
-export interface CollectionConstructor {
+/**
+ * @internal
+ */
+interface CollectionConstructor {
     new (): Collection<unknown, unknown>;
     new <K, V>(entries?: ReadonlyArray<readonly [K, V]> | null): Collection<K, V>;
     new <K, V>(iterable: Iterable<readonly [K, V]>): Collection<K, V>;
     readonly prototype: Collection<unknown, unknown>;
     readonly [Symbol.species]: CollectionConstructor;
 }
+/**
+ * Separate interface for the constructor so that emitted js does not have a constructor that overwrites itself
+ *
+ * @internal
+ */
+interface Collection<K, V> extends Map<K, V> {
+    constructor: CollectionConstructor;
+}
 /**
  * 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}
- * @property {number} size - The amount of elements in this collection.
  */
-export declare class Collection<K, V> extends Map<K, V> {
+declare class Collection<K, V> extends Map<K, V> {
     static readonly default: typeof Collection;
-    ['constructor']: CollectionConstructor;
-    /**
-     * Identical to [Map.get()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get).
-     * Gets an element with the specified key, and returns its value, or `undefined` if the element does not exist.
-     * @param {*} key - The key to get from this collection
-     * @returns {* | undefined}
-     */
-    get(key: K): V | undefined;
-    /**
-     * Identical to [Map.set()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/set).
-     * Sets a new element in the collection with the specified key and value.
-     * @param {*} key - The key of the element to add
-     * @param {*} value - The value of the element to add
-     * @returns {Collection}
-     */
-    set(key: K, value: V): this;
-    /**
-     * Identical to [Map.has()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/has).
-     * Checks if an element exists in the collection.
-     * @param {*} key - The key of the element to check for
-     * @returns {boolean} `true` if the element exists, `false` if it does not exist.
-     */
-    has(key: K): boolean;
-    /**
-     * Identical to [Map.delete()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/delete).
-     * Deletes an element from the collection.
-     * @param {*} key - The key to delete from the collection
-     * @returns {boolean} `true` if the element was removed, `false` if the element does not exist.
-     */
-    delete(key: K): boolean;
-    /**
-     * Identical to [Map.clear()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/clear).
-     * Removes all elements from the collection.
-     * @returns {undefined}
-     */
-    clear(): void;
     /**
      * Checks if all of the elements exist in the collection.
-     * @param {...*} keys - The keys of the elements to check for
-     * @returns {boolean} `true` if all of the elements exist, `false` if at least one does not exist.
+     *
+     * @param 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.
      */
     hasAll(...keys: K[]): boolean;
     /**
      * Checks if any of the elements exist in the collection.
-     * @param {...*} keys - The keys of the elements to check for
-     * @returns {boolean} `true` if any of the elements exist, `false` if none exist.
+     *
+     * @param keys - The keys of the elements to check for
+     *
+     * @returns `true` if any of the elements exist, `false` if none exist.
      */
     hasAny(...keys: K[]): boolean;
     /**
      * Obtains the first value(s) in this collection.
-     * @param {number} [amount] Amount of values to obtain from the beginning
-     * @returns {*|Array<*>} A single value if no amount is provided or an array of values, starting from the end if
-     * amount is negative
+     *
+     * @param 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
      */
     first(): V | undefined;
     first(amount: number): V[];
     /**
      * Obtains the first key(s) in this collection.
-     * @param {number} [amount] Amount of keys to obtain from the beginning
-     * @returns {*|Array<*>} A single key if no amount is provided or an array of keys, starting from the end if
+     *
+     * @param 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
      */
     firstKey(): K | undefined;
     firstKey(amount: number): K[];
     /**
      * Obtains the last value(s) in this collection.
-     * @param {number} [amount] Amount of values to obtain from the end
-     * @returns {*|Array<*>} A single value if no amount is provided or an array of values, starting from the start if
+     *
+     * @param 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
      */
     last(): V | undefined;
     last(amount: number): V[];
     /**
      * Obtains the last key(s) in this collection.
-     * @param {number} [amount] Amount of keys to obtain from the end
-     * @returns {*|Array<*>} A single key if no amount is provided or an array of keys, starting from the start if
+     *
+     * @param 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
      */
     lastKey(): K | undefined;
     lastKey(amount: number): K[];
+    /**
+     * 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.
+     *
+     * @param index The index of the element to obtain
+     */
+    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 key at a given index, allowing for positive and negative integers.
+     * Negative integers count back from the last item in the collection.
+     *
+     * @param index The index of the key to obtain
+     */
+    keyAt(index?: number): K | undefined;
     /**
      * Obtains unique random value(s) from this collection.
-     * @param {number} [amount] Amount of values to obtain randomly
-     * @returns {*|Array<*>} A single value if no amount is provided or an array of values
+     *
+     * @param amount Amount of values to obtain randomly
+     *
+     * @returns A single value if no amount is provided or an array of values
      */
-    random(): V;
+    random(): V | undefined;
     random(amount: number): V[];
     /**
      * Obtains unique random key(s) from this collection.
-     * @param {number} [amount] Amount of keys to obtain randomly
-     * @returns {*|Array<*>} A single key if no amount is provided or an array
+     *
+     * @param amount Amount of keys to obtain randomly
+     *
+     * @returns A single key if no amount is provided or an array
      */
-    randomKey(): K;
+    randomKey(): K | undefined;
     randomKey(amount: number): K[];
     /**
      * Searches for a single item where the given function returns a truthy value. This behaves like
@@ -113,10 +117,12 @@ export declare class Collection<K, V> extends Map<K, V> {
      * <warn>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.</warn>
-     * @param {Function} fn The function to test with (should return boolean)
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {*}
-     * @example collection.find(user => user.username === 'Bob');
+     *
+     * @param fn The function to test with (should return boolean)
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.find(user => user.username === 'Bob');
      */
     find<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): V2 | undefined;
     find(fn: (value: V, key: K, collection: this) => boolean): V | undefined;
@@ -126,10 +132,12 @@ export declare class Collection<K, V> extends Map<K, V> {
      * 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.
-     * @param {Function} fn The function to test with (should return boolean)
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {*}
-     * @example collection.findKey(user => user.username === 'Bob');
+     *
+     * @param fn The function to test with (should return boolean)
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.findKey(user => user.username === 'Bob');
      */
     findKey<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): K2 | undefined;
     findKey(fn: (value: V, key: K, collection: this) => boolean): K | undefined;
@@ -137,9 +145,11 @@ export declare class Collection<K, V> extends Map<K, V> {
     findKey<This>(fn: (this: This, value: V, key: K, collection: this) => boolean, thisArg: This): K | undefined;
     /**
      * Removes items that satisfy the provided filter function.
-     * @param {Function} fn Function used to test (should return a boolean)
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {number} The number of removed entries
+     *
+     * @param fn Function used to test (should return a boolean)
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @returns The number of removed entries
      */
     sweep(fn: (value: V, key: K, collection: this) => boolean): number;
     sweep<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): number;
@@ -147,10 +157,12 @@ export declare class Collection<K, V> extends Map<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.
-     * @param {Function} fn The function to test with (should return boolean)
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {Collection}
-     * @example collection.filter(user => user.username === 'Bob');
+     *
+     * @param fn The function to test with (should return boolean)
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.filter(user => user.username === 'Bob');
      */
     filter<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): Collection<K2, V>;
     filter<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): Collection<K, V2>;
@@ -161,10 +173,12 @@ export declare class Collection<K, V> extends Map<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.
-     * @param {Function} fn Function used to test (should return a boolean)
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {Collection[]}
-     * @example const [big, small] = collection.partition(guild => guild.memberCount > 250);
+     *
+     * @param fn Function used to test (should return a boolean)
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * const [big, small] = collection.partition(guild => guild.memberCount > 250);
      */
     partition<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): [Collection<K2, V>, Collection<Exclude<K, K2>, V>];
     partition<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): [Collection<K, V2>, Collection<K, Exclude<V, V2>>];
@@ -175,50 +189,60 @@ export declare class Collection<K, V> extends Map<K, V> {
     /**
      * 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).
-     * @param {Function} fn Function that produces a new Collection
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {Collection}
-     * @example collection.flatMap(guild => guild.members.cache);
+     *
+     * @param fn Function that produces a new Collection
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.flatMap(guild => guild.members.cache);
      */
     flatMap<T>(fn: (value: V, key: K, collection: this) => Collection<K, T>): Collection<K, T>;
     flatMap<T, This>(fn: (this: This, value: V, key: K, collection: this) => Collection<K, T>, thisArg: This): Collection<K, 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).
-     * @param {Function} fn Function that produces an element of the new array, taking three arguments
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {Array}
-     * @example collection.map(user => user.tag);
+     *
+     * @param fn Function that produces an element of the new array, taking three arguments
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.map(user => user.tag);
      */
     map<T>(fn: (value: V, key: K, collection: this) => T): T[];
     map<This, T>(fn: (this: This, value: V, key: K, collection: this) => T, thisArg: This): 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).
-     * @param {Function} fn Function that produces an element of the new collection, taking three arguments
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {Collection}
-     * @example collection.mapValues(user => user.tag);
+     *
+     * @param fn Function that produces an element of the new collection, taking three arguments
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.mapValues(user => user.tag);
      */
     mapValues<T>(fn: (value: V, key: K, collection: this) => T): Collection<K, T>;
     mapValues<This, T>(fn: (this: This, value: V, key: K, collection: this) => T, thisArg: This): Collection<K, T>;
     /**
      * 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).
-     * @param {Function} fn Function used to test (should return a boolean)
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {boolean}
-     * @example collection.some(user => user.discriminator === '0000');
+     *
+     * @param fn Function used to test (should return a boolean)
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.some(user => user.discriminator === '0000');
      */
     some(fn: (value: V, key: K, collection: this) => boolean): boolean;
     some<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): 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).
-     * @param {Function} fn Function used to test (should return a boolean)
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {boolean}
-     * @example collection.every(user => !user.bot);
+     *
+     * @param fn Function used to test (should return a boolean)
+     * @param thisArg Value to use as `this` when executing function
+     *
+     * @example
+     * collection.every(user => !user.bot);
      */
     every<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): this is Collection<K2, V>;
     every<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): this is Collection<K, V2>;
@@ -229,20 +253,23 @@ export declare class Collection<K, V> extends Map<K, V> {
     /**
      * 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).
-     * @param {Function} fn Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
+     *
+     * @param fn Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
      * and `collection`
-     * @param {*} [initialValue] Starting value for the accumulator
-     * @returns {*}
-     * @example collection.reduce((acc, guild) => acc + guild.memberCount, 0);
+     * @param initialValue Starting value for the accumulator
+     *
+     * @example
+     * collection.reduce((acc, guild) => acc + guild.memberCount, 0);
      */
     reduce<T>(fn: (accumulator: T, value: V, key: K, collection: this) => T, initialValue?: T): T;
     /**
      * 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.
-     * @param {Function} fn Function to execute for each element
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {Collection}
+     *
+     * @param fn Function to execute for each element
+     * @param thisArg Value to use as `this` when executing function
+     *
      * @example
      * collection
      *  .each(user => console.log(user.username))
@@ -253,9 +280,10 @@ export declare class Collection<K, V> extends Map<K, V> {
     each<T>(fn: (this: T, value: V, key: K, collection: this) => void, thisArg: T): this;
     /**
      * Runs a function on the collection and returns the collection.
-     * @param {Function} fn Function to execute
-     * @param {*} [thisArg] Value to use as `this` when executing function
-     * @returns {Collection}
+     *
+     * @param fn Function to execute
+     * @param thisArg Value to use as `this` when executing function
+     *
      * @example
      * collection
      *  .tap(coll => console.log(coll.size))
@@ -266,61 +294,73 @@ export declare class Collection<K, V> extends Map<K, V> {
     tap<T>(fn: (this: T, collection: this) => void, thisArg: T): this;
     /**
      * Creates an identical shallow copy of this collection.
-     * @returns {Collection}
-     * @example const newColl = someColl.clone();
+     *
+     * @example
+     * const newColl = someColl.clone();
      */
     clone(): Collection<K, V>;
     /**
      * Combines this collection with others into a new collection. None of the source collections are modified.
-     * @param {...Collection} collections Collections to merge
-     * @returns {Collection}
-     * @example const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
+     *
+     * @param collections Collections to merge
+     *
+     * @example
+     * const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
      */
     concat(...collections: Collection<K, V>[]): Collection<K, V>;
     /**
      * 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.
-     * @param {Collection} collection Collection to compare with
-     * @returns {boolean} Whether the collections have identical contents
+     *
+     * @param collection Collection to compare with
+     *
+     * @returns Whether the collections have identical contents
      */
     equals(collection: Collection<K, V>): boolean;
     /**
      * 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.
-     * @param {Function} [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.
-     * @returns {Collection}
-     * @example collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
+     *
+     * @param 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
+     * collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
      */
     sort(compareFunction?: Comparator<K, V>): this;
     /**
      * The intersect method returns a new structure containing items where the keys are present in both original structures.
-     * @param {Collection} other The other Collection to filter against
-     * @returns {Collection}
+     *
+     * @param other The other Collection to filter against
      */
     intersect(other: Collection<K, V>): Collection<K, 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.
-     * @param {Collection} other The other Collection to filter against
-     * @returns {Collection}
+     *
+     * @param other The other Collection to filter against
      */
     difference(other: Collection<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.
-     * @param {Function} [compareFunction] Specifies a function that defines the sort order.
+     *
+     * @param 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.
-     * @returns {Collection}
-     * @example collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
+     *
+     * @example
+     * collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
      */
     sorted(compareFunction?: Comparator<K, V>): Collection<K, V>;
     toJSON(): V[];
     private static defaultSort;
 }
-export declare type Comparator<K, V> = (firstValue: V, secondValue: V, firstKey: K, secondKey: K) => number;
-export default Collection;
+/**
+ * @internal
+ */
+declare type Comparator<K, V> = (firstValue: V, secondValue: V, firstKey: K, secondKey: K) => number;
+
+export { Collection, CollectionConstructor, Comparator, Collection as default };