Question: What is the cache?

[JakeElder]

Which package is the feature request for?

discord.js

Feature

I can't find any documentation as to what the cache is, how it is populated and what strategy should be used for missed cache hits. Is documentation available?

I am using abstractions to reliably retrieve resources, IE if I am trying to retrieve a text channel, I will wrap it in an async function that first checks the cache, and then fetches the resource using it's non cache counterpart.

I feel like this is something that could be abstracted away from the end user. From a UX perspective I just want the resource, if it's from cache that's good but I don't want to have to create my own abstractions to use two different api's to retrieve a thing.

Is there documentation for the cache? Or would I have to look through the source to determine what it is?

Ideal solution or implementation

Cache Enabled

const client = new Client({ intents: [FLAGS.GUILDS] });
const guild = client.guilds.fetch(guildId);
// 1. Attempts to return cached channel first
// 2. Hits Discord API if cache miss
const channel = await guild.channels.get(id);

Cache Disabled

const client = new Client({ intents: [FLAGS.GUILDS], cache: false });
const guild = client.guilds.fetch(guildId);
// 1. Hits Discord API immediately as cache disabled
const channel = await guild.channels.get(id);

Granular Resource Control

const client = new Client({
  intents: [FLAGS.GUILDS],
  // Could also configure cache time etc
  cache: { resources: [RESOURCES.ROLE] },
});
const guild = client.guilds.fetch(guildId);
// 1. Hits Discord API without a cache check as
// `ClientOptions['cache']` is truthy and lacks `RESOURCES.CHANNELS`
const channel = await guild.channels.get(id);

Branching Based on Cache Hit

const branchBasedOnCache = (e) => {
  if (e.cacheHit) {
    console.log(`Cache hit for ${e.resourceType}`);
  } else {
    console.log(`Cache missed for ${e.resourceType}`);
  }
}
const client = new Client({ intents: [FLAGS.GUILDS] });
const guild = client.guilds.fetch(guildId);
client.on('resourceGet',  branchBasedOnCache);
const channel = await guild.channels.get(id);
client.off('resourceGet',  branchBasedOnCache);

Alternative solutions or implementations

No response

Other context

No response

[almostSouji]

Discord.js uses Collections, a homebrew extension of the regular JavaScript Map data structure to cache data it receives via both websocket and REST API response payloads.

To only access the cache you can access the .cache property of the respective manager instance or use the .resolve() method on the manager itself.

const m1 = guild.members.cache.get("someid");
const m2 = guild.members.resolve("someid");

To request data from the API, in case it is not yet available in the cache, you use the .fetch() method. It will by default check the cache and hit the API if nothing is found. As such it returns a Promise you need to handle accordingly.

const m1 = await guild.members.fetch("someid");

If you wish to always hit the API and ignore the currently cached version, you can do so using the force option as documented, for example, here (third example).

const m2 = await guild.members.fetch({ user: "someid", force: true });

Generally, the idea behind bots is that they receive most of the required data and its corresponding updates via the websocket connection, meaning the cached versions should generally be up to date. Accordingly, fetch checking the cache before hitting the API is a sensible default for most data lookups users are performing.

Should there be a reason to check against the API, the library allows this via the aforementioned force option in fetch calls. This should, however, be a conscious decision per request, instead of a "set and forget" global setting, for example in the Client constructor.

I hope this lifts the confusion a little.

[almostSouji]

PS: If you are looking for granular cache control regarding memory usage and size limits, you can find sweepers and makeCache on the ClientOptions documentation. Do note, however, that some parts of the library still depend on initial data and caches in library version 13.x, so you may be stripping some of the comfort discord.js offers in the form of getters by disabling caches entirely.