@beatsphere/cache-utils

Three complementary in-memory cache implementations with zero dependencies. Battle-tested in BeatSphere.

Install

npm install @beatsphere/cache-utils

Caches

LRUCache

Least Recently Used cache with O(1) get/set. When full, evicts the item that hasn't been accessed the longest.

import { LRUCache } from '@beatsphere/cache-utils';

const cache = new LRUCache<string, object>(100); // max 100 items

cache.set('user:1', { name: 'Alice' });
cache.get('user:1'); // moves to most-recently-used
cache.size;          // 1
cache.getStats();    // { size: 1, maxSize: 100, utilizationPercent: 1 }

TTLCache

Time-to-live cache with automatic expiration and background cleanup.

import { TTLCache } from '@beatsphere/cache-utils';

const cache = new TTLCache<string, string>(
  30_000,   // 30s TTL
  500,      // max 500 items (default: 1000)
  60_000    // cleanup every 60s (default)
);

cache.set('token', 'abc123');
cache.get('token'); // 'abc123'

// After 30 seconds...
cache.get('token'); // undefined (expired)

// When done:
cache.destroy(); // stops cleanup interval

ETagCache

Stores HTTP ETags alongside response data for If-None-Match / 304 Not Modified flows.

import { ETagCache } from '@beatsphere/cache-utils';

const cache = new ETagCache(5 * 60 * 1000); // 5 min expiry (default)

// After a successful response:
cache.set('/api/users', response.headers.etag, response.data);

// Before the next request:
const etag = cache.getETag('/api/users');
if (etag) {
  // Send If-None-Match: etag
  // On 304: use cache.get('/api/users').data
}

API

LRUCache<K, V>

Method	Returns	Description
new LRUCache(maxSize)		Create cache with max capacity
get(key)	V | undefined	Get value, moves to most-recent
set(key, value)	void	Set value, evicts LRU if full
has(key)	boolean	Check existence
delete(key)	boolean	Remove entry
clear()	void	Remove all entries
size	number	Current item count
keys()	K[]	Keys, least to most recent
values()	V[]	Values, least to most recent
entries()	[K, V][]	Entries, least to most recent
getStats()	object	Size, maxSize, utilization %

TTLCache<K, V>

Method	Returns	Description
new TTLCache(ttlMs, maxSize?, cleanupMs?)		Create cache
get(key)	V | undefined	Get value if not expired
set(key, value)	void	Set value with TTL
has(key)	boolean	Check existence (non-expired)
delete(key)	boolean	Remove entry
clear()	void	Remove all entries
destroy()	void	Stop cleanup interval and clear
size	number	Current item count
keys()	K[]	All keys (may include expired)
values()	V[]	Non-expired values only
entries()	[K, V][]	Non-expired entries only
getStats()	object	Size, maxSize, ttlMs, utilization %

ETagCache

Method	Returns	Description
new ETagCache(maxAgeMs?)		Create cache (default: 5 min)
get(url)	{ etag, data } | null	Get cached entry
set(url, etag, data)	void	Store ETag + data
getETag(url)	string | null	Get just the ETag
delete(url)	void	Remove entry
clear()	void	Remove all entries
size	number	Current item count

License

MIT