Cache customization

Sometimes, you would like to be able to customize discord.js's caching behavior in order to reduce memory usage. To this end, discord.js provides you with two ways to do so:

  1. Limiting the size of caches.
  2. Periodically removing old items from caches.

DANGER

Customization of caching behavior is an advanced topic. It is very easy to introduce errors if your custom cache is not working as expected.

Limiting caches

When creating a new Clientopen in new window, you can limit the size of caches, which are specific to certain managers, using the makeCache option. Generally speaking, almost all your customizations can be done via the helper functions from the Optionsopen in new window class.

Below is the default settings, which will limit message caches.

const { Client, Options } = require('discord.js');

const client = new Client({
	makeCache: Options.cacheWithLimits(Options.DefaultMakeCacheSettings),
});
1
2
3
4
5

To change the cache behaviors for a type of manager, add it on top of the default settings. For example, you can make caches for reactions limited to 0 items i.e. the client won't cache reactions at all:

const client = new Client({
	makeCache: Options.cacheWithLimits({
		...Options.DefaultMakeCacheSettings,
		ReactionManager: 0,
	}),
});
1
2
3
4
5
6

DANGER

As noted in the documentation, customizing GuildManager, ChannelManager, GuildChannelManager, RoleManager, or PermissionOverwriteManager is unsupported! Functionality will break with any kind of customization.

We can further customize this by passing options to LimitedCollectionopen in new window, a special kind of collection that limits the number of items. In the example below, the client is configured so that:

  1. Only 200 guild members maximum may be cached per GuildMemberManager (essentially, per guild).
  2. We never remove a member if it is the client. This is especially important, so that the client can function correctly in guilds.
const client = new Client({
	makeCache: Options.cacheWithLimits({
		...Options.DefaultMakeCacheSettings,
		ReactionManager: 0,
		GuildMemberManager: {
			maxSize: 200,
			keepOverLimit: member => member.id === member.client.user.id,
		},
	}),
});
1
2
3
4
5
6
7
8
9
10

Sweeping caches

In addition to limiting caches, you can also periodically sweep and remove old items from caches. When creating a new Clientopen in new window, you can customize the sweepers option.

Below is the default settings, which will occasionally sweep threads.

const { Client, Options } = require('discord.js');

const client = new Client({
	sweepers: Options.DefaultSweeperSettings,
});
1
2
3
4
5

To change the sweep behavior, you specify the type of cache to sweep (SweeperKeyopen in new window) and the options for sweeping (SweepOptionsopen in new window). If the type of cache has a lifetime associated with it, such as invites, messages, or threads, then you can set the lifetime option to sweep items older than specified. Otherwise, you can set the filter option for any type of cache, which will select the items to sweep.

const client = new Client({
	sweepers: {
		...Options.DefaultSweeperSettings,
		messages: {
			interval: 3_600, // Every hour.
			lifetime: 1_800, // Remove messages older than 30 minutes.
		},
		users: {
			interval: 3_600, // Every hour.
			filter: () => user => user.bot && user.id !== user.client.user.id, // Remove all bots.
		},
	},
});
1
2
3
4
5
6
7
8
9
10
11
12
13

TIP

Take a look at the documentation for which types of cache you can sweep. Also look to see exactly what lifetime means for invites, messages, and threads!