@wolfstar/plugin-cache

npm install @wolfstar/plugin-cache

pnpm add @wolfstar/plugin-cache

yarn add @wolfstar/plugin-cache

bun add @wolfstar/plugin-cache

npm

Source

See the Plugins guide for how plugins from wolfstar-project/plugins fit alongside the core framework.

Description

@wolfstar/plugin-cache is the cache behind the managers of @wolfstar/plugin-gateway. A Cache is one Map-like EntityCache per Discord entity kind (guilds, users, channels, messages, members, roles, and more). It stores raw, JSON-serializable API data only. Building structures on top of it is the managers’ job, which lets the same data live in a Map or in Redis. Swapping the store never changes the call sites:

Store	Backed by	Extras
`createInMemoryCache`	`Map`s	Optional LRU bound, global or per entity
`createRedisCache`	Redis	Per-entity TTL, optional gzip or brotli compression
your own	anything	Implement `Cache`, every method may return a promise

Usage

Most of the time you hand the cache to a GatewayClient, which writes every dispatch into it:

import { createInMemoryCache } from '@wolfstar/plugin-cache';
import { GatewayClient } from '@wolfstar/plugin-gateway';

const client = new GatewayClient({
	intents: GatewayIntentBits.Guilds | GatewayIntentBits.GuildMessages,
	// Keep at most 1000 messages, every other entity cache is unbounded.
	cache: createInMemoryCache({ maxSize: { messages: 1_000 } })
});

You can also use it on its own with any gateway dispatch source:

import { attachCacheToGateway, createInMemoryCache } from '@wolfstar/plugin-cache';

const cache = createInMemoryCache();
const detach = attachCacheToGateway(gateway, cache, {
	onError: (error) => console.error(error)
});

const guild = await cache.guilds?.get(guildId);

applyGatewayDispatch also handles cascades. A CHANNEL_DELETE drops that channel’s messages and a GUILD_DELETE drops every entity of that guild. Reactions and poll votes update the cached message. Pass the bot’s user ID as clientUserId so the me flags are right.

Stars module

On framework 6.1 and later, list the ./module entry in modules in stars.config to add the package to the auto imports. It needs the optional @wolfstar/kit peer dependency, at ^0.2.0 || ^0.3.0.

// stars.config.ts
export default defineConfig({
	modules: ['@wolfstar/plugin-cache/module']
});

The module registers no plugin and takes no options. It reserves the cache key of stars.config for future options, so no other module can claim it. @wolfstar/plugin-gateway still constructs the cache.

Redis

createRedisCache takes any client that exposes the commands it needs, which an ioredis Redis or Cluster instance does as is:

import { createRedisCache } from '@wolfstar/plugin-cache';
import { Redis } from 'ioredis';

const cache = createRedisCache({
	redis: new Redis(process.env.REDIS_URL!),
	prefix: 'my-bot:cache',
	compression: 'gzip',
	compressionThreshold: 1024,
	ttl: { guilds: 60 * 60, users: 30 * 60 }
});

Option	Default	Description
`redis`	—	The client to use.
`prefix`	`"wolfstar:cache"`	Prefix of every key, stored as `<prefix>:<entity>:<key>`.
`compression`	`"none"`	`"gzip"`, `"brotli"`, or `"none"`.
`compressionThreshold`	`1024`	Minimum serialized size, in bytes, for a value to be compressed.
`codec`	`jsonCodec()`	Encodes and decodes values before compression.
`legacyCodecs`	`[]`	Former `codec` values still tagging entries.
`ttl`	`{}`	Time-to-live in seconds per entity cache. Omitted ones never expire.
`indexGuilds`	`true`	Index guild-scoped entity caches by guild.

Compressed values are tagged, so turning compression on or off never breaks reading existing values.

Infrastructure

Shared pieces

Platform helpers

Plugins

npm

Source

Description

Usage

Stars module

Redis

npm

Source

​Description

​Usage

​Stars module

​Redis

Description

Usage

Stars module

Redis