1 | /**
|
2 | * @internal
|
3 | */
|
4 | interface CollectionConstructor {
|
5 | new (): Collection<unknown, unknown>;
|
6 | new <K, V>(entries?: ReadonlyArray<readonly [K, V]> | null): Collection<K, V>;
|
7 | new <K, V>(iterable: Iterable<readonly [K, V]>): Collection<K, V>;
|
8 | readonly prototype: Collection<unknown, unknown>;
|
9 | readonly [Symbol.species]: CollectionConstructor;
|
10 | }
|
11 | /**
|
12 | * Represents an immutable version of a collection
|
13 | */
|
14 | declare type ReadonlyCollection<K, V> = ReadonlyMap<K, V> & Omit<Collection<K, V>, 'forEach' | 'ensure' | 'reverse' | 'sweep' | 'sort' | 'get' | 'set' | 'delete'>;
|
15 | /**
|
16 | * Separate interface for the constructor so that emitted js does not have a constructor that overwrites itself
|
17 | *
|
18 | * @internal
|
19 | */
|
20 | interface Collection<K, V> extends Map<K, V> {
|
21 | constructor: CollectionConstructor;
|
22 | }
|
23 | /**
|
24 | * A Map with additional utility methods. This is used throughout discord.js rather than Arrays for anything that has
|
25 | * an ID, for significantly improved performance and ease-of-use.
|
26 | */
|
27 | declare class Collection<K, V> extends Map<K, V> {
|
28 | static readonly default: typeof Collection;
|
29 | /**
|
30 | * Obtains the value of the given key if it exists, otherwise sets and returns the value provided by the default value generator.
|
31 | *
|
32 | * @param key The key to get if it exists, or set otherwise
|
33 | * @param defaultValueGenerator A function that generates the default value
|
34 | *
|
35 | * @example
|
36 | * collection.ensure(guildId, () => defaultGuildConfig);
|
37 | */
|
38 | ensure(key: K, defaultValueGenerator: (key: K, collection: this) => V): V;
|
39 | /**
|
40 | * Checks if all of the elements exist in the collection.
|
41 | *
|
42 | * @param keys - The keys of the elements to check for
|
43 | *
|
44 | * @returns `true` if all of the elements exist, `false` if at least one does not exist.
|
45 | */
|
46 | hasAll(...keys: K[]): boolean;
|
47 | /**
|
48 | * Checks if any of the elements exist in the collection.
|
49 | *
|
50 | * @param keys - The keys of the elements to check for
|
51 | *
|
52 | * @returns `true` if any of the elements exist, `false` if none exist.
|
53 | */
|
54 | hasAny(...keys: K[]): boolean;
|
55 | /**
|
56 | * Obtains the first value(s) in this collection.
|
57 | *
|
58 | * @param amount Amount of values to obtain from the beginning
|
59 | *
|
60 | * @returns A single value if no amount is provided or an array of values, starting from the end if amount is negative
|
61 | */
|
62 | first(): V | undefined;
|
63 | first(amount: number): V[];
|
64 | /**
|
65 | * Obtains the first key(s) in this collection.
|
66 | *
|
67 | * @param amount Amount of keys to obtain from the beginning
|
68 | *
|
69 | * @returns A single key if no amount is provided or an array of keys, starting from the end if
|
70 | * amount is negative
|
71 | */
|
72 | firstKey(): K | undefined;
|
73 | firstKey(amount: number): K[];
|
74 | /**
|
75 | * Obtains the last value(s) in this collection.
|
76 | *
|
77 | * @param amount Amount of values to obtain from the end
|
78 | *
|
79 | * @returns A single value if no amount is provided or an array of values, starting from the start if
|
80 | * amount is negative
|
81 | */
|
82 | last(): V | undefined;
|
83 | last(amount: number): V[];
|
84 | /**
|
85 | * Obtains the last key(s) in this collection.
|
86 | *
|
87 | * @param amount Amount of keys to obtain from the end
|
88 | *
|
89 | * @returns A single key if no amount is provided or an array of keys, starting from the start if
|
90 | * amount is negative
|
91 | */
|
92 | lastKey(): K | undefined;
|
93 | lastKey(amount: number): K[];
|
94 | /**
|
95 | * Identical to [Array.at()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at).
|
96 | * Returns the item at a given index, allowing for positive and negative integers.
|
97 | * Negative integers count back from the last item in the collection.
|
98 | *
|
99 | * @param index The index of the element to obtain
|
100 | */
|
101 | at(index: number): V | undefined;
|
102 | /**
|
103 | * Identical to [Array.at()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at).
|
104 | * Returns the key at a given index, allowing for positive and negative integers.
|
105 | * Negative integers count back from the last item in the collection.
|
106 | *
|
107 | * @param index The index of the key to obtain
|
108 | */
|
109 | keyAt(index: number): K | undefined;
|
110 | /**
|
111 | * Obtains unique random value(s) from this collection.
|
112 | *
|
113 | * @param amount Amount of values to obtain randomly
|
114 | *
|
115 | * @returns A single value if no amount is provided or an array of values
|
116 | */
|
117 | random(): V | undefined;
|
118 | random(amount: number): V[];
|
119 | /**
|
120 | * Obtains unique random key(s) from this collection.
|
121 | *
|
122 | * @param amount Amount of keys to obtain randomly
|
123 | *
|
124 | * @returns A single key if no amount is provided or an array
|
125 | */
|
126 | randomKey(): K | undefined;
|
127 | randomKey(amount: number): K[];
|
128 | /**
|
129 | * Identical to [Array.reverse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse)
|
130 | * but returns a Collection instead of an Array.
|
131 | */
|
132 | reverse(): this;
|
133 | /**
|
134 | * Searches for a single item where the given function returns a truthy value. This behaves like
|
135 | * [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find).
|
136 | * <warn>All collections used in Discord.js are mapped using their `id` property, and if you want to find by id you
|
137 | * should use the `get` method. See
|
138 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details.</warn>
|
139 | *
|
140 | * @param fn The function to test with (should return boolean)
|
141 | * @param thisArg Value to use as `this` when executing function
|
142 | *
|
143 | * @example
|
144 | * collection.find(user => user.username === 'Bob');
|
145 | */
|
146 | find<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): V2 | undefined;
|
147 | find(fn: (value: V, key: K, collection: this) => boolean): V | undefined;
|
148 | find<This, V2 extends V>(fn: (this: This, value: V, key: K, collection: this) => value is V2, thisArg: This): V2 | undefined;
|
149 | find<This>(fn: (this: This, value: V, key: K, collection: this) => boolean, thisArg: This): V | undefined;
|
150 | /**
|
151 | * Searches for the key of a single item where the given function returns a truthy value. This behaves like
|
152 | * [Array.findIndex()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex),
|
153 | * but returns the key rather than the positional index.
|
154 | *
|
155 | * @param fn The function to test with (should return boolean)
|
156 | * @param thisArg Value to use as `this` when executing function
|
157 | *
|
158 | * @example
|
159 | * collection.findKey(user => user.username === 'Bob');
|
160 | */
|
161 | findKey<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): K2 | undefined;
|
162 | findKey(fn: (value: V, key: K, collection: this) => boolean): K | undefined;
|
163 | findKey<This, K2 extends K>(fn: (this: This, value: V, key: K, collection: this) => key is K2, thisArg: This): K2 | undefined;
|
164 | findKey<This>(fn: (this: This, value: V, key: K, collection: this) => boolean, thisArg: This): K | undefined;
|
165 | /**
|
166 | * Removes items that satisfy the provided filter function.
|
167 | *
|
168 | * @param fn Function used to test (should return a boolean)
|
169 | * @param thisArg Value to use as `this` when executing function
|
170 | *
|
171 | * @returns The number of removed entries
|
172 | */
|
173 | sweep(fn: (value: V, key: K, collection: this) => boolean): number;
|
174 | sweep<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): number;
|
175 | /**
|
176 | * Identical to
|
177 | * [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter),
|
178 | * but returns a Collection instead of an Array.
|
179 | *
|
180 | * @param fn The function to test with (should return boolean)
|
181 | * @param thisArg Value to use as `this` when executing function
|
182 | *
|
183 | * @example
|
184 | * collection.filter(user => user.username === 'Bob');
|
185 | */
|
186 | filter<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): Collection<K2, V>;
|
187 | filter<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): Collection<K, V2>;
|
188 | filter(fn: (value: V, key: K, collection: this) => boolean): Collection<K, V>;
|
189 | filter<This, K2 extends K>(fn: (this: This, value: V, key: K, collection: this) => key is K2, thisArg: This): Collection<K2, V>;
|
190 | filter<This, V2 extends V>(fn: (this: This, value: V, key: K, collection: this) => value is V2, thisArg: This): Collection<K, V2>;
|
191 | filter<This>(fn: (this: This, value: V, key: K, collection: this) => boolean, thisArg: This): Collection<K, V>;
|
192 | /**
|
193 | * Partitions the collection into two collections where the first collection
|
194 | * contains the items that passed and the second contains the items that failed.
|
195 | *
|
196 | * @param fn Function used to test (should return a boolean)
|
197 | * @param thisArg Value to use as `this` when executing function
|
198 | *
|
199 | * @example
|
200 | * const [big, small] = collection.partition(guild => guild.memberCount > 250);
|
201 | */
|
202 | partition<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): [Collection<K2, V>, Collection<Exclude<K, K2>, V>];
|
203 | partition<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): [Collection<K, V2>, Collection<K, Exclude<V, V2>>];
|
204 | partition(fn: (value: V, key: K, collection: this) => boolean): [Collection<K, V>, Collection<K, V>];
|
205 | partition<This, K2 extends K>(fn: (this: This, value: V, key: K, collection: this) => key is K2, thisArg: This): [Collection<K2, V>, Collection<Exclude<K, K2>, V>];
|
206 | partition<This, V2 extends V>(fn: (this: This, value: V, key: K, collection: this) => value is V2, thisArg: This): [Collection<K, V2>, Collection<K, Exclude<V, V2>>];
|
207 | partition<This>(fn: (this: This, value: V, key: K, collection: this) => boolean, thisArg: This): [Collection<K, V>, Collection<K, V>];
|
208 | /**
|
209 | * Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to
|
210 | * [Array.flatMap()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap).
|
211 | *
|
212 | * @param fn Function that produces a new Collection
|
213 | * @param thisArg Value to use as `this` when executing function
|
214 | *
|
215 | * @example
|
216 | * collection.flatMap(guild => guild.members.cache);
|
217 | */
|
218 | flatMap<T>(fn: (value: V, key: K, collection: this) => Collection<K, T>): Collection<K, T>;
|
219 | flatMap<T, This>(fn: (this: This, value: V, key: K, collection: this) => Collection<K, T>, thisArg: This): Collection<K, T>;
|
220 | /**
|
221 | * Maps each item to another value into an array. Identical in behavior to
|
222 | * [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
|
223 | *
|
224 | * @param fn Function that produces an element of the new array, taking three arguments
|
225 | * @param thisArg Value to use as `this` when executing function
|
226 | *
|
227 | * @example
|
228 | * collection.map(user => user.tag);
|
229 | */
|
230 | map<T>(fn: (value: V, key: K, collection: this) => T): T[];
|
231 | map<This, T>(fn: (this: This, value: V, key: K, collection: this) => T, thisArg: This): T[];
|
232 | /**
|
233 | * Maps each item to another value into a collection. Identical in behavior to
|
234 | * [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
|
235 | *
|
236 | * @param fn Function that produces an element of the new collection, taking three arguments
|
237 | * @param thisArg Value to use as `this` when executing function
|
238 | *
|
239 | * @example
|
240 | * collection.mapValues(user => user.tag);
|
241 | */
|
242 | mapValues<T>(fn: (value: V, key: K, collection: this) => T): Collection<K, T>;
|
243 | mapValues<This, T>(fn: (this: This, value: V, key: K, collection: this) => T, thisArg: This): Collection<K, T>;
|
244 | /**
|
245 | * Checks if there exists an item that passes a test. Identical in behavior to
|
246 | * [Array.some()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some).
|
247 | *
|
248 | * @param fn Function used to test (should return a boolean)
|
249 | * @param thisArg Value to use as `this` when executing function
|
250 | *
|
251 | * @example
|
252 | * collection.some(user => user.discriminator === '0000');
|
253 | */
|
254 | some(fn: (value: V, key: K, collection: this) => boolean): boolean;
|
255 | some<T>(fn: (this: T, value: V, key: K, collection: this) => boolean, thisArg: T): boolean;
|
256 | /**
|
257 | * Checks if all items passes a test. Identical in behavior to
|
258 | * [Array.every()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every).
|
259 | *
|
260 | * @param fn Function used to test (should return a boolean)
|
261 | * @param thisArg Value to use as `this` when executing function
|
262 | *
|
263 | * @example
|
264 | * collection.every(user => !user.bot);
|
265 | */
|
266 | every<K2 extends K>(fn: (value: V, key: K, collection: this) => key is K2): this is Collection<K2, V>;
|
267 | every<V2 extends V>(fn: (value: V, key: K, collection: this) => value is V2): this is Collection<K, V2>;
|
268 | every(fn: (value: V, key: K, collection: this) => boolean): boolean;
|
269 | every<This, K2 extends K>(fn: (this: This, value: V, key: K, collection: this) => key is K2, thisArg: This): this is Collection<K2, V>;
|
270 | every<This, V2 extends V>(fn: (this: This, value: V, key: K, collection: this) => value is V2, thisArg: This): this is Collection<K, V2>;
|
271 | every<This>(fn: (this: This, value: V, key: K, collection: this) => boolean, thisArg: This): boolean;
|
272 | /**
|
273 | * Applies a function to produce a single value. Identical in behavior to
|
274 | * [Array.reduce()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce).
|
275 | *
|
276 | * @param fn Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
|
277 | * and `collection`
|
278 | * @param initialValue Starting value for the accumulator
|
279 | *
|
280 | * @example
|
281 | * collection.reduce((acc, guild) => acc + guild.memberCount, 0);
|
282 | */
|
283 | reduce<T>(fn: (accumulator: T, value: V, key: K, collection: this) => T, initialValue?: T): T;
|
284 | /**
|
285 | * Identical to
|
286 | * [Map.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/forEach),
|
287 | * but returns the collection instead of undefined.
|
288 | *
|
289 | * @param fn Function to execute for each element
|
290 | * @param thisArg Value to use as `this` when executing function
|
291 | *
|
292 | * @example
|
293 | * collection
|
294 | * .each(user => console.log(user.username))
|
295 | * .filter(user => user.bot)
|
296 | * .each(user => console.log(user.username));
|
297 | */
|
298 | each(fn: (value: V, key: K, collection: this) => void): this;
|
299 | each<T>(fn: (this: T, value: V, key: K, collection: this) => void, thisArg: T): this;
|
300 | /**
|
301 | * Runs a function on the collection and returns the collection.
|
302 | *
|
303 | * @param fn Function to execute
|
304 | * @param thisArg Value to use as `this` when executing function
|
305 | *
|
306 | * @example
|
307 | * collection
|
308 | * .tap(coll => console.log(coll.size))
|
309 | * .filter(user => user.bot)
|
310 | * .tap(coll => console.log(coll.size))
|
311 | */
|
312 | tap(fn: (collection: this) => void): this;
|
313 | tap<T>(fn: (this: T, collection: this) => void, thisArg: T): this;
|
314 | /**
|
315 | * Creates an identical shallow copy of this collection.
|
316 | *
|
317 | * @example
|
318 | * const newColl = someColl.clone();
|
319 | */
|
320 | clone(): Collection<K, V>;
|
321 | /**
|
322 | * Combines this collection with others into a new collection. None of the source collections are modified.
|
323 | *
|
324 | * @param collections Collections to merge
|
325 | *
|
326 | * @example
|
327 | * const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
|
328 | */
|
329 | concat(...collections: ReadonlyCollection<K, V>[]): Collection<K, V>;
|
330 | /**
|
331 | * Checks if this collection shares identical items with another.
|
332 | * This is different to checking for equality using equal-signs, because
|
333 | * the collections may be different objects, but contain the same data.
|
334 | *
|
335 | * @param collection Collection to compare with
|
336 | *
|
337 | * @returns Whether the collections have identical contents
|
338 | */
|
339 | equals(collection: ReadonlyCollection<K, V>): boolean;
|
340 | /**
|
341 | * The sort method sorts the items of a collection in place and returns it.
|
342 | * The sort is not necessarily stable in Node 10 or older.
|
343 | * The default sort order is according to string Unicode code points.
|
344 | *
|
345 | * @param compareFunction Specifies a function that defines the sort order.
|
346 | * If omitted, the collection is sorted according to each character's Unicode code point value, according to the string conversion of each element.
|
347 | *
|
348 | * @example
|
349 | * collection.sort((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
|
350 | */
|
351 | sort(compareFunction?: Comparator<K, V>): this;
|
352 | /**
|
353 | * The intersect method returns a new structure containing items where the keys and values are present in both original structures.
|
354 | *
|
355 | * @param other The other Collection to filter against
|
356 | */
|
357 | intersect<T>(other: ReadonlyCollection<K, T>): Collection<K, T>;
|
358 | /**
|
359 | * The difference method returns a new structure containing items where the key is present in one of the original structures but not the other.
|
360 | *
|
361 | * @param other The other Collection to filter against
|
362 | */
|
363 | difference<T>(other: ReadonlyCollection<K, T>): Collection<K, V | T>;
|
364 | /**
|
365 | * Merges two Collections together into a new Collection.
|
366 | * @param other The other Collection to merge with
|
367 | * @param whenInSelf Function getting the result if the entry only exists in this Collection
|
368 | * @param whenInOther Function getting the result if the entry only exists in the other Collection
|
369 | * @param whenInBoth Function getting the result if the entry exists in both Collections
|
370 | *
|
371 | * @example
|
372 | * // Sums up the entries in two collections.
|
373 | * coll.merge(
|
374 | * other,
|
375 | * x => ({ keep: true, value: x }),
|
376 | * y => ({ keep: true, value: y }),
|
377 | * (x, y) => ({ keep: true, value: x + y }),
|
378 | * );
|
379 | *
|
380 | * @example
|
381 | * // Intersects two collections in a left-biased manner.
|
382 | * coll.merge(
|
383 | * other,
|
384 | * x => ({ keep: false }),
|
385 | * y => ({ keep: false }),
|
386 | * (x, _) => ({ keep: true, value: x }),
|
387 | * );
|
388 | */
|
389 | merge<T, R>(other: ReadonlyCollection<K, T>, whenInSelf: (value: V, key: K) => Keep<R>, whenInOther: (valueOther: T, key: K) => Keep<R>, whenInBoth: (value: V, valueOther: T, key: K) => Keep<R>): Collection<K, R>;
|
390 | /**
|
391 | * The sorted method sorts the items of a collection and returns it.
|
392 | * The sort is not necessarily stable in Node 10 or older.
|
393 | * The default sort order is according to string Unicode code points.
|
394 | *
|
395 | * @param compareFunction Specifies a function that defines the sort order.
|
396 | * If omitted, the collection is sorted according to each character's Unicode code point value,
|
397 | * according to the string conversion of each element.
|
398 | *
|
399 | * @example
|
400 | * collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
|
401 | */
|
402 | sorted(compareFunction?: Comparator<K, V>): Collection<K, V>;
|
403 | toJSON(): V[];
|
404 | private static defaultSort;
|
405 | /**
|
406 | * Creates a Collection from a list of entries.
|
407 | * @param entries The list of entries
|
408 | * @param combine Function to combine an existing entry with a new one
|
409 | *
|
410 | * @example
|
411 | * Collection.combineEntries([["a", 1], ["b", 2], ["a", 2]], (x, y) => x + y);
|
412 | * // returns Collection { "a" => 3, "b" => 2 }
|
413 | */
|
414 | static combineEntries<K, V>(entries: Iterable<[K, V]>, combine: (firstValue: V, secondValue: V, key: K) => V): Collection<K, V>;
|
415 | }
|
416 | /**
|
417 | * @internal
|
418 | */
|
419 | declare type Keep<V> = {
|
420 | keep: true;
|
421 | value: V;
|
422 | } | {
|
423 | keep: false;
|
424 | };
|
425 | /**
|
426 | * @internal
|
427 | */
|
428 | declare type Comparator<K, V> = (firstValue: V, secondValue: V, firstKey: K, secondKey: K) => number;
|
429 |
|
430 | export { Collection, CollectionConstructor, Comparator, Keep, ReadonlyCollection, Collection as default };
|
431 |
|
\ | No newline at end of file |