From dad0cd8e81e3f530d5e0dda1ea45359c602372ca Mon Sep 17 00:00:00 2001 From: 1Computer1 Date: Tue, 10 Sep 2019 11:44:47 -0400 Subject: [PATCH] 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 --- package.json | 1 + src/util/Collection.js | 417 +---------------------------------------- src/util/Util.js | 2 +- typings/index.d.ts | 35 +--- 4 files changed, 12 insertions(+), 443 deletions(-) diff --git a/package.json b/package.json index 626fea20e..602973946 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/src/util/Collection.js b/src/util/Collection.js index 3d01ffef0..13cc0889e 100644 --- a/src/util/Collection.js +++ b/src/util/Collection.js @@ -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). - * 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. - * @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/} + */ diff --git a/src/util/Util.js b/src/util/Util.js index f0079a2ac..6087f3c24 100644 --- a/src/util/Util.js +++ b/src/util/Util.js @@ -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)) diff --git a/typings/index.d.ts b/typings/index.d.ts index 28946efa3..4a6896c1e 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -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; } - export class Collection extends Map { - private _array: V[]; - private _keyArray: K[]; - - public array(): V[]; - public clone(): Collection; - public concat(...collections: Collection[]): Collection; - public each(fn: (value: V, key: K, collection: Collection) => void, thisArg?: any): Collection; - public equals(collection: Collection): boolean; - public every(fn: (value: V, key: K, collection: Collection) => boolean, thisArg?: any): boolean; - public filter(fn: (value: V, key: K, collection: Collection) => boolean, thisArg?: any): Collection; - public find(fn: (value: V, key: K, collection: Collection) => boolean, thisArg?: any): V | undefined; - public findKey(fn: (value: V, key: K, collection: Collection) => 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(fn: (value: V, key: K, collection: Collection) => T, thisArg?: any): T[]; - public partition(fn: (value: V, key: K, collection: Collection) => boolean, thisArg?: any): [Collection, Collection]; - public random(): V | undefined; - public random(count: number): V[]; - public randomKey(): K | undefined; - public randomKey(count: number): K[]; - public reduce(fn: (accumulator: T, value: V, key: K, collection: Collection) => T, initialValue?: T): T; - public some(fn: (value: V, key: K, collection: Collection) => boolean, thisArg?: any): boolean; - public sort(compareFunction?: (a: V, b: V, c?: K, d?: K) => number): Collection; - public sweep(fn: (value: V, key: K, collection: Collection) => boolean, thisArg?: any): number; - public tap(fn: (collection: Collection) => void, thisArg?: any): Collection; + export class Collection extends BaseCollection { public toJSON(): object; }