Store methods

Data access

get(key)

Return the value for key, or undefined if absent or expired. A hit marks the entry as most-recently-used for LRU purposes.

store.get("user:alice"); // → { id: 1, name: 'Alice' } or undefined

peek(key)

Return a live value without changing its LRU recency. Use this when you want to inspect a value without affecting eviction order.

store.peek("user:alice"); // → { id: 1, name: 'Alice' } or undefined

has(key)

Whether a live (non-expired) entry exists for key. Does not affect LRU recency.

store.has("user:alice"); // → true or false

Writing

set(key, value, options?)

Store value under key. Overwrites any existing entry and marks the key as most-recently-used. May evict the LRU entry when maxEntries would be exceeded.

store.set("user:alice", { id: 1, name: "Alice" });
store.set("session:xyz", { user: "alice" }, { ttlMs: 3600000 });

Deletion

delete(key)

Remove the entry for key. Returns true if an entry was removed.

const removed = store.delete("user:alice"); // → true or false

clear()

Remove all entries.

store.clear();

Introspection

keys()

All live keys, ordered from least- to most-recently-used.

store.keys(); // → ['user:alice', 'user:bob']

values()

All live values, ordered from least- to most-recently-used.

store.values(); // → [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]

entries()

All live [key, value] pairs, ordered from least- to most-recently-used. Keys are relative to the view, matching keys(). Reading does not affect recency.

store.entries(); // → [['user:alice', { id: 1, name: 'Alice' }], ['user:bob', { id: 2, name: 'Bob' }]]

Use entries() when you need to iterate over both keys and values together, or to capture a snapshot of the store's current state.

// Export all entries as JSON
const snapshot = Object.fromEntries(store.entries());

size()

Number of live entries.

store.size(); // → 2

isEmpty()

Whether the store or namespace view contains no live entries.

store.isEmpty(); // → false

Time-to-live

ttl(key)

Remaining time-to-live for key in milliseconds, or undefined when the entry is absent, expired, or has no expiry. Does not affect LRU recency, so pollers can inspect freshness without pinning entries.

store.ttl("session:xyz"); // → 3599123 or undefined

touch(key, options?)

Refresh a live entry's LRU recency without changing its value, and restart its TTL from options.ttlMs or the store default when either is set (an existing expiry is otherwise kept). Emits no event. Returns false when key is absent or expired.

const refreshed = store.touch("session:xyz"); // → true or false
store.touch("session:xyz", { ttlMs: 7200000 }); // Extend TTL

Maintenance

sweep()

Eagerly remove every expired entry and return how many were removed. Expiry is otherwise lazy (checked on read), so long-lived stores with TTLs should call this periodically to reclaim memory.

const removed = store.sweep(); // → 3

flush()

Synchronously write the current entries to persistPath as JSON. Expired entries are swept first so they are never persisted. Throws if the store was created without persistPath.

Persistence is per-store: calling flush() on a namespace view writes the entire store (all namespaces), not just the view's entries.

store.flush();

Events

on(event, listener)

Subscribe to a lifecycle event. Listeners are store-wide regardless of which view they were registered on, fire synchronously in registration order, and receive the full (prefixed) key. A listener that throws is silently ignored so store operations can never fail because of an observer. Registering the same listener twice for one event is a no-op.

store.on("set", (key) => console.log(`Set: ${key}`));

off(event, listener)

Remove a listener previously registered with on. Unknown listeners are ignored.

store.off("set", listener);

Scoping

namespace(name)

Return a scoped view of this store. The view shares the store's data, maxEntries budget, TTL default, and persistence, but every key is transparently prefixed with name plus the ":" delimiter, so views with different names never see each other's entries.

keys(), size(), clear(), and sweep() on a view are scoped to the view's entries, and keys() reports keys relative to the view (the prefix is stripped). Calling namespace() on a view nests: keys of store.namespace("a").namespace("b") live under "a:b:".

name must be a non-empty string; otherwise a TypeError is thrown.

const users = store.namespace("users");
users.set("alice", { id: 1 });
users.keys(); // → ['alice']
store.keys(); // → ['users:alice']