@discordjs/collection 1.4.0-dev.1677499493-ffdb197.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+# [@discordjs/collection@1.4.0](https://github.com/discordjs/discord.js/compare/@discordjs/collection@1.3.0...@discordjs/collection@1.4.0) - (2023-03-12)
+
+## Documentation
+
+- Fix version export (#9049) ([8b70f49](https://github.com/discordjs/discord.js/commit/8b70f497a1207e30edebdecd12b926c981c13d28))
+
+## Features
+
+- **website:** Add support for source file links (#9048) ([f6506e9](https://github.com/discordjs/discord.js/commit/f6506e99c496683ee0ab67db0726b105b929af38))
+
+## Refactor
+
+- Compare with `undefined` directly (#9191) ([869153c](https://github.com/discordjs/discord.js/commit/869153c3fdf155783e7c0ecebd3627b087c3a026))
+
 # [@discordjs/collection@1.3.0](https://github.com/discordjs/discord.js/compare/@discordjs/collection@1.2.0...@discordjs/collection@1.3.0) - (2022-11-28)
 
 ## Bug Fixes

package/dist/index.js

@@ -28,6 +28,16 @@ module.exports = __toCommonJS(src_exports);
 
 // src/collection.ts
 var Collection = class extends Map {
+  /**
+  * Obtains the value of the given key if it exists, otherwise sets and returns the value provided by the default value generator.
+  *
+  * @param key - The key to get if it exists, or set otherwise
+  * @param defaultValueGenerator - A function that generates the default value
+  * @example
+  * ```ts
+  * collection.ensure(guildId, () => defaultGuildConfig);
+  * ```
+  */
   ensure(key, defaultValueGenerator) {
     if (this.has(key))
       return this.get(key);
@@ -37,33 +47,51 @@ var Collection = class extends Map {
     this.set(key, defaultValue);
     return defaultValue;
   }
+  /**
+  * Checks if all of the elements exist in the collection.
+  *
+  * @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) {
     return keys.every((k) => super.has(k));
   }
+  /**
+  * Checks if any of the elements exist in the collection.
+  *
+  * @param keys - The keys of the elements to check for
+  * @returns `true` if any of the elements exist, `false` if none exist.
+  */
   hasAny(...keys) {
     return keys.some((k) => super.has(k));
   }
   first(amount) {
-    if (typeof amount === "undefined")
+    if (amount === void 0)
       return this.values().next().value;
     if (amount < 0)
       return this.last(amount * -1);
     amount = Math.min(this.size, amount);
     const iter = this.values();
-    return Array.from({ length: amount }, () => iter.next().value);
+    return Array.from({
+      length: amount
+    }, () => iter.next().value);
   }
   firstKey(amount) {
-    if (typeof amount === "undefined")
+    if (amount === void 0)
       return this.keys().next().value;
     if (amount < 0)
       return this.lastKey(amount * -1);
     amount = Math.min(this.size, amount);
     const iter = this.keys();
-    return Array.from({ length: amount }, () => iter.next().value);
+    return Array.from({
+      length: amount
+    }, () => iter.next().value);
   }
   last(amount) {
-    const arr = [...this.values()];
-    if (typeof amount === "undefined")
+    const arr = [
+      ...this.values()
+    ];
+    if (amount === void 0)
       return arr[arr.length - 1];
     if (amount < 0)
       return this.first(amount * -1);
@@ -72,8 +100,10 @@ var Collection = class extends Map {
     return arr.slice(-amount);
   }
   lastKey(amount) {
-    const arr = [...this.keys()];
-    if (typeof amount === "undefined")
+    const arr = [
+      ...this.keys()
+    ];
+    if (amount === void 0)
       return arr[arr.length - 1];
     if (amount < 0)
       return this.firstKey(amount * -1);
@@ -81,40 +111,66 @@ var Collection = class extends Map {
       return [];
     return arr.slice(-amount);
   }
+  /**
+  * Identical to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at | 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) {
     index = Math.floor(index);
-    const arr = [...this.values()];
+    const arr = [
+      ...this.values()
+    ];
     return arr.at(index);
   }
+  /**
+  * Identical to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at | 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) {
     index = Math.floor(index);
-    const arr = [...this.keys()];
+    const arr = [
+      ...this.keys()
+    ];
     return arr.at(index);
   }
   random(amount) {
-    const arr = [...this.values()];
-    if (typeof amount === "undefined")
+    const arr = [
+      ...this.values()
+    ];
+    if (amount === void 0)
       return arr[Math.floor(Math.random() * arr.length)];
     if (!arr.length || !amount)
       return [];
-    return Array.from(
-      { length: Math.min(amount, arr.length) },
-      () => arr.splice(Math.floor(Math.random() * arr.length), 1)[0]
-    );
+    return Array.from({
+      length: Math.min(amount, arr.length)
+    }, () => arr.splice(Math.floor(Math.random() * arr.length), 1)[0]);
   }
   randomKey(amount) {
-    const arr = [...this.keys()];
-    if (typeof amount === "undefined")
+    const arr = [
+      ...this.keys()
+    ];
+    if (amount === void 0)
       return arr[Math.floor(Math.random() * arr.length)];
     if (!arr.length || !amount)
       return [];
-    return Array.from(
-      { length: Math.min(amount, arr.length) },
-      () => arr.splice(Math.floor(Math.random() * arr.length), 1)[0]
-    );
-  }
+    return Array.from({
+      length: Math.min(amount, arr.length)
+    }, () => arr.splice(Math.floor(Math.random() * arr.length), 1)[0]);
+  }
+  /**
+  * Identical to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse | Array.reverse()}
+  * but returns a Collection instead of an Array.
+  */
   reverse() {
-    const entries = [...this.entries()].reverse();
+    const entries = [
+      ...this.entries()
+    ].reverse();
     this.clear();
     for (const [key, value] of entries)
       this.set(key, value);
@@ -123,7 +179,7 @@ var Collection = class extends Map {
   find(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     for (const [key, val] of this) {
       if (fn(val, key, this))
@@ -134,7 +190,7 @@ var Collection = class extends Map {
   findKey(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     for (const [key, val] of this) {
       if (fn(val, key, this))
@@ -145,7 +201,7 @@ var Collection = class extends Map {
   sweep(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     const previousSize = this.size;
     for (const [key, val] of this) {
@@ -157,7 +213,7 @@ var Collection = class extends Map {
   filter(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     const results = new this.constructor[Symbol.species]();
     for (const [key, val] of this) {
@@ -169,7 +225,7 @@ var Collection = class extends Map {
   partition(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     const results = [
       new this.constructor[Symbol.species](),
@@ -191,10 +247,12 @@ var Collection = class extends Map {
   map(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     const iter = this.entries();
-    return Array.from({ length: this.size }, () => {
+    return Array.from({
+      length: this.size
+    }, () => {
       const [key, value] = iter.next().value;
       return fn(value, key, this);
     });
@@ -202,7 +260,7 @@ var Collection = class extends Map {
   mapValues(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     const coll = new this.constructor[Symbol.species]();
     for (const [key, val] of this)
@@ -212,7 +270,7 @@ var Collection = class extends Map {
   some(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     for (const [key, val] of this) {
       if (fn(val, key, this))
@@ -223,7 +281,7 @@ var Collection = class extends Map {
   every(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     for (const [key, val] of this) {
       if (!fn(val, key, this))
@@ -231,11 +289,23 @@ var Collection = class extends Map {
     }
     return true;
   }
+  /**
+  * Applies a function to produce a single value. Identical in behavior to
+  * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce | Array.reduce()}.
+  *
+  * @param fn - Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
+  * and `collection`
+  * @param initialValue - Starting value for the accumulator
+  * @example
+  * ```ts
+  * collection.reduce((acc, guild) => acc + guild.memberCount, 0);
+  * ```
+  */
   reduce(fn, initialValue) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
     let accumulator;
-    if (typeof initialValue !== "undefined") {
+    if (initialValue !== void 0) {
       accumulator = initialValue;
       for (const [key, val] of this)
         accumulator = fn(accumulator, val, key, this);
@@ -264,14 +334,31 @@ var Collection = class extends Map {
   tap(fn, thisArg) {
     if (typeof fn !== "function")
       throw new TypeError(`${fn} is not a function`);
-    if (typeof thisArg !== "undefined")
+    if (thisArg !== void 0)
       fn = fn.bind(thisArg);
     fn(this);
     return this;
   }
+  /**
+  * Creates an identical shallow copy of this collection.
+  *
+  * @example
+  * ```ts
+  * const newColl = someColl.clone();
+  * ```
+  */
   clone() {
     return new this.constructor[Symbol.species](this);
   }
+  /**
+  * Combines this collection with others into a new collection. None of the source collections are modified.
+  *
+  * @param collections - Collections to merge
+  * @example
+  * ```ts
+  * const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
+  * ```
+  */
   concat(...collections) {
     const newColl = this.clone();
     for (const coll of collections) {
@@ -280,6 +367,14 @@ var Collection = class extends Map {
     }
     return newColl;
   }
+  /**
+  * 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 to compare with
+  * @returns Whether the collections have identical contents
+  */
   equals(collection) {
     if (!collection)
       return false;
@@ -294,8 +389,22 @@ var Collection = class extends Map {
     }
     return true;
   }
+  /**
+  * 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 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
+  * ```ts
+  * collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
+  * ```
+  */
   sort(compareFunction = Collection.defaultSort) {
-    const entries = [...this.entries()];
+    const entries = [
+      ...this.entries()
+    ];
     entries.sort((a, b) => compareFunction(a[1], b[1], a[0], b[0]));
     super.clear();
     for (const [k, v] of entries) {
@@ -303,6 +412,11 @@ var Collection = class extends Map {
     }
     return this;
   }
+  /**
+  * The intersect method returns a new structure containing items where the keys and values are present in both original structures.
+  *
+  * @param other - The other Collection to filter against
+  */
   intersect(other) {
     const coll = new this.constructor[Symbol.species]();
     for (const [k, v] of other) {
@@ -312,6 +426,11 @@ var Collection = class extends Map {
     }
     return coll;
   }
+  /**
+  * The subtract method returns a new structure containing items where the keys and values of the original structure are not present in the other.
+  *
+  * @param other - The other Collection to filter against
+  */
   subtract(other) {
     const coll = new this.constructor[Symbol.species]();
     for (const [k, v] of this) {
@@ -321,6 +440,11 @@ var Collection = class extends Map {
     }
     return coll;
   }
+  /**
+  * 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 other - The other Collection to filter against
+  */
   difference(other) {
     const coll = new this.constructor[Symbol.species]();
     for (const [k, v] of other) {
@@ -333,9 +457,40 @@ var Collection = class extends Map {
     }
     return coll;
   }
+  /**
+  * Merges two Collections together into a new Collection.
+  *
+  * @param other - The other Collection to merge with
+  * @param whenInSelf - Function getting the result if the entry only exists in this Collection
+  * @param whenInOther - Function getting the result if the entry only exists in the other Collection
+  * @param whenInBoth - Function getting the result if the entry exists in both Collections
+  * @example
+  * ```ts
+  * // 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
+  * ```ts
+  * // Intersects two collections in a left-biased manner.
+  * coll.merge(
+  *  other,
+  *  x => ({ keep: false }),
+  *  y => ({ keep: false }),
+  *  (x, _) => ({ keep: true, value: x }),
+  * );
+  * ```
+  */
   merge(other, whenInSelf, whenInOther, whenInBoth) {
     const coll = new this.constructor[Symbol.species]();
-    const keys = /* @__PURE__ */ new Set([...this.keys(), ...other.keys()]);
+    const keys = /* @__PURE__ */ new Set([
+      ...this.keys(),
+      ...other.keys()
+    ]);
     for (const k of keys) {
       const hasInSelf = this.has(k);
       const hasInOther = other.has(k);
@@ -355,15 +510,41 @@ var Collection = class extends Map {
     }
     return coll;
   }
+  /**
+  * 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 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
+  * ```ts
+  * collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
+  * ```
+  */
   sorted(compareFunction = Collection.defaultSort) {
     return new this.constructor[Symbol.species](this).sort((av, bv, ak, bk) => compareFunction(av, bv, ak, bk));
   }
   toJSON() {
-    return [...this.values()];
+    return [
+      ...this.values()
+    ];
   }
   static defaultSort(firstValue, secondValue) {
     return Number(firstValue > secondValue) || Number(firstValue === secondValue) - 1;
   }
+  /**
+  * Creates a Collection from a list of entries.
+  *
+  * @param entries - The list of entries
+  * @param combine - Function to combine an existing entry with a new one
+  * @example
+  * ```ts
+  * Collection.combineEntries([["a", 1], ["b", 2], ["a", 2]], (x, y) => x + y);
+  * // returns Collection { "a" => 3, "b" => 2 }
+  * ```
+  */
   static combineEntries(entries, combine) {
     const coll = new Collection();
     for (const [k, v] of entries) {
@@ -379,7 +560,7 @@ var Collection = class extends Map {
 __name(Collection, "Collection");
 
 // src/index.ts
-var version = "1.4.0-dev.1677499493-ffdb197.0";
+var version = "[VI]{{inject}}[/VI]";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Collection,