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
Section titled “Import”import { Cache } from "lunibee";// or from the sub-package:import { Cache } from "@lunibee/collection";import { Cache } from "lunibee";// or from the sub-package:import { Cache } from "@lunibee/collection";Constructor
Section titled “Constructor”new Cache<K, V>(options?: CacheOptions)new Cache(options)| 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});import { Cache } from "lunibee";
const messageCache = new Cache({ maxSize: 500, ttl: 5 * 60 * 1000, // 5 minutes});Methods
Section titled “Methods”get(key)
Section titled “get(key)”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);const msg = messageCache.get(messageId);set(key, value)
Section titled “set(key, value)”Stores a value. Evicts the least recently used entry when maxSize is exceeded.
messageCache.set(message.id, message);messageCache.set(message.id, message);has(key)
Section titled “has(key)”Returns true if a live, non-expired entry exists.
if (!messageCache.has(id)) { // fetch from API}if (!messageCache.has(id)) { // fetch from API}delete(key)
Section titled “delete(key)”Removes a single entry.
messageCache.delete(messageId);messageCache.delete(messageId);clear()
Section titled “clear()”Removes all entries.
invalidate(predicate)
Section titled “invalidate(predicate)”Removes all entries matching a predicate. Returns the number removed.
const count = messageCache.invalidate((msg, id) => msg.channelId === channelId);const count = messageCache.invalidate((msg, id) => msg.channelId === channelId);sweep()
Section titled “sweep()”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.`);const expired = messageCache.sweep();console.log(`Swept ${expired} expired messages.`);values()
Section titled “values()”Returns an array of all live values, in the order they were first added.
entries()
Section titled “entries()”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).
dispose()
Section titled “dispose()”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);});process.on("SIGINT", () => { messageCache.dispose(); process.exit(0);});Examples
Section titled “Examples”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;}const guildPreviewCache = new Cache({ maxSize: 100, ttl: 10 * 60 * 1000, // 10 minutes});
async function getGuildPreview(guildId) { 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);});const messageCache = new Cache({ 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);});