@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