index.d.ts (17358B)
1 export interface CollectionConstructor { 2 new (): Collection<unknown, unknown>; 3 new <K, V>(entries?: ReadonlyArray<readonly [K, V]> | null): Collection<K, V>; 4 new <K, V>(iterable: Iterable<readonly [K, V]>): Collection<K, V>; 5 readonly prototype: Collection<unknown, unknown>; 6 readonly [Symbol.species]: CollectionConstructor; 7 } 8 /** 9 * A Map with additional utility methods. This is used throughout discord.js rather than Arrays for anything that has 10 * an ID, for significantly improved performance and ease-of-use. 11 * @extends {Map} 12 * @property {number} size - The amount of elements in this collection. 13 */ 14 declare class Collection<K, V> extends Map<K, V> { 15 private _array; 16 private _keyArray; 17 static readonly default: typeof Collection; 18 ['constructor']: typeof Collection; 19 constructor(entries?: ReadonlyArray<readonly [K, V]> | null); 20 /** 21 * Identical to [Map.get()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get). 22 * Gets an element with the specified key, and returns its value, or `undefined` if the element does not exist. 23 * @param {*} key - The key to get from this collection 24 * @returns {* | undefined} 25 */ 26 get(key: K): V | undefined; 27 /** 28 * Identical to [Map.set()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/set). 29 * Sets a new element in the collection with the specified key and value. 30 * @param {*} key - The key of the element to add 31 * @param {*} value - The value of the element to add 32 * @returns {Collection} 33 */ 34 set(key: K, value: V): this; 35 /** 36 * Identical to [Map.has()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/has). 37 * Checks if an element exists in the collection. 38 * @param {*} key - The key of the element to check for 39 * @returns {boolean} `true` if the element exists, `false` if it does not exist. 40 */ 41 has(key: K): boolean; 42 /** 43 * Identical to [Map.delete()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/delete). 44 * Deletes an element from the collection. 45 * @param {*} key - The key to delete from the collection 46 * @returns {boolean} `true` if the element was removed, `false` if the element does not exist. 47 */ 48 delete(key: K): boolean; 49 /** 50 * Identical to [Map.clear()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/clear). 51 * Removes all elements from the collection. 52 * @returns {undefined} 53 */ 54 clear(): void; 55 /** 56 * Creates an ordered array of the values of this collection, and caches it internally. The array will only be 57 * reconstructed if an item is added to or removed from the collection, or if you change the length of the array 58 * itself. If you don't want this caching behavior, use `[...collection.values()]` or 59 * `Array.from(collection.values())` instead. 60 * @returns {Array} 61 */ 62 array(): V[]; 63 /** 64 * Creates an ordered array of the keys of this collection, and caches it internally. The array will only be 65 * reconstructed if an item is added to or removed from the collection, or if you change the length of the array 66 * itself. If you don't want this caching behavior, use `[...collection.keys()]` or 67 * `Array.from(collection.keys())` instead. 68 * @returns {Array} 69 */ 70 keyArray(): K[]; 71 /** 72 * Obtains the first value(s) in this collection. 73 * @param {number} [amount] Amount of values to obtain from the beginning 74 * @returns {*|Array<*>} A single value if no amount is provided or an array of values, starting from the end if 75 * amount is negative 76 */ 77 first(): V | undefined; 78 first(amount: number): V[]; 79 /** 80 * Obtains the first key(s) in this collection. 81 * @param {number} [amount] Amount of keys to obtain from the beginning 82 * @returns {*|Array<*>} A single key if no amount is provided or an array of keys, starting from the end if 83 * amount is negative 84 */ 85 firstKey(): K | undefined; 86 firstKey(amount: number): K[]; 87 /** 88 * Obtains the last value(s) in this collection. This relies on {@link Collection#array}, and thus the caching 89 * mechanism applies here as well. 90 * @param {number} [amount] Amount of values to obtain from the end 91 * @returns {*|Array<*>} A single value if no amount is provided or an array of values, starting from the start if 92 * amount is negative 93 */ 94 last(): V | undefined; 95 last(amount: number): V[]; 96 /** 97 * Obtains the last key(s) in this collection. This relies on {@link Collection#keyArray}, and thus the caching 98 * mechanism applies here as well. 99 * @param {number} [amount] Amount of keys to obtain from the end 100 * @returns {*|Array<*>} A single key if no amount is provided or an array of keys, starting from the start if 101 * amount is negative 102 */ 103 lastKey(): K | undefined; 104 lastKey(amount: number): K[]; 105 /** 106 * Obtains unique random value(s) from this collection. This relies on {@link Collection#array}, and thus the caching 107 * mechanism applies here as well. 108 * @param {number} [amount] Amount of values to obtain randomly 109 * @returns {*|Array<*>} A single value if no amount is provided or an array of values 110 */ 111 random(): V; 112 random(amount: number): V[]; 113 /** 114 * Obtains unique random key(s) from this collection. This relies on {@link Collection#keyArray}, and thus the caching 115 * mechanism applies here as well. 116 * @param {number} [amount] Amount of keys to obtain randomly 117 * @returns {*|Array<*>} A single key if no amount is provided or an array 118 */ 119 randomKey(): K; 120 randomKey(amount: number): K[]; 121 /** 122 * Searches for a single item where the given function returns a truthy value. This behaves like 123 * [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find). 124 * <warn>All collections used in Discord.js are mapped using their `id` property, and if you want to find by id you 125 * should use the `get` method. See 126 * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details.</warn> 127 * @param {Function} fn The function to test with (should return boolean) 128 * @param {*} [thisArg] Value to use as `this` when executing function 129 * @returns {*} 130 * @example collection.find(user => user.username === 'Bob'); 131 */ 132 find(fn: (value: V, key: K, collection: this) => boolean): V | undefined; 133 find<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): V | undefined; 134 /** 135 * Searches for the key of a single item where the given function returns a truthy value. This behaves like 136 * [Array.findIndex()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex), 137 * but returns the key rather than the positional index. 138 * @param {Function} fn The function to test with (should return boolean) 139 * @param {*} [thisArg] Value to use as `this` when executing function 140 * @returns {*} 141 * @example collection.findKey(user => user.username === 'Bob'); 142 */ 143 findKey(fn: (value: V, key: K, collection: this) => boolean): K | undefined; 144 findKey<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): K | undefined; 145 /** 146 * Removes items that satisfy the provided filter function. 147 * @param {Function} fn Function used to test (should return a boolean) 148 * @param {*} [thisArg] Value to use as `this` when executing function 149 * @returns {number} The number of removed entries 150 */ 151 sweep(fn: (value: V, key: K, collection: this) => boolean): number; 152 sweep<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): number; 153 /** 154 * Identical to 155 * [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), 156 * but returns a Collection instead of an Array. 157 * @param {Function} fn The function to test with (should return boolean) 158 * @param {*} [thisArg] Value to use as `this` when executing function 159 * @returns {Collection} 160 * @example collection.filter(user => user.username === 'Bob'); 161 */ 162 filter(fn: (value: V, key: K, collection: this) => boolean): this; 163 filter<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): this; 164 /** 165 * Partitions the collection into two collections where the first collection 166 * contains the items that passed and the second contains the items that failed. 167 * @param {Function} fn Function used to test (should return a boolean) 168 * @param {*} [thisArg] Value to use as `this` when executing function 169 * @returns {Collection[]} 170 * @example const [big, small] = collection.partition(guild => guild.memberCount > 250); 171 */ 172 partition(fn: (value: V, key: K, collection: this) => boolean): [this, this]; 173 partition<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): [this, this]; 174 /** 175 * Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to 176 * [Array.flatMap()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap). 177 * @param {Function} fn Function that produces a new Collection 178 * @param {*} [thisArg] Value to use as `this` when executing function 179 * @returns {Collection} 180 * @example collection.flatMap(guild => guild.members); 181 */ 182 flatMap<T>(fn: (value: V, key: K, collection: this) => Collection<K, T>): Collection<K, T>; 183 flatMap<T, This>(fn: (this: This, value: V, key: K, collection: this) => Collection<K, T>, thisArg: This): Collection<K, T>; 184 /** 185 * Maps each item to another value into an array. Identical in behavior to 186 * [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map). 187 * @param {Function} fn Function that produces an element of the new array, taking three arguments 188 * @param {*} [thisArg] Value to use as `this` when executing function 189 * @returns {Array} 190 * @example collection.map(user => user.tag); 191 */ 192 map<T>(fn: (value: V, key: K, collection: this) => T): T[]; 193 map<This, T>(fn: (this: This, value: V, key: K, collection: this) => T, thisArg: This): T[]; 194 /** 195 * Maps each item to another value into a collection. Identical in behavior to 196 * [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map). 197 * @param {Function} fn Function that produces an element of the new collection, taking three arguments 198 * @param {*} [thisArg] Value to use as `this` when executing function 199 * @returns {Collection} 200 * @example collection.mapValues(user => user.tag); 201 */ 202 mapValues<T>(fn: (value: V, key: K, collection: this) => T): Collection<K, T>; 203 mapValues<This, T>(fn: (this: This, value: V, key: K, collection: this) => T, thisArg: This): Collection<K, T>; 204 /** 205 * Checks if there exists an item that passes a test. Identical in behavior to 206 * [Array.some()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some). 207 * @param {Function} fn Function used to test (should return a boolean) 208 * @param {*} [thisArg] Value to use as `this` when executing function 209 * @returns {boolean} 210 * @example collection.some(user => user.discriminator === '0000'); 211 */ 212 some(fn: (value: V, key: K, collection: this) => boolean): boolean; 213 some<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): boolean; 214 /** 215 * Checks if all items passes a test. Identical in behavior to 216 * [Array.every()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every). 217 * @param {Function} fn Function used to test (should return a boolean) 218 * @param {*} [thisArg] Value to use as `this` when executing function 219 * @returns {boolean} 220 * @example collection.every(user => !user.bot); 221 */ 222 every(fn: (value: V, key: K, collection: this) => boolean): boolean; 223 every<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): boolean; 224 /** 225 * Applies a function to produce a single value. Identical in behavior to 226 * [Array.reduce()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce). 227 * @param {Function} fn Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`, 228 * and `collection` 229 * @param {*} [initialValue] Starting value for the accumulator 230 * @returns {*} 231 * @example collection.reduce((acc, guild) => acc + guild.memberCount, 0); 232 */ 233 reduce<T>(fn: (accumulator: T, value: V, key: K, collection: this) => T, initialValue?: T): T; 234 /** 235 * Identical to 236 * [Map.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/forEach), 237 * but returns the collection instead of undefined. 238 * @param {Function} fn Function to execute for each element 239 * @param {*} [thisArg] Value to use as `this` when executing function 240 * @returns {Collection} 241 * @example 242 * collection 243 * .each(user => console.log(user.username)) 244 * .filter(user => user.bot) 245 * .each(user => console.log(user.username)); 246 */ 247 each(fn: (value: V, key: K, collection: this) => void): this; 248 each<T>(fn: (this: T, value: V, key: K, collection: this) => void, thisArg: T): this; 249 /** 250 * Runs a function on the collection and returns the collection. 251 * @param {Function} fn Function to execute 252 * @param {*} [thisArg] Value to use as `this` when executing function 253 * @returns {Collection} 254 * @example 255 * collection 256 * .tap(coll => console.log(coll.size)) 257 * .filter(user => user.bot) 258 * .tap(coll => console.log(coll.size)) 259 */ 260 tap(fn: (collection: this) => void): this; 261 tap<T>(fn: (this: T, collection: this) => void, thisArg: T): this; 262 /** 263 * Creates an identical shallow copy of this collection. 264 * @returns {Collection} 265 * @example const newColl = someColl.clone(); 266 */ 267 clone(): this; 268 /** 269 * Combines this collection with others into a new collection. None of the source collections are modified. 270 * @param {...Collection} collections Collections to merge 271 * @returns {Collection} 272 * @example const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl); 273 */ 274 concat(...collections: Collection<K, V>[]): this; 275 /** 276 * Checks if this collection shares identical items with another. 277 * This is different to checking for equality using equal-signs, because 278 * the collections may be different objects, but contain the same data. 279 * @param {Collection} collection Collection to compare with 280 * @returns {boolean} Whether the collections have identical contents 281 */ 282 equals(collection: Collection<K, V>): boolean; 283 /** 284 * The sort method sorts the items of a collection in place and returns it. 285 * The sort is not necessarily stable. The default sort order is according to string Unicode code points. 286 * @param {Function} [compareFunction] Specifies a function that defines the sort order. 287 * If omitted, the collection is sorted according to each character's Unicode code point value, 288 * according to the string conversion of each element. 289 * @returns {Collection} 290 * @example collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp); 291 */ 292 sort(compareFunction?: (firstValue: V, secondValue: V, firstKey: K, secondKey: K) => number): this; 293 /** 294 * The intersect method returns a new structure containing items where the keys are present in both original structures. 295 * @param {Collection} other The other Collection to filter against 296 * @returns {Collection} 297 */ 298 intersect(other: Collection<K, V>): Collection<K, V>; 299 /** 300 * The difference method returns a new structure containing items where the key is present in one of the original structures but not the other. 301 * @param {Collection} other The other Collection to filter against 302 * @returns {Collection} 303 */ 304 difference(other: Collection<K, V>): Collection<K, V>; 305 /** 306 * The sorted method sorts the items of a collection and returns it. 307 * The sort is not necessarily stable. The default sort order is according to string Unicode code points. 308 * @param {Function} [compareFunction] Specifies a function that defines the sort order. 309 * If omitted, the collection is sorted according to each character's Unicode code point value, 310 * according to the string conversion of each element. 311 * @returns {Collection} 312 * @example collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp); 313 */ 314 sorted(compareFunction?: (firstValue: V, secondValue: V, firstKey: K, secondKey: K) => number): this; 315 } 316 export { Collection }; 317 export default Collection;