enerthya.dev-cache

Real LRU + TTL cache for Enerthya. Zero external dependencies.

Features

• LRUCache — pure Least-Recently-Used cache. O(1) get/set/delete via doubly-linked-list + Map.
• TTLCache — LRU with per-entry expiration. Lazy eviction on access + explicit purgeExpired().
• createCache() — convenience factory that returns the right type depending on whether you pass a TTL.
• Drop-in replacement for fixedsize-map (.get() / .set() / .has() / .delete() / .size).

Installation

npm install enerthya.dev-cache

Usage

const { LRUCache, TTLCache, createCache } = require("enerthya.dev-cache");

// ── Plain LRU (no expiration) ─────────────────────────────────────────────────
const lru = new LRUCache(100);      // max 100 entries
lru.set("guild:123", settings);
lru.get("guild:123");               // returns value, promotes to MRU
lru.has("guild:123");               // true
lru.delete("guild:123");            // true if found
lru.clear();                        // remove all
lru.size;                           // current count

// ── LRU + TTL ─────────────────────────────────────────────────────────────────
const cache = new TTLCache(500, 5 * 60 * 1000);  // max 500, 5 min default TTL
cache.set("user:456", profile);                   // uses default TTL (5 min)
cache.set("short", data, 10_000);                 // 10 s override
cache.set("permanent", value, 0);                 // no expiration for this entry

cache.purgeExpired();               // proactively remove expired entries (returns count)
cache.entries();                    // [[key, value], ...] — expired skipped
cache.keys();                       // [key, ...] — expired skipped

// ── Factory ───────────────────────────────────────────────────────────────────
const c1 = createCache(100);         // → LRUCache(100)
const c2 = createCache(100, 60_000); // → TTLCache(100, 60_000)

Migration from fixedsize-map

| fixedsize-map | enerthya.dev-cache | |---|---| | new FixedSizeMap(n) | new LRUCache(n) or createCache(n) | | .add(key, val) | .set(key, val) | | .get(key) | .get(key) | | .contains(key) | .has(key) | | (no delete) | .delete(key) |

API

LRUCache(maxSize)

| Method | Description | |---|---| | get(key) | Returns value and promotes to MRU; undefined if missing | | peek(key) | Returns value without updating recency | | has(key) | Returns true if key exists | | set(key, value) | Sets value; evicts LRU if at capacity | | delete(key) | Removes key; returns true if existed | | clear() | Removes all entries | | entries() | IterableIterator<[key, value]> LRU → MRU | | keys() | key[] LRU → MRU | | size | Current entry count | | maxSize | Configured maximum |

TTLCache(maxSize, ttlMs = 0)

Same API as LRUCache, plus:

| Method | Description | |---|---| | set(key, value, ttlMs?) | Optional per-entry TTL override (0 = never expire) | | purgeExpired() | Proactively removes expired entries; returns count evicted | | entries() | Returns only live entries (expired ones are evicted on access) | | keys() | Returns only live keys |

createCache(maxSize?, ttlMs?)

Factory function. Returns LRUCache if ttlMs is 0 or omitted; TTLCache otherwise.

Running tests

node test.js

All tests use Node's built-in assert module — no external test runner required.