ts-cachecraft 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,543 @@
+/** Lifecycle events emitted by all cache implementations. */
+type CacheEvent = 'set' | 'get' | 'delete' | 'evict' | 'expire' | 'clear';
+/** Serializable representation of a single cached entry with metadata. */
+type CacheEntry<V> = {
+    key: string;
+    value: V;
+    createdAt: number;
+    lastAccessed: number;
+    accessCount: number;
+    ttl?: number;
+    tier?: 'hot' | 'cold';
+    metadata?: Record<string, unknown>;
+};
+/** Payload passed to event listeners on every cache operation. */
+type CacheEventDetail<V> = {
+    event: CacheEvent;
+    key: string;
+    value?: V;
+    evictedKey?: string;
+    evictedValue?: V;
+    timestamp: number;
+};
+/** Callback signature for cache event subscribers. */
+type CacheEventListener<V> = (detail: CacheEventDetail<V>) => void;
+/** Base configuration accepted by all cache constructors. */
+type CacheOptions<V = unknown> = {
+    capacity: number;
+    ttl?: number;
+    onEvict?: (key: string, value: V) => void;
+};
+/** Point-in-time performance counters returned by `stats()`. */
+type CacheStats = {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    capacity: number;
+    hitRate: number;
+};
+/** Full cache state returned by `snapshot()`, including entries and stats. */
+type CacheSnapshot<V> = {
+    entries: CacheEntry<V>[];
+    stats: CacheStats;
+    strategy: string;
+};
+/** Public interface implemented by every cache strategy. */
+type Cache<V = unknown> = {
+    get(key: string): V | undefined;
+    set(key: string, value: V, ttl?: number): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    readonly size: number;
+    readonly capacity: number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    stats(): CacheStats;
+    snapshot(): CacheSnapshot<V>;
+    on(event: CacheEvent, listener: CacheEventListener<V>): void;
+    off(event: CacheEvent, listener: CacheEventListener<V>): void;
+};
+/** Options for {@link TwoTierCache}. Total capacity is `hotCapacity + coldCapacity`. */
+type TwoTierOptions<V = unknown> = CacheOptions<V> & {
+    hotCapacity: number;
+    coldCapacity: number;
+    promoteThreshold?: number;
+};
+/** Options for {@link ARCCache}. Uses the base `CacheOptions` fields. */
+type ARCOptions<V = unknown> = CacheOptions<V>;
+/** Options for {@link SLRUCache}. `protectedRatio` controls the segment split. */
+type SLRUOptions<V = unknown> = CacheOptions<V> & {
+    protectedRatio?: number;
+};
+/** Options for {@link WTinyLFUCache}. `windowRatio` sizes the admission window. */
+type WTinyLFUOptions<V = unknown> = CacheOptions<V> & {
+    windowRatio?: number;
+};
+/** Options for {@link LRUKCache}. `k` sets the number of accesses to track. */
+type LRUKOptions<V = unknown> = CacheOptions<V> & {
+    k?: number;
+};
+
+/**
+ * Abstract foundation for all cache strategies.
+ *
+ * Provides shared infrastructure: capacity validation, hit/miss/eviction
+ * counters, the event pub-sub system, and `stats()`/`snapshot()` methods.
+ * Subclasses implement the storage and eviction logic.
+ */
+declare abstract class BaseCache<V> {
+    protected _capacity: number;
+    protected _hits: number;
+    protected _misses: number;
+    protected _evictions: number;
+    protected onEvict?: (key: string, value: V) => void;
+    private listeners;
+    constructor(options: CacheOptions<V> | number);
+    abstract get(key: string): V | undefined;
+    abstract set(key: string, value: V, ttl?: number): void;
+    abstract delete(key: string): boolean;
+    abstract has(key: string): boolean;
+    abstract clear(): void;
+    abstract get size(): number;
+    abstract keys(): IterableIterator<string>;
+    abstract values(): IterableIterator<V>;
+    abstract entries(): IterableIterator<[string, V]>;
+    abstract get strategy(): string;
+    protected abstract collectEntries(): CacheEntry<V>[];
+    get capacity(): number;
+    stats(): CacheStats;
+    snapshot(): CacheSnapshot<V>;
+    on(event: CacheEvent, listener: CacheEventListener<V>): void;
+    off(event: CacheEvent, listener: CacheEventListener<V>): void;
+    protected emit(detail: CacheEventDetail<V>): void;
+    protected now(): number;
+}
+
+/** Configuration flags that differentiate LRU, MRU, FIFO, and LIFO behavior. */
+type DLLCacheConfig = {
+    reorderOnGet: boolean;
+    reorderOnUpdate: boolean;
+    addPosition: 'front' | 'back';
+    evictPosition: 'front' | 'back';
+};
+/**
+ * Abstract cache backed by a doubly linked list and a HashMap.
+ *
+ * Provides O(1) get, set, and delete by combining a `Map` for key lookup
+ * with a `DoublyLinkedList` for ordering. The {@link DLLCacheConfig} flags
+ * control insertion position, eviction position, and whether accesses
+ * reorder entries, allowing LRU, MRU, FIFO, and LIFO to share this
+ * single implementation. Also supports optional per-entry TTL.
+ */
+declare abstract class DLLCache<V> extends BaseCache<V> {
+    private list;
+    private map;
+    private defaultTTL?;
+    private config;
+    constructor(options: CacheOptions<V>, config: DLLCacheConfig);
+    get(key: string): V | undefined;
+    set(key: string, value: V, ttl?: number): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    protected collectEntries(): CacheEntry<V>[];
+    private deleteNode;
+}
+
+/**
+ * Least Recently Used (LRU) cache.
+ *
+ * Evicts the entry that has not been accessed for the longest time. Every
+ * `get` or `set` promotes the entry to the front of the list, and eviction
+ * removes from the back. O(1) for all operations.
+ */
+declare class LRUCache<V> extends DLLCache<V> {
+    constructor(options: CacheOptions<V>);
+    get strategy(): string;
+}
+
+/**
+ * Most Recently Used (MRU) cache.
+ *
+ * Evicts the most recently accessed entry. Useful for sequential scan
+ * workloads where the item just accessed is unlikely to be needed again.
+ * O(1) for all operations.
+ */
+declare class MRUCache<V> extends DLLCache<V> {
+    constructor(options: CacheOptions<V>);
+    get strategy(): string;
+}
+
+/**
+ * Least Frequently Used (LFU) cache.
+ *
+ * Evicts the entry with the lowest access count. Groups entries into
+ * frequency buckets (each a doubly linked list) and tracks the minimum
+ * frequency. On eviction, removes the LRU entry from the min-frequency
+ * bucket. On access, promotes the entry to the next frequency bucket.
+ * O(1) for all operations.
+ */
+declare class LFUCache<V> extends BaseCache<V> {
+    private store;
+    private freqBuckets;
+    private minFrequency;
+    constructor(options: CacheOptions<V>);
+    private getOrCreateBucket;
+    private incrementFrequency;
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    private evict;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    get strategy(): string;
+    protected collectEntries(): CacheEntry<V>[];
+}
+
+/**
+ * Time-to-Live (TTL) cache.
+ *
+ * Expires entries after a configurable duration. Supports a global default
+ * TTL and per-key overrides via the `ttl` parameter on `set()`. Expiration
+ * is lazy (checked on access) with periodic background cleanup. Call
+ * `destroy()` to stop the cleanup timer when the cache is no longer needed.
+ */
+declare class TTLCache<V> extends BaseCache<V> {
+    private store;
+    private defaultTTL;
+    private cleanupTimer;
+    constructor(options: CacheOptions<V>);
+    private isExpired;
+    private cleanup;
+    get(key: string): V | undefined;
+    set(key: string, value: V, ttl?: number): void;
+    private evict;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    get strategy(): string;
+    protected collectEntries(): CacheEntry<V>[];
+    destroy(): void;
+}
+
+/**
+ * First In, First Out (FIFO) cache.
+ *
+ * Evicts the oldest inserted entry regardless of access pattern. New entries
+ * are appended to the back and eviction removes from the front. Accessing an
+ * entry does not change its position. O(1) for all operations.
+ */
+declare class FIFOCache<V> extends DLLCache<V> {
+    constructor(options: CacheOptions<V>);
+    get strategy(): string;
+}
+
+/**
+ * Last In, First Out (LIFO) cache.
+ *
+ * Evicts the most recently inserted entry (not the most recently accessed).
+ * New entries are added to the front and eviction also removes from the
+ * front. Accessing an entry does not change its position. O(1) for all
+ * operations.
+ */
+declare class LIFOCache<V> extends DLLCache<V> {
+    constructor(options: CacheOptions<V>);
+    get strategy(): string;
+}
+
+/**
+ * Random Replacement (RR) cache.
+ *
+ * Evicts a randomly chosen entry when the cache is full. Uses a contiguous
+ * key array alongside a Map: on eviction, picks a random index, swaps it
+ * with the last element, and pops for O(1) random removal. Immune to
+ * pathological access patterns that defeat deterministic strategies.
+ */
+declare class RRCache<V> extends BaseCache<V> {
+    private store;
+    private keyList;
+    constructor(options: CacheOptions<V>);
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    private evict;
+    private removeKeyAtIndex;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    get strategy(): string;
+    protected collectEntries(): CacheEntry<V>[];
+}
+
+/**
+ * Adaptive Replacement Cache (ARC).
+ *
+ * Self-tuning algorithm that balances recency and frequency by maintaining
+ * four lists: T1 (recent), T2 (frequent), and their ghost lists B1/B2
+ * (keys only, capped at capacity). A parameter `p` shifts the target size
+ * of T1 vs T2 based on which ghost list sees more hits, continuously
+ * adapting to the workload without manual tuning. O(1) for all operations.
+ *
+ * @see https://www.usenix.org/conference/fast-03/arc-self-tuning-low-overhead-replacement-cache
+ */
+declare class ARCCache<V> extends BaseCache<V> {
+    /** Adaptation parameter: target size of T1. */
+    private p;
+    /** T1: recent cache entries (seen once recently). */
+    private t1;
+    /** T2: frequent cache entries (seen at least twice recently). */
+    private t2;
+    /** B1: ghost list for recently evicted from T1 (keys only). */
+    private b1;
+    /** B2: ghost list for recently evicted from T2 (keys only). */
+    private b2;
+    private t1Map;
+    private t2Map;
+    private b1Map;
+    private b2Map;
+    private metaMap;
+    constructor(options: ARCOptions<V>);
+    get strategy(): string;
+    get size(): number;
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    protected collectEntries(): CacheEntry<V>[];
+    /**
+     * Replace: evict an entry from either T1 or T2 to make room.
+     * The evicted entry's key is moved to the corresponding ghost list.
+     */
+    private replace;
+    /** Cap a ghost list at capacity to prevent unbounded memory growth. */
+    private trimGhostList;
+}
+
+/**
+ * Two-Tier (Hot/Cold) cache.
+ *
+ * Separates entries into a hot tier and a cold tier, both internally LRU.
+ * New entries start in the cold tier. After `promoteThreshold` accesses an
+ * entry is promoted to hot. When the hot tier is full its LRU entry is
+ * demoted back to cold. When cold is full its LRU entry is permanently
+ * evicted. O(1) for all operations.
+ */
+declare class TwoTierCache<V> extends BaseCache<V> {
+    private hotList;
+    private coldList;
+    private hotMap;
+    private coldMap;
+    private metaMap;
+    private hotCapacity;
+    private coldCapacity;
+    private promoteThreshold;
+    constructor(options: TwoTierOptions<V>);
+    get strategy(): string;
+    get size(): number;
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    protected collectEntries(): CacheEntry<V>[];
+    /** Evict from hot tier if full, demoting LRU to cold tier. */
+    private ensureHotCapacity;
+    /** Evict LRU from cold tier if full (permanent eviction). */
+    private ensureColdCapacity;
+}
+
+/**
+ * Segmented LRU (SLRU) cache.
+ *
+ * Divides capacity into a probation segment and a protected segment
+ * (controlled by `protectedRatio`, default 0.8). New entries enter
+ * probation. A hit in probation promotes the entry to protected. When
+ * protected is full its LRU entry is demoted back to probation. Eviction
+ * always removes from probation's LRU end. O(1) for all operations.
+ */
+declare class SLRUCache<V> extends BaseCache<V> {
+    private probationList;
+    private protectedList;
+    private probationMap;
+    private protectedMap;
+    private metaMap;
+    private protectedCapacity;
+    private probationCapacity;
+    constructor(options: SLRUOptions<V>);
+    get strategy(): string;
+    get size(): number;
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    protected collectEntries(): CacheEntry<V>[];
+    /** If protected is full, demote LRU from protected to probation. */
+    private ensureProtectedCapacity;
+    /** Evict LRU from probation if full. */
+    private ensureProbationCapacity;
+}
+
+/**
+ * Clock (Second Chance) cache.
+ *
+ * Approximates LRU using a circular buffer and a sweeping clock hand.
+ * Each entry has a reference bit set to 1 on access. On eviction the hand
+ * sweeps the buffer: entries with bit=1 get cleared (second chance),
+ * the first entry with bit=0 is evicted. O(1) amortized for all operations.
+ */
+declare class ClockCache<V> extends BaseCache<V> {
+    private buffer;
+    private map;
+    private hand;
+    constructor(options: CacheOptions<V>);
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    private findEmptySlot;
+    private evict;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    get strategy(): string;
+    protected collectEntries(): CacheEntry<V>[];
+}
+
+/**
+ * Window Tiny Least Frequently Used (W-TinyLFU) cache.
+ *
+ * Near-optimal admission policy combining a small window LRU with a main
+ * segmented LRU (probation + protected) and a Count-Min Sketch for
+ * frequency estimation. New entries enter the window. When the window
+ * evicts, the candidate competes against the main cache's probation
+ * victim by estimated frequency, and the loser is discarded. The sketch
+ * periodically halves all counters to age out stale frequencies.
+ * O(1) for all operations.
+ *
+ * @see https://arxiv.org/abs/1512.00727
+ */
+declare class WTinyLFUCache<V> extends BaseCache<V> {
+    private sketch;
+    private windowList;
+    private windowMap;
+    private windowCapacity;
+    private probationList;
+    private probationMap;
+    private protectedList;
+    private protectedMap;
+    private protectedCapacity;
+    private mainCapacity;
+    constructor(options: WTinyLFUOptions<V>);
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    private evictFromWindow;
+    private ensureProtectedCapacity;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    get strategy(): string;
+    protected collectEntries(): CacheEntry<V>[];
+}
+
+/**
+ * LRU-K cache.
+ *
+ * Generalizes LRU by tracking the K-th most recent access time for each
+ * entry. Entries with fewer than K accesses (correlated group) are evicted
+ * first by oldest first-access time. Among fully-tracked entries, the one
+ * whose K-th access is oldest is evicted. With K=2, this effectively
+ * filters out one-time scans that would pollute a standard LRU cache.
+ * O(1) get/set, O(n) eviction (scans within each group).
+ *
+ * @see https://www.cs.cmu.edu/~christos/courses/721-resources/p297-o_neil.pdf
+ */
+declare class LRUKCache<V> extends BaseCache<V> {
+    private store;
+    private k;
+    /** Keys with < K accesses, in insertion order for FIFO eviction. */
+    private correlatedKeys;
+    constructor(options: LRUKOptions<V>);
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    private evict;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    get strategy(): string;
+    protected collectEntries(): CacheEntry<V>[];
+}
+
+/**
+ * SIEVE cache (NSDI'24).
+ *
+ * Uses lazy promotion and quick demotion for efficient eviction. New
+ * entries are inserted at the head of a FIFO queue with visited=false.
+ * On access, only a visited bit is set with no reordering. On eviction,
+ * a hand pointer sweeps toward the tail: visited entries get their bit
+ * cleared (retained), the first unvisited entry is evicted. Achieves
+ * competitive hit rates with LRU and W-TinyLFU while requiring fewer
+ * metadata updates per operation. O(1) get/set, O(k) amortized eviction.
+ *
+ * @see https://junchengyang.com/publication/nsdi24-SIEVE.pdf
+ */
+declare class SieveCache<V> extends BaseCache<V> {
+    private head;
+    private tail;
+    private hand;
+    private map;
+    constructor(options: CacheOptions<V>);
+    get(key: string): V | undefined;
+    set(key: string, value: V, _ttl?: number): void;
+    private evict;
+    delete(key: string): boolean;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[string, V]>;
+    get strategy(): string;
+    protected collectEntries(): CacheEntry<V>[];
+    private removeNode;
+}
+
+export { ARCCache, type ARCOptions, BaseCache, type Cache, type CacheEntry, type CacheEvent, type CacheEventDetail, type CacheEventListener, type CacheOptions, type CacheSnapshot, type CacheStats, ClockCache, FIFOCache, LFUCache, LIFOCache, LRUCache, LRUKCache, type LRUKOptions, MRUCache, RRCache, SLRUCache, type SLRUOptions, SieveCache, TTLCache, TwoTierCache, type TwoTierOptions, WTinyLFUCache, type WTinyLFUOptions };