@whirlybird/cache

Warning whirlybird is experimental software. Use at your own risk!

About

A simple in-memory cache system for data received from the Discord WebSocket API.

Ecosystem

Discover the rest of the whirlybird ecosystem!

Installing

Using Node.js

You will need Node.js v18.x.x or higher.

Install with the package manager of your choice:

$ npm i @whirlybird/cache
$ pnpm i @whirlybird/cache
$ yarn add @whirlybird/cache

Enable ECMAScript modules (ESM) for your project:

{
  "type": "module"
}

Using Deno

You will need Deno v1.26.x or higher.

Import for GitHub:

export * from "https://github.com/apacheli/whirlybird/raw/dev/core/http/lib.js";

Getting Started

Simply add WhirlyCache.update() into your handleEvent() function:

import { WhirlyCache } from "@whirlybird/cache";
import { Gateway } from "@whirlybird/gateway";

const cache = new WhirlyCache();

const handleEvent = (event, data) => {
  cache.update(event, data);

  switch (event) {
    // ...
  }
};

const gateway = new Gateway({
  handleEvent,
});

whirlybird does not cache by default. You should only toggle each option (as listed below) to true if you need to access that type of data. You should also use intents in conjunction with these options to only receive and process data from the WebSocket API that are necessary.

const cache = new WhirlyCache({
  channels: false,
  emojis: false,
  guilds: false,
  guildScheduledEvents: false,
  members: false,
  presences: false,
  roles: false,
  stageInstances: false,
  stickers: false,
  users: false,
  voiceStates: false,
});

You can also provide your own functions to create the structures. whirlybird will automatically use them when updating.

const cache = new WhirlyCache({
  createChannel: () => {/* ... */},
  createEmoji: () => {/* ... */},
  createGuild: () => {/* ... */},
  createGuildScheduledEvent: () => {/* ... */},
  createMember: () => {/* ... */},
  createPresence: () => {/* ... */},
  createRole: () => {/* ... */},
  createStageInstance: () => {/* ... */},
  createSticker: () => {/* ... */},
  createUser: () => {/* ... */},
  createVoiceState: () => {/* ... */},
  updateChannel: () => {/* ... */},
  updateEmoji: () => {/* ... */},
  updateGuild: () => {/* ... */},
  updateGuildScheduledEvent: () => {/* ... */},
  updateMember: () => {/* ... */},
  updatePresence: () => {/* ... */},
  updateRole: () => {/* ... */},
  updateStageInstance: () => {/* ... */},
  updateSticker: () => {/* ... */},
  updateUser: () => {/* ... */},
  updateVoiceState: () => {/* ... */},
});

All structures will be keyed as a BigInt. Learn more about them here.

// cache.guilds.get(123n);
const guild = {
  data: createGuild(),
  channels: new ExtendedMap(/* BigInt => channel (see below) */),
  emojis: new ExtendedMap(/* BigInt => createEmoji() */),
  guildScheduledEvents: new ExtendedMap(
    /* BigInt => createGuildScheduledEvent() */
  ),
  members: new ExtendedMap(/* BigInt => createMember() */),
  roles: new ExtendedMap(/* BigInt => createRole() */),
  stageInstances: new ExtendedMap(/* BigInt => createStageInstance() */),
  stickers: new ExtendedMap(/* BigInt => createSticker() */),
};

// cache.users.get(123n);
const user = {
  data: createUser(),
  presence: createPresence(),
  voiceState: createVoice(),
};

// cache.channels.get(123n);
// guild.channels.get(123n);
const channel = {
  data: createChannel(),
};

Note If you are using the default options, you should never see undefined being used explicitly. This is not the same as the property not existing on the structure. Please report it to our issue tracker as that is a bug!