Skip to content

Cache

Cache<K, V> is a bounded LRU (Least Recently Used) cache with optional TTL expiration. It is backed by Collection internally, exposing a subset of its API focused on lifecycle management.

A cache shared through Redis by every process is RedisCache.

import { Cache } from "lunibee";
// or from the sub-package:
import { Cache } from "@lunibee/collection";
new Cache<K, V>(options?: CacheOptions)
Option Type Default Description
maxSize number Infinity Maximum number of live entries. Evicts the least recently used when exceeded.
ttl number 0 (disabled) Entry lifetime in milliseconds.
jitter number 0 Fraction (0-1) of ttl randomly shaved off each entry’s lifetime when it is set, so entries stored together do not expire together. 0.2 gives each entry 80-100% of ttl; it never lives longer than ttl. Values outside 0-1 throw a RangeError.
sweepInterval number min(ttl, 60_000) Kept for compatibility; no longer needed. Expired entries are dropped at their deadline.
import { Cache } from "lunibee";
const messageCache = new Cache<string, Message>({
maxSize: 500,
ttl: 5 * 60 * 1000, // 5 minutes
});

Returns a live entry, or undefined if missing or expired. Promotes accessed entries to the “most recently used” position; it does not extend the TTL.

const msg = messageCache.get(messageId);

Stores a value. Evicts the least recently used entry when maxSize is exceeded.

messageCache.set(message.id, message);

Returns true if a live, non-expired entry exists.

if (!messageCache.has(id)) {
// fetch from API
}

Removes a single entry.

messageCache.delete(messageId);

Removes all entries.

Removes all entries matching a predicate. Returns the number removed.

const count = messageCache.invalidate((msg, id) => msg.channelId === channelId);

Removes expired entries now. Returns the count removed. Entries are also dropped by themselves at their deadline, so calling this is optional.

const expired = messageCache.sweep();
console.log(`Swept ${expired} expired messages.`);

Returns an array of all live values, in the order they were first added.

Returns an array of [key, value] pairs for all live entries, in the order they were first added.

Property returning the count of live entries (triggers a TTL sweep).

Kept for compatibility. There is no background sweep timer to stop any more (the cache’s single expiry timer is unref’d and never holds the process open), so calling it is optional.

process.on("SIGINT", () => {
messageCache.dispose();
process.exit(0);
});

Caching API responses

import { Cache } from "lunibee";
const guildPreviewCache = new Cache<string, Record<string, unknown>>({
maxSize: 100,
ttl: 10 * 60 * 1000, // 10 minutes
});
async function getGuildPreview(guildId: string) {
const cached = guildPreviewCache.get(guildId);
if (cached) return cached;
const preview = await client.fetchGuildPreview(guildId);
guildPreviewCache.set(guildId, preview);
return preview;
}

Per-channel message cache

import { Cache, type Message } from "lunibee";
const messageCache = new Cache<string, Message>({
maxSize: 1000,
ttl: 60 * 1000, // 60 seconds
sweepInterval: 10 * 1000, // accepted for compatibility; expiry no longer needs it
});
client.on("messageCreate", (message) => {
messageCache.set(message.id, message);
});
client.on("messageDelete", (data) => {
messageCache.delete(data.id);
});