discord.js comes with a utility class known as
Map class, so it has all the
Map features and more!
If you're not familiar with
Map, read MDN's page on it (opens new window) before continuing. You should be familiar with
Array methods (opens new window) as well. We will also use some ES6 features, so read up here if you do not know what they are.
Map allows for an association between unique keys and their values.
For example, how can you transform every value or filter the entries in a
This is the point of the
# Array-like Methods
Many of the methods on
Collection correspond to their namesake in
Array. One of them is
// Assume we have an array of users and a collection of the same users. array.find(u => u.discriminator === '1000'); collection.find(u => u.discriminator === '1000');
The interface of the callback function is very similar between the two.
For arrays, callbacks usually pass the parameters
(value, index, array), where
value is the value iterated to,
index is the current index, and
array is the array. For collections, you would have
(value, key, collection).
value is the same, but
key is the key of the value, and
collection is the collection itself instead.
Methods that follow this philosophy of staying close to the
Array interface are as follows:
filter- Note that this returns a
Collectionrather than an
map- Yet this returns an
Arrayof values instead of a
# Converting to Array
There are two ways you might want to convert a
Collection into an
Array. The first way is the
They create an array from the items in the collection but also caches it:
// Not computed the second time; it is cached! collection.array(); collection.array(); // Any change to the collection, however, invalidates the cache. // This call to `array` must be recomputed. collection.delete('81440962496172032'); collection.array();
This caching behavior is undesirable if you are planning to mutate the array, so instead, you can use
// For values. Array.from(collection.values()); // For keys. Array.from(collection.keys()); // For [key, value] pairs. Array.from(collection);
Many people use
array way too much! This leads to unneeded caching of data and confusing code. Before you use
array or similar, ask yourself if whatever you are trying to do can't be done with the given
Collection methods or with a for-of loop.
# Extra Utilities
Some methods are not from
// A random value. Be careful; this uses `array`, so caching is done. collection.random(); // The first value. collection.first(); // The first 5 values. collection.first(5); // Similar to `first`, but from the end. This uses `array`. collection.last(); collection.last(2); // Removes anything that meets the condition from the collection. // Sort of like `filter`, but in-place. collection.sweep(user => user.username === 'Bob');
A more complicated method is
partition, which splits a single Collection into two new Collections based on the provided function.
You can think of it as two
filters, but done at the same time:
// `bots` is a Collection of users where their `bot` property was true. // `humans` is a Collection where the property was false instead! const [bots, humans] = collection.partition(u => u.bot); // Both return true. bots.every(b => b.bot); humans.every(h => !h.bot);