@toreda/cache

TypeScript caches for different use cases.

Constructor params

Every cache type takes a single optional init object. The named wrappers accept the same object minus the cfg flags they pin, and TtlCache additionally requires cfg.ttl.

| Param | Purpose | Default | |---|---|---| | log | Log instance (LogLike) used for cache activity & diagnostic output. | None — logging disabled. | | cfg | Deep-partial, data-only config merged over defaults (see table below). | All defaults — simple FIFO + TTL behavior. | | itemValidator | Called on every add; return false to reject the item (onAddReject('validator')). | None — all items accepted. | | rng | Random source for the random eviction basis and sketch hashing. Inject for deterministic tests. | Math.random | | evictionTargetSelector | Escape hatch for eviction target selection rules no flag combination expresses. Returns the id to evict, or null to reject the incoming add. | None — selection follows cfg.evict. | | events | Observability callbacks (onItemAdd, onItemEvict, onItemExpire, onAddReject, …), fired synchronously post-commit. | {} — no callbacks. |

cfg options

| Option | Purpose | Default | |---|---|---| | capacityMax | Maximum number of items. 0 = unbounded. | 1000 | | initialSize | Initial size hint for an empty cache. | 0 | | ttl | Default TTL (seconds) for items added without an explicit ttl. 0 = never expire. | 30 | | get.countsAsAccess | A get call counts as an access for eviction accounting. | true | | get.slidesExpiration | A get refreshes the item's expiration window. | false | | has.countsAsAccess | A has call counts as an access for eviction accounting. | false | | has.slidesExpiration | A has refreshes the item's expiration window. | false | | touch.countsAsAccess | A touch call counts as an access for eviction accounting. | true | | prune.auto | Interval timer prunes expired items automatically. | false | | prune.interval | Seconds between auto-prune runs. | 10 | | prune.minDelay | Minimum seconds allowed between prune() calls. | 10 | | evict.basis | Metadata axis that chooses the eviction target: insertion, access, frequency, random, or none. | insertion | | evict.order | Direction along the basis: oldest or newest. | oldest | | evict.secondChance | Accessed items get one skip before eviction (CLOCK). | false | | evict.tieBreak | Tie-break for frequency ties: access or insertion. | access | | segments.enabled | Split the cache into probation + protected regions. | false | | segments.protectedRatio | Protected region size as a fraction of capacityMax. | 0.8 | | segments.probationRatio | Probation budget as a fraction of capacityMax (2Q A1in). | 0.25 | | segments.probationBasis | Basis used to pick a probation eviction target: access (SLRU) or insertion (2Q). | access | | segments.promoteOnHit | A probation-region hit promotes the item to protected. | true | | ghosts.enabled | Keep a bounded, ids-only registry of recently-evicted items. | false | | ghosts.sizeRatio | Ghost registry size as a fraction of capacityMax. | 0.5 | | ghosts.perSegment | Split ghosts into recency/frequency lists (ARC B1/B2). | false | | adaptive | Ghost hits shift the probation/protected balance (ARC's p). | false | | admission.policy | always admits every newcomer; frequency compares sketch estimates (W-TinyLFU). | always | | admission.windowRatio | W-TinyLFU entry window as a fraction of capacityMax. | 0.01 | | admission.sketchResetThreshold | Sketch counter-halving threshold. 0 = derived from capacity. | 0 |

events callbacks

Callbacks provide external visibility into cache state changes.

Every callback is optional and costs nothing when unset. Callbacks fire post-commit (state and stats already updated), synchronously, each wrapped in try/catch — a throwing callback is logged and never corrupts cache state.

| Event | Signature | Fired when | |---|---|---| | onItemAdd | (item, id) | An item is successfully added. | | onItemExpire | (item, id, timeAdded) | An item is removed because its TTL elapsed. Precedes onItemRemove. | | onItemEvict | (item, id) | An item is removed to make room at capacity. Precedes onItemRemove. | | onItemRemove | (item, id, reason) | Every single-item removal, after any specific event. Reasons: delete, evict, expire, overwrite. | | onAddReject | (item, reason) | An add call is refused. Reasons: validator, admission, capacity, duplicate, bad-id. | | onItemHit | (item, id, source) | A cache hit via get or touch (source names which). | | onItemMiss | (id) | A get miss. | | onCapacityIncrease | (oldMax, newMax) | Capacity is raised via setCapacity. | | onCapacityDecrease | (oldMax, newMax) | Capacity is lowered via setCapacity. | | onClear | (count) | Once per clear() / reset() with the number of items removed. | | onReset | () | By reset(), after onClear. | | onPrune | (removed) | Whenever prune() actually runs (not delay-gated), including when 0 items were removed. |

Single-item removals fire the specific event (onItemExpire / onItemEvict) first, then the general onItemRemove. Bulk clear() / reset() fire only onClear (and onReset) — never per-item events.

const cache = new LruCache<User>({
	cfg: {capacityMax: 500, ttl: 300},
	events: {
		onItemEvict: (item, id) => console.log(`evicted ${id}`),
		onItemExpire: (item, id) => console.log(`expired ${id}`),
		onAddReject: (item, reason) => console.warn(`add refused: ${reason}`)
	}
});

Usage

The base Cache is policy-agnostic — every behavior is a config flag with a default that reproduces simple FIFO + TTL behavior:

import {Cache} from '@toreda/cache';

interface User {
	[k: string]: unknown;
	id: string;
	name: string;
}

const cache = new Cache<User>({
	cfg: {capacityMax: 1000, ttl: 300},
	events: {
		onItemEvict: (item, id) => console.log(`evicted ${id}`)
	}
});

cache.add({id: 'u-1', name: 'Ada'});
const user = cache.getOrAdd('u-2', (id) => ({id, name: 'Grace'}));
console.log(cache.size, cache.get('u-1'));

Cache types

Named wrappers pin the eviction flags for a well-known replacement policy. Every type combines freely with the expiration axis (ttl, sliding, prune) — the eviction policy and TTL are independent.

| Type | Policy — who leaves at capacity | |---|---| | FifoCache | Oldest inserted item. | | LifoCache | Newest inserted item. | | LruCache | Least-recently used item. | | MruCache | Most-recently used item. | | LfuCache | Least-frequently used item (ties: least-recent). | | RandomCache | A uniformly random item (inject rng for determinism). | | TtlCache | Nothing — items leave only on TTL expiry (auto-pruned). Adds getRemainingTtl(id). | | ClockCache | Insertion order with a second-chance reprieve for accessed items (CLOCK). | | SlruCache | Segmented LRU — probation feeds a protected region; scan-resistant. | | TwoQueueCache | 2Q — FIFO probation + ghost list; re-referenced ids promote to the main region. | | ArcCache | ARC — adapts the recency/frequency balance from per-segment ghost hits. | | TinyLfuCache | W-TinyLFU — a frequency sketch gates admission; rare newcomers are refused. |

All examples below use the User interface defined above.

FifoCache

First-in, first-out. Insertion order alone decides the eviction target — reads never reorder anything:

import {FifoCache} from '@toreda/cache';

const cache = new FifoCache<User>({cfg: {capacityMax: 2}});

cache.add({id: 'a', name: 'Ada'});
cache.add({id: 'b', name: 'Grace'});
cache.get('a'); // Reads don't affect FIFO order.
cache.add({id: 'c', name: 'Edsger'}); // Evicts 'a' — the oldest insert.

LifoCache

Last-in, first-out — the newest insert is sacrificed to protect older entries:

import {LifoCache} from '@toreda/cache';

const cache = new LifoCache<User>({cfg: {capacityMax: 2}});

cache.add({id: 'a', name: 'Ada'});
cache.add({id: 'b', name: 'Grace'});
cache.add({id: 'c', name: 'Edsger'}); // Evicts 'b' — the newest insert; 'a' survives.

LruCache

Least-recently used. Every get / touch refreshes an item's recency:

import {LruCache} from '@toreda/cache';

const cache = new LruCache<User>({cfg: {capacityMax: 2}});

cache.add({id: 'a', name: 'Ada'});
cache.add({id: 'b', name: 'Grace'});
cache.get('a'); // 'a' is now most-recent.
cache.add({id: 'c', name: 'Edsger'}); // Evicts 'b' — least-recently used.

MruCache

Most-recently used — evicts the hottest item, useful for cyclic scans where the item you just read is the one you'll need last:

import {MruCache} from '@toreda/cache';

const cache = new MruCache<User>({cfg: {capacityMax: 2}});

cache.add({id: 'a', name: 'Ada'});
cache.add({id: 'b', name: 'Grace'});
cache.get('a'); // 'a' is now most-recent.
cache.add({id: 'c', name: 'Edsger'}); // Evicts 'a' — the most-recently used.

LfuCache

Least-frequently used. Each read increments a hit count; ties fall back to least-recent:

import {LfuCache} from '@toreda/cache';

const cache = new LfuCache<User>({cfg: {capacityMax: 2}});

cache.add({id: 'a', name: 'Ada'});
cache.add({id: 'b', name: 'Grace'});
cache.get('a');
cache.get('a'); // 'a' has 2 hits, 'b' has 0.
cache.add({id: 'c', name: 'Edsger'}); // Evicts 'b' — the least-frequently used.

RandomCache

Uniform random replacement. Inject rng to make eviction deterministic in tests:

import {RandomCache} from '@toreda/cache';

const cache = new RandomCache<User>({
	cfg: {capacityMax: 1000},
	rng: () => 0.42 // Optional — defaults to Math.random.
});

TtlCache

Pure expiration — no capacity evictions, items leave only when their (required) TTL elapses. An auto-prune timer sweeps expired items; call stopAutoPrune() when done with the cache:

import {TtlCache} from '@toreda/cache';

const cache = new TtlCache<User>({
	cfg: {ttl: 60} // Seconds. Required, and capacity is unbounded by default.
});

cache.add({id: 'a', name: 'Ada'});
cache.getRemainingTtl('a'); // Whole seconds until expiry, or null once gone.
cache.stopAutoPrune(); // Release the sweep timer on shutdown.

ClockCache

CLOCK (second-chance FIFO). A hand sweeps insertion order, but an accessed item gets one reprieve before eviction — LRU-like behavior without reordering on every read:

import {ClockCache} from '@toreda/cache';

const cache = new ClockCache<User>({cfg: {capacityMax: 2}});

cache.add({id: 'a', name: 'Ada'});
cache.add({id: 'b', name: 'Grace'});
cache.get('a'); // Marks 'a' referenced.
cache.add({id: 'c', name: 'Edsger'}); // 'a' is spared once; 'b' is evicted instead.

SlruCache

Segmented LRU. New items sit in probation; a hit promotes them into the protected region, so a one-time scan of new ids can't displace the working set:

import {SlruCache} from '@toreda/cache';

const cache = new SlruCache<User>({
	cfg: {
		capacityMax: 1000,
		segments: {protectedRatio: 0.8} // Optional — protected region share (default 0.8).
	}
});

TwoQueueCache

2Q. A FIFO probation queue (A1in) absorbs newcomers and a ghost list (A1out) remembers recent evictees — a quick re-reference admits an id straight into the main LRU region:

import {TwoQueueCache} from '@toreda/cache';

const cache = new TwoQueueCache<User>({
	cfg: {
		capacityMax: 1000,
		segments: {probationRatio: 0.25}, // Optional — A1in share (default 0.25).
		ghosts: {sizeRatio: 0.5} // Optional — A1out budget vs capacity (default 0.5).
	}
});

ArcCache

ARC. Self-tuning — per-segment ghost lists track whether recency or frequency evictions are being regretted, and the balance point adapts toward whichever is winning:

import {ArcCache} from '@toreda/cache';

const cache = new ArcCache<User>({
	cfg: {
		capacityMax: 1000,
		segments: {protectedRatio: 0.5} // Optional — ARC's starting balance point (default 0.5).
	}
});

TinyLfuCache

W-TinyLFU. A count-min sketch estimates access frequency, and a newcomer is only admitted over the resident eviction target when the sketch says it's at least as popular — add returns false when admission is refused:

import {TinyLfuCache} from '@toreda/cache';

const cache = new TinyLfuCache<User>({
	cfg: {
		capacityMax: 1000,
		admission: {
			windowRatio: 0.01, // Optional — entry window share (default 0.01).
			sketchResetThreshold: 100_000 // Optional — halve sketch counts after this many increments.
		}
	}
});

const admitted = cache.add({id: 'rare', name: 'One-hit wonder'});
// admitted === false when the frequency sketch refuses the newcomer at capacity.

Combining policies with expiration

Mix-and-match — an LRU cache with a 5-minute default TTL and sliding expiration on reads:

import {LruCache} from '@toreda/cache';

const cache = new LruCache<User>({
	cfg: {
		capacityMax: 500,
		ttl: 300,
		get: {slidesExpiration: true}
	}
});

Wrappers remove the flags they pin from the caller's cfg type, so contradictory combinations (e.g. asking an LruCache for FIFO eviction) are a compile-time error while orthogonal features still combine.

Source Code

@toreda/cache is an open source package provided under the MIT License. Download, clone, or check the complete project source here on Github. We welcome bug reports, comments, and pull requests.

Legal

License

MIT © Toreda, Inc.

Copyright

Copyright © 2019 - 2026 Toreda, Inc. All Rights Reserved.

Website

https://www.toreda.com