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.

Import

TypeScript

import { Cache } from "lunibee";
// or from the sub-package:
import { Cache } from "@lunibee/collection";

JavaScript

import { Cache } from "lunibee";
// or from the sub-package:
import { Cache } from "@lunibee/collection";

Constructor

TypeScript

new Cache<K, V>(options?: CacheOptions)

JavaScript

new Cache<K, V>(options?: CacheOptions)

Option	Type	Default	Description
maxSize	number	Infinity	Maximum number of live entries. Evicts the oldest when exceeded.
ttl	number	0 (disabled)	Entry lifetime in milliseconds.
sweepInterval	number	min(ttl, 60_000)	How often the background sweeper runs.

TypeScript

import { Cache } from "lunibee";

const messageCache = new Cache<string, Message>({
  maxSize: 500,
  ttl: 5 * 60 * 1000, // 5 minutes
});

JavaScript

import { Cache } from "lunibee";

const messageCache = new Cache<string, Message>({
  maxSize ,
  ttl: 5 * 60 * 1000, // 5 minutes
});

Methods

get(key)

Returns a live entry, or undefined if missing or expired. Promotes accessed entries to the “most recently used” position.

TypeScript

const msg = messageCache.get(messageId);

JavaScript

const msg = messageCache.get(messageId);

set(key, value)

Stores a value. Evicts the oldest entry when maxSize is exceeded.

TypeScript

messageCache.set(message.id, message);

JavaScript

messageCache.set(message.id, message);

has(key)

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

TypeScript

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

JavaScript

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

delete(key)

Removes a single entry.

TypeScript

messageCache.delete(messageId);

JavaScript

messageCache.delete(messageId);

clear()

Removes all entries.

invalidate(predicate)

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

TypeScript

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

JavaScript

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

sweep()

Manually triggers a TTL sweep, removing expired entries. Returns the count removed.

TypeScript

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

JavaScript

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

values()

Returns an array of all live values.

entries()

Returns an array of [key, value] pairs for all live entries.

size

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

dispose()

Stops the background sweep timer. Call when you no longer need the cache to prevent memory leaks.

TypeScript

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

JavaScript

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

Examples

Caching API responses

TypeScript

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;
}

JavaScript

const guildPreviewCache = new Cache<string, Record<string, unknown>>({
  maxSize ,
  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

TypeScript

const messageCache = new Cache<string, Message>({
  maxSize: 1000,
  ttl: 60 * 1000,   // 60 seconds
  sweepInterval: 10 * 1000, // sweep every 10s
});

client.on("messageCreate", (message) => {
  messageCache.set(message.id, message);
});

client.on("messageDelete", (data) => {
  messageCache.delete(data.id);
});

JavaScript

const messageCache = new Cache<string, Message>({
  maxSize ,
  ttl: 60 * 1000,   // 60 seconds
  sweepInterval: 10 * 1000, // sweep every 10s
});

client.on("messageCreate", (message) => {
  messageCache.set(message.id, message);
});

client.on("messageDelete", (data) => {
  messageCache.delete(data.id);
});