mirror of
https://github.com/discordjs/discord.js.git
synced 2026-03-09 16:13:31 +01:00
feat: external collection package (#2934)
* Use external collection package * Complete typings * Document properly base collection class * Add clone since sort is now in-place * Update for latest changes to package * Fix whitespace * Update docs link * Oops * Update Collection.js * Update index.d.ts
This commit is contained in:
1Computer1
@@ -35,6 +35,7 @@
|
||||
"runkitExampleFilename": "./docs/examples/ping.js",
|
||||
"unpkg": "./webpack/discord.min.js",
|
||||
"dependencies": {
|
||||
"@discordjs/collection": "^0.1.0",
|
||||
"abort-controller": "^3.0.0",
|
||||
"form-data": "^2.3.3",
|
||||
"node-fetch": "^2.3.0",
|
||||
|
||||
@@ -1,423 +1,22 @@
|
||||
'use strict';
|
||||
|
||||
const BaseCollection = require('@discordjs/collection');
|
||||
const Util = require('./Util');
|
||||
|
||||
/**
|
||||
* 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}
|
||||
* @extends {BaseCollection}
|
||||
*/
|
||||
class Collection extends Map {
|
||||
constructor(iterable) {
|
||||
super(iterable);
|
||||
|
||||
/**
|
||||
* Cached array for the `array()` method - will be reset to `null` whenever `set()` or `delete()` are called
|
||||
* @name Collection#_array
|
||||
* @type {?Array}
|
||||
* @private
|
||||
*/
|
||||
Object.defineProperty(this, '_array', { value: null, writable: true, configurable: true });
|
||||
|
||||
/**
|
||||
* Cached array for the `keyArray()` method - will be reset to `null` whenever `set()` or `delete()` are called
|
||||
* @name Collection#_keyArray
|
||||
* @type {?Array}
|
||||
* @private
|
||||
*/
|
||||
Object.defineProperty(this, '_keyArray', { value: null, writable: true, configurable: true });
|
||||
}
|
||||
|
||||
set(key, val) {
|
||||
this._array = null;
|
||||
this._keyArray = null;
|
||||
return super.set(key, val);
|
||||
}
|
||||
|
||||
delete(key) {
|
||||
this._array = null;
|
||||
this._keyArray = null;
|
||||
return super.delete(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an ordered array of the values of this collection, and caches it internally. The array will only be
|
||||
* reconstructed if an item is added to or removed from the collection, or if you change the length of the array
|
||||
* itself. If you don't want this caching behavior, use `[...collection.values()]` or
|
||||
* `Array.from(collection.values())` instead.
|
||||
* @returns {Array}
|
||||
*/
|
||||
array() {
|
||||
if (!this._array || this._array.length !== this.size) this._array = [...this.values()];
|
||||
return this._array;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an ordered array of the keys of this collection, and caches it internally. The array will only be
|
||||
* reconstructed if an item is added to or removed from the collection, or if you change the length of the array
|
||||
* itself. If you don't want this caching behavior, use `[...collection.keys()]` or
|
||||
* `Array.from(collection.keys())` instead.
|
||||
* @returns {Array}
|
||||
*/
|
||||
keyArray() {
|
||||
if (!this._keyArray || this._keyArray.length !== this.size) this._keyArray = [...this.keys()];
|
||||
return this._keyArray;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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
|
||||
*/
|
||||
first(amount) {
|
||||
if (typeof amount === 'undefined') return this.values().next().value;
|
||||
if (amount < 0) return this.last(amount * -1);
|
||||
amount = Math.min(this.size, amount);
|
||||
const arr = new Array(amount);
|
||||
const iter = this.values();
|
||||
for (let i = 0; i < amount; i++) arr[i] = iter.next().value;
|
||||
return arr;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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
|
||||
* amount is negative
|
||||
*/
|
||||
firstKey(amount) {
|
||||
if (typeof amount === 'undefined') return this.keys().next().value;
|
||||
if (amount < 0) return this.lastKey(amount * -1);
|
||||
amount = Math.min(this.size, amount);
|
||||
const arr = new Array(amount);
|
||||
const iter = this.keys();
|
||||
for (let i = 0; i < amount; i++) arr[i] = iter.next().value;
|
||||
return arr;
|
||||
}
|
||||
|
||||
/**
|
||||
* Obtains the last value(s) in this collection. This relies on {@link Collection#array}, and thus the caching
|
||||
* mechanism applies here as well.
|
||||
* @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
|
||||
* amount is negative
|
||||
*/
|
||||
last(amount) {
|
||||
const arr = this.array();
|
||||
if (typeof amount === 'undefined') return arr[arr.length - 1];
|
||||
if (amount < 0) return this.first(amount * -1);
|
||||
if (!amount) return [];
|
||||
return arr.slice(-amount);
|
||||
}
|
||||
|
||||
/**
|
||||
* Obtains the last key(s) in this collection. This relies on {@link Collection#keyArray}, and thus the caching
|
||||
* mechanism applies here as well.
|
||||
* @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
|
||||
* amount is negative
|
||||
*/
|
||||
lastKey(amount) {
|
||||
const arr = this.keyArray();
|
||||
if (typeof amount === 'undefined') return arr[arr.length - 1];
|
||||
if (amount < 0) return this.firstKey(amount * -1);
|
||||
if (!amount) return [];
|
||||
return arr.slice(-amount);
|
||||
}
|
||||
|
||||
/**
|
||||
* Obtains unique random value(s) from this collection. This relies on {@link Collection#array}, and thus the caching
|
||||
* mechanism applies here as well.
|
||||
* @param {number} [amount] Amount of values to obtain randomly
|
||||
* @returns {*|Array<*>} A single value if no amount is provided or an array of values
|
||||
*/
|
||||
random(amount) {
|
||||
let arr = this.array();
|
||||
if (typeof amount === 'undefined') return arr[Math.floor(Math.random() * arr.length)];
|
||||
if (arr.length === 0 || !amount) return [];
|
||||
const rand = new Array(amount);
|
||||
arr = arr.slice();
|
||||
for (let i = 0; i < amount; i++) rand[i] = arr.splice(Math.floor(Math.random() * arr.length), 1)[0];
|
||||
return rand;
|
||||
}
|
||||
|
||||
/**
|
||||
* Obtains unique random key(s) from this collection. This relies on {@link Collection#keyArray}, and thus the caching
|
||||
* mechanism applies here as well.
|
||||
* @param {number} [amount] Amount of keys to obtain randomly
|
||||
* @returns {*|Array<*>} A single key if no amount is provided or an array
|
||||
*/
|
||||
randomKey(amount) {
|
||||
let arr = this.keyArray();
|
||||
if (typeof amount === 'undefined') return arr[Math.floor(Math.random() * arr.length)];
|
||||
if (arr.length === 0 || !amount) return [];
|
||||
const rand = new Array(amount);
|
||||
arr = arr.slice();
|
||||
for (let i = 0; i < amount; i++) rand[i] = arr.splice(Math.floor(Math.random() * arr.length), 1)[0];
|
||||
return rand;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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).
|
||||
* <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');
|
||||
*/
|
||||
find(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
for (const [key, val] of this) {
|
||||
if (fn(val, key, this)) return val;
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/* eslint-disable max-len */
|
||||
/**
|
||||
* 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');
|
||||
*/
|
||||
findKey(fn, thisArg) {
|
||||
/* eslint-enable max-len */
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
for (const [key, val] of this) {
|
||||
if (fn(val, key, this)) return key;
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes entries that satisfy the provided filter function.
|
||||
* @param {Function} fn Function used to test (should return a boolean)
|
||||
* @param {Object} [thisArg] Value to use as `this` when executing function
|
||||
* @returns {number} The number of removed entries
|
||||
*/
|
||||
sweep(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
const previousSize = this.size;
|
||||
for (const [key, val] of this) {
|
||||
if (fn(val, key, this)) this.delete(key);
|
||||
}
|
||||
return previousSize - this.size;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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');
|
||||
*/
|
||||
filter(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
const results = new this.constructor[Symbol.species]();
|
||||
for (const [key, val] of this) {
|
||||
if (fn(val, key, this)) results.set(key, val);
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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);
|
||||
*/
|
||||
partition(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
const results = [new this.constructor[Symbol.species](), new this.constructor[Symbol.species]()];
|
||||
for (const [key, val] of this) {
|
||||
if (fn(val, key, this)) {
|
||||
results[0].set(key, val);
|
||||
} else {
|
||||
results[1].set(key, val);
|
||||
}
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
/**
|
||||
* Maps each item to another value. 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);
|
||||
*/
|
||||
map(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
const arr = new Array(this.size);
|
||||
let i = 0;
|
||||
for (const [key, val] of this) arr[i++] = fn(val, key, this);
|
||||
return arr;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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');
|
||||
*/
|
||||
some(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
for (const [key, val] of this) {
|
||||
if (fn(val, key, this)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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);
|
||||
*/
|
||||
every(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
for (const [key, val] of this) {
|
||||
if (!fn(val, key, this)) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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`,
|
||||
* and `collection`
|
||||
* @param {*} [initialValue] Starting value for the accumulator
|
||||
* @returns {*}
|
||||
* @example collection.reduce((acc, guild) => acc + guild.memberCount, 0);
|
||||
*/
|
||||
reduce(fn, initialValue) {
|
||||
let accumulator;
|
||||
if (typeof initialValue !== 'undefined') {
|
||||
accumulator = initialValue;
|
||||
for (const [key, val] of this) accumulator = fn(accumulator, val, key, this);
|
||||
} else {
|
||||
let first = true;
|
||||
for (const [key, val] of this) {
|
||||
if (first) {
|
||||
accumulator = val;
|
||||
first = false;
|
||||
continue;
|
||||
}
|
||||
accumulator = fn(accumulator, val, key, this);
|
||||
}
|
||||
}
|
||||
return accumulator;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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}
|
||||
* @example
|
||||
* collection
|
||||
* .each(user => console.log(user.username))
|
||||
* .filter(user => user.bot)
|
||||
* .each(user => console.log(user.username));
|
||||
*/
|
||||
each(fn, thisArg) {
|
||||
this.forEach(fn, thisArg);
|
||||
return 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}
|
||||
* @example
|
||||
* collection
|
||||
* .tap(coll => console.log(`${coll.size} users, including bots`))
|
||||
* .filter(user => user.bot)
|
||||
* .tap(coll => console.log(`${coll.size} users, excluding bots`))
|
||||
*/
|
||||
tap(fn, thisArg) {
|
||||
if (typeof thisArg !== 'undefined') fn = fn.bind(thisArg);
|
||||
fn(this);
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an identical shallow copy of this collection.
|
||||
* @returns {Collection}
|
||||
* @example 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 {...Collection} collections Collections to merge
|
||||
* @returns {Collection}
|
||||
* @example const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
|
||||
*/
|
||||
concat(...collections) {
|
||||
const newColl = this.clone();
|
||||
for (const coll of collections) {
|
||||
for (const [key, val] of coll) newColl.set(key, val);
|
||||
}
|
||||
return newColl;
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if this collection shares identical key-value pairings 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
|
||||
*/
|
||||
equals(collection) {
|
||||
if (!collection) return false;
|
||||
if (this === collection) return true;
|
||||
if (this.size !== collection.size) return false;
|
||||
return !this.find((value, key) => {
|
||||
const testVal = collection.get(key);
|
||||
return testVal !== value || (testVal === undefined && !collection.has(key));
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* The sort() method sorts the elements of a collection and returns it.
|
||||
* The sort is not necessarily stable. 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);
|
||||
*/
|
||||
sort(compareFunction = (x, y) => +(x > y) || +(x === y) - 1) {
|
||||
return new this.constructor[Symbol.species]([...this.entries()]
|
||||
.sort((a, b) => compareFunction(a[1], b[1], a[0], b[0])));
|
||||
}
|
||||
|
||||
class Collection extends BaseCollection {
|
||||
toJSON() {
|
||||
return this.map(e => typeof e.toJSON === 'function' ? e.toJSON() : Util.flatten(e));
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = Collection;
|
||||
|
||||
/**
|
||||
* @external BaseCollection
|
||||
* @see {@link https://discord.js.org/#/docs/collection/}
|
||||
*/
|
||||
|
||||
@@ -432,7 +432,7 @@ class Util {
|
||||
* @returns {Collection}
|
||||
*/
|
||||
static discordSort(collection) {
|
||||
return collection.sort((a, b) =>
|
||||
return collection.sorted((a, b) =>
|
||||
a.rawPosition - b.rawPosition ||
|
||||
parseInt(b.id.slice(0, -10)) - parseInt(a.id.slice(0, -10)) ||
|
||||
parseInt(b.id.slice(10)) - parseInt(a.id.slice(10))
|
||||
|
||||
35
typings/index.d.ts
vendored
35
typings/index.d.ts
vendored
@@ -1,4 +1,5 @@
|
||||
declare module 'discord.js' {
|
||||
import BaseCollection from '@discord.js/collection';
|
||||
import { EventEmitter } from 'events';
|
||||
import { Stream, Readable, Writable } from 'stream';
|
||||
import { ChildProcess } from 'child_process';
|
||||
@@ -311,39 +312,7 @@ declare module 'discord.js' {
|
||||
public setUsername(username: string): Promise<ClientUser>;
|
||||
}
|
||||
|
||||
export class Collection<K, V> extends Map<K, V> {
|
||||
private _array: V[];
|
||||
private _keyArray: K[];
|
||||
|
||||
public array(): V[];
|
||||
public clone(): Collection<K, V>;
|
||||
public concat(...collections: Collection<K, V>[]): Collection<K, V>;
|
||||
public each(fn: (value: V, key: K, collection: Collection<K, V>) => void, thisArg?: any): Collection<K, V>;
|
||||
public equals(collection: Collection<any, any>): boolean;
|
||||
public every(fn: (value: V, key: K, collection: Collection<K, V>) => boolean, thisArg?: any): boolean;
|
||||
public filter(fn: (value: V, key: K, collection: Collection<K, V>) => boolean, thisArg?: any): Collection<K, V>;
|
||||
public find(fn: (value: V, key: K, collection: Collection<K, V>) => boolean, thisArg?: any): V | undefined;
|
||||
public findKey(fn: (value: V, key: K, collection: Collection<K, V>) => boolean, thisArg?: any): K | undefined;
|
||||
public first(): V | undefined;
|
||||
public first(count: number): V[];
|
||||
public firstKey(): K | undefined;
|
||||
public firstKey(count: number): K[];
|
||||
public keyArray(): K[];
|
||||
public last(): V | undefined;
|
||||
public last(count: number): V[];
|
||||
public lastKey(): K | undefined;
|
||||
public lastKey(count: number): K[];
|
||||
public map<T>(fn: (value: V, key: K, collection: Collection<K, V>) => T, thisArg?: any): T[];
|
||||
public partition(fn: (value: V, key: K, collection: Collection<K, V>) => boolean, thisArg?: any): [Collection<K, V>, Collection<K, V>];
|
||||
public random(): V | undefined;
|
||||
public random(count: number): V[];
|
||||
public randomKey(): K | undefined;
|
||||
public randomKey(count: number): K[];
|
||||
public reduce<T>(fn: (accumulator: T, value: V, key: K, collection: Collection<K, V>) => T, initialValue?: T): T;
|
||||
public some(fn: (value: V, key: K, collection: Collection<K, V>) => boolean, thisArg?: any): boolean;
|
||||
public sort(compareFunction?: (a: V, b: V, c?: K, d?: K) => number): Collection<K, V>;
|
||||
public sweep(fn: (value: V, key: K, collection: Collection<K, V>) => boolean, thisArg?: any): number;
|
||||
public tap(fn: (collection: Collection<K, V>) => void, thisArg?: any): Collection<K, V>;
|
||||
export class Collection<K, V> extends BaseCollection<K, V> {
|
||||
public toJSON(): object;
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user