ts-cachecraft 1.0.0

package/dist/index.cjs

@@ -0,0 +1,2322 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ARCCache: () => ARCCache,
+  BaseCache: () => BaseCache,
+  ClockCache: () => ClockCache,
+  FIFOCache: () => FIFOCache,
+  LFUCache: () => LFUCache,
+  LIFOCache: () => LIFOCache,
+  LRUCache: () => LRUCache,
+  LRUKCache: () => LRUKCache,
+  MRUCache: () => MRUCache,
+  RRCache: () => RRCache,
+  SLRUCache: () => SLRUCache,
+  SieveCache: () => SieveCache,
+  TTLCache: () => TTLCache,
+  TwoTierCache: () => TwoTierCache,
+  WTinyLFUCache: () => WTinyLFUCache
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/base-cache.ts
+var BaseCache = class {
+  _capacity;
+  _hits = 0;
+  _misses = 0;
+  _evictions = 0;
+  onEvict;
+  listeners = /* @__PURE__ */ new Map();
+  constructor(options) {
+    const capacity = typeof options === "number" ? options : options.capacity;
+    if (capacity < 1) throw new RangeError("Cache capacity must be at least 1");
+    this._capacity = capacity;
+    if (typeof options === "object") {
+      this.onEvict = options.onEvict;
+    }
+  }
+  get capacity() {
+    return this._capacity;
+  }
+  stats() {
+    const total = this._hits + this._misses;
+    return {
+      hits: this._hits,
+      misses: this._misses,
+      evictions: this._evictions,
+      size: this.size,
+      capacity: this._capacity,
+      hitRate: total === 0 ? 0 : this._hits / total
+    };
+  }
+  snapshot() {
+    return {
+      entries: this.collectEntries(),
+      stats: this.stats(),
+      strategy: this.strategy
+    };
+  }
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+  }
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+  }
+  emit(detail) {
+    const set = this.listeners.get(detail.event);
+    if (set) {
+      for (const listener of set) {
+        listener(detail);
+      }
+    }
+  }
+  now() {
+    return Date.now();
+  }
+};
+
+// src/structures/doubly-linked-list.ts
+function createNode(key, value) {
+  return { key, value, prev: null, next: null, accessCount: 0 };
+}
+var DoublyLinkedList = class {
+  head;
+  tail;
+  _size = 0;
+  constructor() {
+    this.head = createNode("__head__", void 0);
+    this.tail = createNode("__tail__", void 0);
+    this.head.next = this.tail;
+    this.tail.prev = this.head;
+  }
+  get size() {
+    return this._size;
+  }
+  addToFront(node) {
+    node.next = this.head.next;
+    node.prev = this.head;
+    this.head.next.prev = node;
+    this.head.next = node;
+    this._size++;
+  }
+  addToBack(node) {
+    node.prev = this.tail.prev;
+    node.next = this.tail;
+    this.tail.prev.next = node;
+    this.tail.prev = node;
+    this._size++;
+  }
+  remove(node) {
+    if (!node.prev || !node.next) return;
+    node.prev.next = node.next;
+    node.next.prev = node.prev;
+    node.prev = null;
+    node.next = null;
+    this._size--;
+  }
+  moveToFront(node) {
+    this.remove(node);
+    this.addToFront(node);
+  }
+  moveToBack(node) {
+    this.remove(node);
+    this.addToBack(node);
+  }
+  removeLast() {
+    if (this._size === 0) return null;
+    const node = this.tail.prev;
+    this.remove(node);
+    return node;
+  }
+  removeFirst() {
+    if (this._size === 0) return null;
+    const node = this.head.next;
+    this.remove(node);
+    return node;
+  }
+  peekFirst() {
+    return this._size === 0 ? null : this.head.next;
+  }
+  peekLast() {
+    return this._size === 0 ? null : this.tail.prev;
+  }
+  clear() {
+    this.head.next = this.tail;
+    this.tail.prev = this.head;
+    this._size = 0;
+  }
+  *[Symbol.iterator]() {
+    let current = this.head.next;
+    while (current && current !== this.tail) {
+      yield current;
+      current = current.next;
+    }
+  }
+  toArray() {
+    const result = [];
+    for (const node of this) {
+      result.push(node);
+    }
+    return result;
+  }
+};
+
+// src/caches/dll-cache.ts
+var DLLCache = class extends BaseCache {
+  list = new DoublyLinkedList();
+  map = /* @__PURE__ */ new Map();
+  defaultTTL;
+  config;
+  constructor(options, config) {
+    super(options);
+    this.defaultTTL = options.ttl;
+    this.config = config;
+  }
+  get(key) {
+    const node = this.map.get(key);
+    if (!node) {
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    if (node.expiry && node.expiry <= this.now()) {
+      this.deleteNode(key, node);
+      this._misses++;
+      this.emit({ event: "expire", key, value: node.value, timestamp: this.now() });
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    node.lastAccessed = this.now();
+    node.accessCount = (node.accessCount ?? 0) + 1;
+    if (this.config.reorderOnGet) {
+      this.list.moveToFront(node);
+    }
+    this._hits++;
+    this.emit({ event: "get", key, value: node.value, timestamp: this.now() });
+    return node.value;
+  }
+  set(key, value, ttl) {
+    const now = this.now();
+    const effectiveTTL = ttl ?? this.defaultTTL;
+    const expiry = effectiveTTL ? now + effectiveTTL : void 0;
+    const existing = this.map.get(key);
+    if (existing) {
+      existing.value = value;
+      existing.lastAccessed = now;
+      existing.expiry = expiry;
+      existing.metadata = { ...existing.metadata, createdAt: existing.metadata?.createdAt ?? now };
+      if (this.config.reorderOnUpdate) {
+        this.list.moveToFront(existing);
+      }
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.map.size >= this._capacity) {
+      const evicted = this.config.evictPosition === "back" ? this.list.removeLast() : this.list.removeFirst();
+      if (evicted) {
+        this.map.delete(evicted.key);
+        this._evictions++;
+        this.onEvict?.(evicted.key, evicted.value);
+        this.emit({ event: "evict", key, value, evictedKey: evicted.key, evictedValue: evicted.value, timestamp: now });
+      }
+    }
+    const node = createNode(key, value);
+    node.metadata = { createdAt: now };
+    node.lastAccessed = now;
+    node.accessCount = 0;
+    node.expiry = expiry;
+    if (this.config.addPosition === "front") {
+      this.list.addToFront(node);
+    } else {
+      this.list.addToBack(node);
+    }
+    this.map.set(key, node);
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  delete(key) {
+    const node = this.map.get(key);
+    if (!node) return false;
+    this.deleteNode(key, node);
+    this.emit({ event: "delete", key, value: node.value, timestamp: this.now() });
+    return true;
+  }
+  has(key) {
+    const node = this.map.get(key);
+    if (!node) return false;
+    if (node.expiry && node.expiry <= this.now()) {
+      return false;
+    }
+    return true;
+  }
+  clear() {
+    this.list.clear();
+    this.map.clear();
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    return this.map.size;
+  }
+  *keys() {
+    for (const node of this.list) {
+      yield node.key;
+    }
+  }
+  *values() {
+    for (const node of this.list) {
+      yield node.value;
+    }
+  }
+  *entries() {
+    for (const node of this.list) {
+      yield [node.key, node.value];
+    }
+  }
+  collectEntries() {
+    const result = [];
+    for (const node of this.list) {
+      result.push({
+        key: node.key,
+        value: node.value,
+        createdAt: node.metadata?.createdAt ?? 0,
+        lastAccessed: node.lastAccessed ?? 0,
+        accessCount: node.accessCount ?? 0
+      });
+    }
+    return result;
+  }
+  deleteNode(key, node) {
+    this.list.remove(node);
+    this.map.delete(key);
+  }
+};
+
+// src/caches/lru.ts
+var LRUCache = class extends DLLCache {
+  constructor(options) {
+    super(options, {
+      reorderOnGet: true,
+      reorderOnUpdate: true,
+      addPosition: "front",
+      evictPosition: "back"
+    });
+  }
+  get strategy() {
+    return "LRU";
+  }
+};
+
+// src/caches/mru.ts
+var MRUCache = class extends DLLCache {
+  constructor(options) {
+    super(options, {
+      reorderOnGet: true,
+      reorderOnUpdate: true,
+      addPosition: "front",
+      evictPosition: "front"
+    });
+  }
+  get strategy() {
+    return "MRU";
+  }
+};
+
+// src/caches/lfu.ts
+var LFUCache = class extends BaseCache {
+  store = /* @__PURE__ */ new Map();
+  freqBuckets = /* @__PURE__ */ new Map();
+  minFrequency = 0;
+  constructor(options) {
+    super(options);
+  }
+  getOrCreateBucket(freq) {
+    let bucket = this.freqBuckets.get(freq);
+    if (!bucket) {
+      bucket = new DoublyLinkedList();
+      this.freqBuckets.set(freq, bucket);
+    }
+    return bucket;
+  }
+  incrementFrequency(meta) {
+    const oldFreq = meta.frequency;
+    const oldBucket = this.freqBuckets.get(oldFreq);
+    oldBucket.remove(meta.node);
+    if (oldBucket.size === 0 && this.minFrequency === oldFreq) {
+      this.minFrequency = oldFreq + 1;
+    }
+    meta.frequency = oldFreq + 1;
+    const newBucket = this.getOrCreateBucket(meta.frequency);
+    newBucket.addToFront(meta.node);
+  }
+  get(key) {
+    const meta = this.store.get(key);
+    if (!meta) {
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    this._hits++;
+    meta.accessCount++;
+    meta.lastAccessed = this.now();
+    this.incrementFrequency(meta);
+    this.emit({ event: "get", key, value: meta.node.value, timestamp: this.now() });
+    return meta.node.value;
+  }
+  set(key, value, _ttl) {
+    const existing = this.store.get(key);
+    if (existing) {
+      existing.node.value = value;
+      existing.lastAccessed = this.now();
+      existing.accessCount++;
+      this.incrementFrequency(existing);
+      this.emit({ event: "set", key, value, timestamp: this.now() });
+      return;
+    }
+    if (this.store.size >= this._capacity) {
+      this.evict();
+    }
+    const node = createNode(key, value);
+    const now = this.now();
+    const meta = {
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 1,
+      frequency: 1,
+      node
+    };
+    this.store.set(key, meta);
+    const bucket = this.getOrCreateBucket(1);
+    bucket.addToFront(node);
+    this.minFrequency = 1;
+    this.emit({ event: "set", key, value, timestamp: this.now() });
+  }
+  evict() {
+    const bucket = this.freqBuckets.get(this.minFrequency);
+    if (!bucket || bucket.size === 0) return;
+    const evicted = bucket.removeLast();
+    if (!evicted) return;
+    this.store.delete(evicted.key);
+    this._evictions++;
+    this.onEvict?.(evicted.key, evicted.value);
+    this.emit({
+      event: "evict",
+      key: evicted.key,
+      evictedKey: evicted.key,
+      evictedValue: evicted.value,
+      timestamp: this.now()
+    });
+  }
+  delete(key) {
+    const meta = this.store.get(key);
+    if (!meta) return false;
+    const bucket = this.freqBuckets.get(meta.frequency);
+    if (bucket) {
+      bucket.remove(meta.node);
+    }
+    this.store.delete(key);
+    this.emit({ event: "delete", key, value: meta.node.value, timestamp: this.now() });
+    return true;
+  }
+  has(key) {
+    return this.store.has(key);
+  }
+  clear() {
+    this.store.clear();
+    this.freqBuckets.clear();
+    this.minFrequency = 0;
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    return this.store.size;
+  }
+  *keys() {
+    for (const key of this.store.keys()) {
+      yield key;
+    }
+  }
+  *values() {
+    for (const meta of this.store.values()) {
+      yield meta.node.value;
+    }
+  }
+  *entries() {
+    for (const [key, meta] of this.store.entries()) {
+      yield [key, meta.node.value];
+    }
+  }
+  get strategy() {
+    return "LFU";
+  }
+  collectEntries() {
+    const result = [];
+    for (const [key, meta] of this.store.entries()) {
+      result.push({
+        key,
+        value: meta.node.value,
+        createdAt: meta.createdAt,
+        lastAccessed: meta.lastAccessed,
+        accessCount: meta.accessCount
+      });
+    }
+    return result;
+  }
+};
+
+// src/caches/ttl.ts
+var TTLCache = class extends BaseCache {
+  store = /* @__PURE__ */ new Map();
+  defaultTTL;
+  cleanupTimer = null;
+  constructor(options) {
+    super(options);
+    this.defaultTTL = options.ttl ?? 0;
+    if (this.defaultTTL > 0) {
+      this.cleanupTimer = setInterval(() => this.cleanup(), this.defaultTTL);
+    }
+  }
+  isExpired(entry) {
+    return entry.expiry > 0 && this.now() >= entry.expiry;
+  }
+  cleanup() {
+    for (const [key, entry] of this.store.entries()) {
+      if (this.isExpired(entry)) {
+        this.store.delete(key);
+        this.emit({
+          event: "expire",
+          key,
+          value: entry.value,
+          timestamp: this.now()
+        });
+      }
+    }
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    if (this.isExpired(entry)) {
+      this.store.delete(key);
+      this.emit({ event: "expire", key, value: entry.value, timestamp: this.now() });
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    this._hits++;
+    entry.accessCount++;
+    entry.lastAccessed = this.now();
+    this.emit({ event: "get", key, value: entry.value, timestamp: this.now() });
+    return entry.value;
+  }
+  set(key, value, ttl) {
+    const existing = this.store.get(key);
+    const now = this.now();
+    const effectiveTTL = ttl ?? this.defaultTTL;
+    const expiry = effectiveTTL > 0 ? now + effectiveTTL : 0;
+    if (existing && !this.isExpired(existing)) {
+      existing.value = value;
+      existing.lastAccessed = now;
+      existing.accessCount++;
+      existing.expiry = expiry;
+      existing.ttl = effectiveTTL;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (existing) {
+      this.store.delete(key);
+    }
+    if (this.store.size >= this._capacity) {
+      this.evict();
+    }
+    this.store.set(key, {
+      value,
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 1,
+      expiry,
+      ttl: effectiveTTL
+    });
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  evict() {
+    let oldestKey = null;
+    let oldestTime = Infinity;
+    for (const [key, entry] of this.store.entries()) {
+      if (this.isExpired(entry)) {
+        this.store.delete(key);
+        this._evictions++;
+        this.onEvict?.(key, entry.value);
+        this.emit({
+          event: "evict",
+          key,
+          evictedKey: key,
+          evictedValue: entry.value,
+          timestamp: this.now()
+        });
+        return;
+      }
+      if (entry.createdAt < oldestTime) {
+        oldestTime = entry.createdAt;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey !== null) {
+      const entry = this.store.get(oldestKey);
+      this.store.delete(oldestKey);
+      this._evictions++;
+      this.onEvict?.(oldestKey, entry.value);
+      this.emit({
+        event: "evict",
+        key: oldestKey,
+        evictedKey: oldestKey,
+        evictedValue: entry.value,
+        timestamp: this.now()
+      });
+    }
+  }
+  delete(key) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    this.store.delete(key);
+    this.emit({ event: "delete", key, value: entry.value, timestamp: this.now() });
+    return true;
+  }
+  has(key) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    return !this.isExpired(entry);
+  }
+  clear() {
+    this.store.clear();
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    let count = 0;
+    for (const entry of this.store.values()) {
+      if (!this.isExpired(entry)) {
+        count++;
+      }
+    }
+    return count;
+  }
+  *keys() {
+    for (const [key, entry] of this.store.entries()) {
+      if (!this.isExpired(entry)) {
+        yield key;
+      }
+    }
+  }
+  *values() {
+    for (const [, entry] of this.store.entries()) {
+      if (!this.isExpired(entry)) {
+        yield entry.value;
+      }
+    }
+  }
+  *entries() {
+    for (const [key, entry] of this.store.entries()) {
+      if (!this.isExpired(entry)) {
+        yield [key, entry.value];
+      }
+    }
+  }
+  get strategy() {
+    return "TTL";
+  }
+  collectEntries() {
+    const result = [];
+    for (const [key, entry] of this.store.entries()) {
+      if (!this.isExpired(entry)) {
+        result.push({
+          key,
+          value: entry.value,
+          createdAt: entry.createdAt,
+          lastAccessed: entry.lastAccessed,
+          accessCount: entry.accessCount,
+          ttl: entry.ttl
+        });
+      }
+    }
+    return result;
+  }
+  destroy() {
+    if (this.cleanupTimer !== null) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.clear();
+  }
+};
+
+// src/caches/fifo.ts
+var FIFOCache = class extends DLLCache {
+  constructor(options) {
+    super(options, {
+      reorderOnGet: false,
+      reorderOnUpdate: false,
+      addPosition: "back",
+      evictPosition: "front"
+    });
+  }
+  get strategy() {
+    return "FIFO";
+  }
+};
+
+// src/caches/lifo.ts
+var LIFOCache = class extends DLLCache {
+  constructor(options) {
+    super(options, {
+      reorderOnGet: false,
+      reorderOnUpdate: true,
+      addPosition: "front",
+      evictPosition: "front"
+    });
+  }
+  get strategy() {
+    return "LIFO";
+  }
+};
+
+// src/caches/rr.ts
+var RRCache = class extends BaseCache {
+  store = /* @__PURE__ */ new Map();
+  keyList = [];
+  constructor(options) {
+    super(options);
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    this._hits++;
+    entry.accessCount++;
+    entry.lastAccessed = this.now();
+    this.emit({ event: "get", key, value: entry.value, timestamp: this.now() });
+    return entry.value;
+  }
+  set(key, value, _ttl) {
+    const existing = this.store.get(key);
+    if (existing) {
+      existing.value = value;
+      existing.lastAccessed = this.now();
+      existing.accessCount++;
+      this.emit({ event: "set", key, value, timestamp: this.now() });
+      return;
+    }
+    if (this.store.size >= this._capacity) {
+      this.evict();
+    }
+    const now = this.now();
+    const keyIndex = this.keyList.length;
+    this.keyList.push(key);
+    this.store.set(key, {
+      value,
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 1,
+      keyIndex
+    });
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  evict() {
+    if (this.keyList.length === 0) return;
+    const randomIndex = Math.floor(Math.random() * this.keyList.length);
+    const evictedKey = this.keyList[randomIndex];
+    const entry = this.store.get(evictedKey);
+    this.removeKeyAtIndex(randomIndex);
+    this.store.delete(evictedKey);
+    this._evictions++;
+    this.onEvict?.(evictedKey, entry.value);
+    this.emit({
+      event: "evict",
+      key: evictedKey,
+      evictedKey,
+      evictedValue: entry.value,
+      timestamp: this.now()
+    });
+  }
+  removeKeyAtIndex(index) {
+    const lastIndex = this.keyList.length - 1;
+    if (index !== lastIndex) {
+      const lastKey = this.keyList[lastIndex];
+      this.keyList[index] = lastKey;
+      const lastEntry = this.store.get(lastKey);
+      if (lastEntry) {
+        lastEntry.keyIndex = index;
+      }
+    }
+    this.keyList.pop();
+  }
+  delete(key) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    this.removeKeyAtIndex(entry.keyIndex);
+    this.store.delete(key);
+    this.emit({ event: "delete", key, value: entry.value, timestamp: this.now() });
+    return true;
+  }
+  has(key) {
+    return this.store.has(key);
+  }
+  clear() {
+    this.store.clear();
+    this.keyList.length = 0;
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    return this.store.size;
+  }
+  *keys() {
+    for (const key of this.store.keys()) {
+      yield key;
+    }
+  }
+  *values() {
+    for (const entry of this.store.values()) {
+      yield entry.value;
+    }
+  }
+  *entries() {
+    for (const [key, entry] of this.store.entries()) {
+      yield [key, entry.value];
+    }
+  }
+  get strategy() {
+    return "RR";
+  }
+  collectEntries() {
+    const result = [];
+    for (const [key, entry] of this.store.entries()) {
+      result.push({
+        key,
+        value: entry.value,
+        createdAt: entry.createdAt,
+        lastAccessed: entry.lastAccessed,
+        accessCount: entry.accessCount
+      });
+    }
+    return result;
+  }
+};
+
+// src/caches/arc.ts
+var ARCCache = class extends BaseCache {
+  /** Adaptation parameter: target size of T1. */
+  p = 0;
+  /** T1: recent cache entries (seen once recently). */
+  t1 = new DoublyLinkedList();
+  /** T2: frequent cache entries (seen at least twice recently). */
+  t2 = new DoublyLinkedList();
+  /** B1: ghost list for recently evicted from T1 (keys only). */
+  b1 = new DoublyLinkedList();
+  /** B2: ghost list for recently evicted from T2 (keys only). */
+  b2 = new DoublyLinkedList();
+  t1Map = /* @__PURE__ */ new Map();
+  t2Map = /* @__PURE__ */ new Map();
+  b1Map = /* @__PURE__ */ new Map();
+  b2Map = /* @__PURE__ */ new Map();
+  metaMap = /* @__PURE__ */ new Map();
+  constructor(options) {
+    super(options);
+  }
+  get strategy() {
+    return "ARC";
+  }
+  get size() {
+    return this.t1.size + this.t2.size;
+  }
+  get(key) {
+    const now = this.now();
+    if (this.t1Map.has(key)) {
+      const node = this.t1Map.get(key);
+      this.t1.remove(node);
+      this.t1Map.delete(key);
+      this.t2.addToFront(node);
+      this.t2Map.set(key, node);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    if (this.t2Map.has(key)) {
+      const node = this.t2Map.get(key);
+      this.t2.moveToFront(node);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    this._misses++;
+    this.emit({ event: "get", key, value: void 0, timestamp: now });
+    return void 0;
+  }
+  set(key, value, _ttl) {
+    const now = this.now();
+    const c = this._capacity;
+    if (this.t1Map.has(key)) {
+      const node2 = this.t1Map.get(key);
+      node2.value = value;
+      this.t1.remove(node2);
+      this.t1Map.delete(key);
+      this.t2.addToFront(node2);
+      this.t2Map.set(key, node2);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.t2Map.has(key)) {
+      const node2 = this.t2Map.get(key);
+      node2.value = value;
+      this.t2.moveToFront(node2);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.b1Map.has(key)) {
+      const delta = this.b2.size >= this.b1.size ? 1 : Math.ceil(this.b2.size / (this.b1.size || 1));
+      this.p = Math.min(this.p + delta, c);
+      this.replace(key);
+      const ghostNode = this.b1Map.get(key);
+      this.b1.remove(ghostNode);
+      this.b1Map.delete(key);
+      const node2 = createNode(key, value);
+      this.t2.addToFront(node2);
+      this.t2Map.set(key, node2);
+      this.metaMap.set(key, { createdAt: now, lastAccessed: now, accessCount: 1 });
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.b2Map.has(key)) {
+      const delta = this.b1.size >= this.b2.size ? 1 : Math.ceil(this.b1.size / (this.b2.size || 1));
+      this.p = Math.max(this.p - delta, 0);
+      this.replace(key);
+      const ghostNode = this.b2Map.get(key);
+      this.b2.remove(ghostNode);
+      this.b2Map.delete(key);
+      const node2 = createNode(key, value);
+      this.t2.addToFront(node2);
+      this.t2Map.set(key, node2);
+      this.metaMap.set(key, { createdAt: now, lastAccessed: now, accessCount: 1 });
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    const l1 = this.t1.size + this.b1.size;
+    const l2 = this.t2.size + this.b2.size;
+    if (l1 === c) {
+      if (this.t1.size < c) {
+        const ghost = this.b1.removeLast();
+        if (ghost) {
+          this.b1Map.delete(ghost.key);
+        }
+        this.replace(key);
+      } else {
+        const evicted = this.t1.removeLast();
+        if (evicted) {
+          this.t1Map.delete(evicted.key);
+          this.metaMap.delete(evicted.key);
+          this._evictions++;
+          this.onEvict?.(evicted.key, evicted.value);
+          this.emit({
+            event: "evict",
+            key,
+            evictedKey: evicted.key,
+            evictedValue: evicted.value,
+            timestamp: now
+          });
+        }
+      }
+    } else if (l1 < c && l1 + l2 >= c) {
+      if (l1 + l2 >= 2 * c) {
+        const ghost = this.b2.removeLast();
+        if (ghost) {
+          this.b2Map.delete(ghost.key);
+        }
+      }
+      this.replace(key);
+    }
+    const node = createNode(key, value);
+    this.t1.addToFront(node);
+    this.t1Map.set(key, node);
+    this.metaMap.set(key, { createdAt: now, lastAccessed: now, accessCount: 1 });
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  delete(key) {
+    const now = this.now();
+    if (this.t1Map.has(key)) {
+      const node = this.t1Map.get(key);
+      this.t1.remove(node);
+      this.t1Map.delete(key);
+      this.metaMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: now });
+      return true;
+    }
+    if (this.t2Map.has(key)) {
+      const node = this.t2Map.get(key);
+      this.t2.remove(node);
+      this.t2Map.delete(key);
+      this.metaMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: now });
+      return true;
+    }
+    return false;
+  }
+  has(key) {
+    return this.t1Map.has(key) || this.t2Map.has(key);
+  }
+  clear() {
+    this.t1.clear();
+    this.t2.clear();
+    this.b1.clear();
+    this.b2.clear();
+    this.t1Map.clear();
+    this.t2Map.clear();
+    this.b1Map.clear();
+    this.b2Map.clear();
+    this.metaMap.clear();
+    this.p = 0;
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  *keys() {
+    for (const node of this.t1) {
+      yield node.key;
+    }
+    for (const node of this.t2) {
+      yield node.key;
+    }
+  }
+  *values() {
+    for (const node of this.t1) {
+      yield node.value;
+    }
+    for (const node of this.t2) {
+      yield node.value;
+    }
+  }
+  *entries() {
+    for (const node of this.t1) {
+      yield [node.key, node.value];
+    }
+    for (const node of this.t2) {
+      yield [node.key, node.value];
+    }
+  }
+  collectEntries() {
+    const result = [];
+    for (const node of this.t1) {
+      const meta = this.metaMap.get(node.key);
+      result.push({
+        key: node.key,
+        value: node.value,
+        createdAt: meta?.createdAt ?? 0,
+        lastAccessed: meta?.lastAccessed ?? 0,
+        accessCount: meta?.accessCount ?? 0
+      });
+    }
+    for (const node of this.t2) {
+      const meta = this.metaMap.get(node.key);
+      result.push({
+        key: node.key,
+        value: node.value,
+        createdAt: meta?.createdAt ?? 0,
+        lastAccessed: meta?.lastAccessed ?? 0,
+        accessCount: meta?.accessCount ?? 0
+      });
+    }
+    return result;
+  }
+  /**
+   * Replace: evict an entry from either T1 or T2 to make room.
+   * The evicted entry's key is moved to the corresponding ghost list.
+   */
+  replace(incomingKey) {
+    const now = this.now();
+    if (this.t1.size > 0 && (this.t1.size > this.p || this.t1.size === this.p && this.b2Map.has(incomingKey))) {
+      const evicted = this.t1.removeLast();
+      this.t1Map.delete(evicted.key);
+      this.metaMap.delete(evicted.key);
+      const ghost = createNode(evicted.key, void 0);
+      this.b1.addToFront(ghost);
+      this.b1Map.set(evicted.key, ghost);
+      this.trimGhostList(this.b1, this.b1Map);
+      this._evictions++;
+      this.onEvict?.(evicted.key, evicted.value);
+      this.emit({
+        event: "evict",
+        key: incomingKey,
+        evictedKey: evicted.key,
+        evictedValue: evicted.value,
+        timestamp: now
+      });
+    } else if (this.t2.size > 0) {
+      const evicted = this.t2.removeLast();
+      this.t2Map.delete(evicted.key);
+      this.metaMap.delete(evicted.key);
+      const ghost = createNode(evicted.key, void 0);
+      this.b2.addToFront(ghost);
+      this.b2Map.set(evicted.key, ghost);
+      this.trimGhostList(this.b2, this.b2Map);
+      this._evictions++;
+      this.onEvict?.(evicted.key, evicted.value);
+      this.emit({
+        event: "evict",
+        key: incomingKey,
+        evictedKey: evicted.key,
+        evictedValue: evicted.value,
+        timestamp: now
+      });
+    }
+  }
+  /** Cap a ghost list at capacity to prevent unbounded memory growth. */
+  trimGhostList(list, map) {
+    while (list.size > this._capacity) {
+      const removed = list.removeLast();
+      if (removed) {
+        map.delete(removed.key);
+      }
+    }
+  }
+};
+
+// src/caches/two-tier.ts
+var TwoTierCache = class extends BaseCache {
+  hotList = new DoublyLinkedList();
+  coldList = new DoublyLinkedList();
+  hotMap = /* @__PURE__ */ new Map();
+  coldMap = /* @__PURE__ */ new Map();
+  metaMap = /* @__PURE__ */ new Map();
+  hotCapacity;
+  coldCapacity;
+  promoteThreshold;
+  constructor(options) {
+    super({ capacity: options.hotCapacity + options.coldCapacity, onEvict: options.onEvict });
+    this.hotCapacity = options.hotCapacity;
+    this.coldCapacity = options.coldCapacity;
+    this.promoteThreshold = options.promoteThreshold ?? 2;
+  }
+  get strategy() {
+    return "TWO-TIER";
+  }
+  get size() {
+    return this.hotMap.size + this.coldMap.size;
+  }
+  get(key) {
+    const now = this.now();
+    if (this.hotMap.has(key)) {
+      const node = this.hotMap.get(key);
+      this.hotList.moveToFront(node);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    if (this.coldMap.has(key)) {
+      const node = this.coldMap.get(key);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      if (meta.accessCount >= this.promoteThreshold) {
+        this.coldList.remove(node);
+        this.coldMap.delete(key);
+        this.ensureHotCapacity(now, key);
+        this.hotList.addToFront(node);
+        this.hotMap.set(key, node);
+        meta.tier = "hot";
+      } else {
+        this.coldList.moveToFront(node);
+      }
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    this._misses++;
+    this.emit({ event: "get", key, value: void 0, timestamp: now });
+    return void 0;
+  }
+  set(key, value, _ttl) {
+    const now = this.now();
+    if (this.hotMap.has(key)) {
+      const node2 = this.hotMap.get(key);
+      node2.value = value;
+      this.hotList.moveToFront(node2);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.coldMap.has(key)) {
+      const node2 = this.coldMap.get(key);
+      node2.value = value;
+      this.coldList.moveToFront(node2);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    this.ensureColdCapacity(now, key);
+    const node = createNode(key, value);
+    this.coldList.addToFront(node);
+    this.coldMap.set(key, node);
+    this.metaMap.set(key, {
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 1,
+      tier: "cold"
+    });
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  delete(key) {
+    const now = this.now();
+    if (this.hotMap.has(key)) {
+      const node = this.hotMap.get(key);
+      this.hotList.remove(node);
+      this.hotMap.delete(key);
+      this.metaMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: now });
+      return true;
+    }
+    if (this.coldMap.has(key)) {
+      const node = this.coldMap.get(key);
+      this.coldList.remove(node);
+      this.coldMap.delete(key);
+      this.metaMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: now });
+      return true;
+    }
+    return false;
+  }
+  has(key) {
+    return this.hotMap.has(key) || this.coldMap.has(key);
+  }
+  clear() {
+    this.hotList.clear();
+    this.coldList.clear();
+    this.hotMap.clear();
+    this.coldMap.clear();
+    this.metaMap.clear();
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  *keys() {
+    for (const node of this.hotList) {
+      yield node.key;
+    }
+    for (const node of this.coldList) {
+      yield node.key;
+    }
+  }
+  *values() {
+    for (const node of this.hotList) {
+      yield node.value;
+    }
+    for (const node of this.coldList) {
+      yield node.value;
+    }
+  }
+  *entries() {
+    for (const node of this.hotList) {
+      yield [node.key, node.value];
+    }
+    for (const node of this.coldList) {
+      yield [node.key, node.value];
+    }
+  }
+  collectEntries() {
+    const result = [];
+    for (const node of this.hotList) {
+      const meta = this.metaMap.get(node.key);
+      result.push({
+        key: node.key,
+        value: node.value,
+        createdAt: meta?.createdAt ?? 0,
+        lastAccessed: meta?.lastAccessed ?? 0,
+        accessCount: meta?.accessCount ?? 0,
+        tier: "hot"
+      });
+    }
+    for (const node of this.coldList) {
+      const meta = this.metaMap.get(node.key);
+      result.push({
+        key: node.key,
+        value: node.value,
+        createdAt: meta?.createdAt ?? 0,
+        lastAccessed: meta?.lastAccessed ?? 0,
+        accessCount: meta?.accessCount ?? 0,
+        tier: "cold"
+      });
+    }
+    return result;
+  }
+  /** Evict from hot tier if full, demoting LRU to cold tier. */
+  ensureHotCapacity(now, triggerKey) {
+    if (this.hotList.size >= this.hotCapacity) {
+      const evicted = this.hotList.removeLast();
+      if (evicted) {
+        this.hotMap.delete(evicted.key);
+        this.ensureColdCapacity(now, triggerKey);
+        this.coldList.addToBack(evicted);
+        this.coldMap.set(evicted.key, evicted);
+        const meta = this.metaMap.get(evicted.key);
+        if (meta) meta.tier = "cold";
+      }
+    }
+  }
+  /** Evict LRU from cold tier if full (permanent eviction). */
+  ensureColdCapacity(now, triggerKey) {
+    if (this.coldList.size >= this.coldCapacity) {
+      const evicted = this.coldList.removeLast();
+      if (evicted) {
+        this.coldMap.delete(evicted.key);
+        this.metaMap.delete(evicted.key);
+        this._evictions++;
+        this.onEvict?.(evicted.key, evicted.value);
+        this.emit({
+          event: "evict",
+          key: triggerKey ?? evicted.key,
+          evictedKey: evicted.key,
+          evictedValue: evicted.value,
+          timestamp: now
+        });
+      }
+    }
+  }
+};
+
+// src/caches/slru.ts
+var SLRUCache = class extends BaseCache {
+  probationList = new DoublyLinkedList();
+  protectedList = new DoublyLinkedList();
+  probationMap = /* @__PURE__ */ new Map();
+  protectedMap = /* @__PURE__ */ new Map();
+  metaMap = /* @__PURE__ */ new Map();
+  protectedCapacity;
+  probationCapacity;
+  constructor(options) {
+    super(options);
+    const ratio = options.protectedRatio ?? 0.8;
+    this.protectedCapacity = Math.max(1, Math.floor(options.capacity * ratio));
+    this.probationCapacity = Math.max(1, options.capacity - this.protectedCapacity);
+  }
+  get strategy() {
+    return "SLRU";
+  }
+  get size() {
+    return this.probationMap.size + this.protectedMap.size;
+  }
+  get(key) {
+    const now = this.now();
+    if (this.protectedMap.has(key)) {
+      const node = this.protectedMap.get(key);
+      this.protectedList.moveToFront(node);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    if (this.probationMap.has(key)) {
+      const node = this.probationMap.get(key);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this.probationList.remove(node);
+      this.probationMap.delete(key);
+      this.ensureProtectedCapacity(now, key);
+      this.protectedList.addToFront(node);
+      this.protectedMap.set(key, node);
+      meta.segment = "protected";
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    this._misses++;
+    this.emit({ event: "get", key, value: void 0, timestamp: now });
+    return void 0;
+  }
+  set(key, value, _ttl) {
+    const now = this.now();
+    if (this.protectedMap.has(key)) {
+      const node2 = this.protectedMap.get(key);
+      node2.value = value;
+      this.protectedList.moveToFront(node2);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.probationMap.has(key)) {
+      const node2 = this.probationMap.get(key);
+      node2.value = value;
+      this.probationList.moveToFront(node2);
+      const meta = this.metaMap.get(key);
+      meta.lastAccessed = now;
+      meta.accessCount++;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    this.ensureProbationCapacity(now, key);
+    const node = createNode(key, value);
+    this.probationList.addToFront(node);
+    this.probationMap.set(key, node);
+    this.metaMap.set(key, {
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 1,
+      segment: "probation"
+    });
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  delete(key) {
+    const now = this.now();
+    if (this.protectedMap.has(key)) {
+      const node = this.protectedMap.get(key);
+      this.protectedList.remove(node);
+      this.protectedMap.delete(key);
+      this.metaMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: now });
+      return true;
+    }
+    if (this.probationMap.has(key)) {
+      const node = this.probationMap.get(key);
+      this.probationList.remove(node);
+      this.probationMap.delete(key);
+      this.metaMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: now });
+      return true;
+    }
+    return false;
+  }
+  has(key) {
+    return this.protectedMap.has(key) || this.probationMap.has(key);
+  }
+  clear() {
+    this.probationList.clear();
+    this.protectedList.clear();
+    this.probationMap.clear();
+    this.protectedMap.clear();
+    this.metaMap.clear();
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  *keys() {
+    for (const node of this.protectedList) {
+      yield node.key;
+    }
+    for (const node of this.probationList) {
+      yield node.key;
+    }
+  }
+  *values() {
+    for (const node of this.protectedList) {
+      yield node.value;
+    }
+    for (const node of this.probationList) {
+      yield node.value;
+    }
+  }
+  *entries() {
+    for (const node of this.protectedList) {
+      yield [node.key, node.value];
+    }
+    for (const node of this.probationList) {
+      yield [node.key, node.value];
+    }
+  }
+  collectEntries() {
+    const result = [];
+    for (const node of this.protectedList) {
+      const meta = this.metaMap.get(node.key);
+      result.push({
+        key: node.key,
+        value: node.value,
+        createdAt: meta?.createdAt ?? 0,
+        lastAccessed: meta?.lastAccessed ?? 0,
+        accessCount: meta?.accessCount ?? 0,
+        metadata: { segment: "protected" }
+      });
+    }
+    for (const node of this.probationList) {
+      const meta = this.metaMap.get(node.key);
+      result.push({
+        key: node.key,
+        value: node.value,
+        createdAt: meta?.createdAt ?? 0,
+        lastAccessed: meta?.lastAccessed ?? 0,
+        accessCount: meta?.accessCount ?? 0,
+        metadata: { segment: "probation" }
+      });
+    }
+    return result;
+  }
+  /** If protected is full, demote LRU from protected to probation. */
+  ensureProtectedCapacity(now, triggerKey) {
+    if (this.protectedList.size >= this.protectedCapacity) {
+      const demoted = this.protectedList.removeLast();
+      if (demoted) {
+        this.protectedMap.delete(demoted.key);
+        this.ensureProbationCapacity(now, triggerKey);
+        this.probationList.addToBack(demoted);
+        this.probationMap.set(demoted.key, demoted);
+        const meta = this.metaMap.get(demoted.key);
+        if (meta) meta.segment = "probation";
+      }
+    }
+  }
+  /** Evict LRU from probation if full. */
+  ensureProbationCapacity(now, triggerKey) {
+    if (this.probationList.size >= this.probationCapacity) {
+      const evicted = this.probationList.removeLast();
+      if (evicted) {
+        this.probationMap.delete(evicted.key);
+        this.metaMap.delete(evicted.key);
+        this._evictions++;
+        this.onEvict?.(evicted.key, evicted.value);
+        this.emit({
+          event: "evict",
+          key: triggerKey ?? evicted.key,
+          evictedKey: evicted.key,
+          evictedValue: evicted.value,
+          timestamp: now
+        });
+      }
+    }
+  }
+};
+
+// src/caches/clock.ts
+var ClockCache = class extends BaseCache {
+  buffer;
+  map = /* @__PURE__ */ new Map();
+  // key -> index in buffer
+  hand = 0;
+  constructor(options) {
+    super(options);
+    this.buffer = Array.from({ length: this._capacity }).fill(null);
+  }
+  get(key) {
+    const idx = this.map.get(key);
+    if (idx === void 0) {
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    const entry = this.buffer[idx];
+    entry.refBit = true;
+    entry.lastAccessed = this.now();
+    entry.accessCount++;
+    this._hits++;
+    this.emit({ event: "get", key, value: entry.value, timestamp: this.now() });
+    return entry.value;
+  }
+  set(key, value, _ttl) {
+    const now = this.now();
+    const existingIdx = this.map.get(key);
+    if (existingIdx !== void 0) {
+      const entry = this.buffer[existingIdx];
+      entry.value = value;
+      entry.refBit = true;
+      entry.lastAccessed = now;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.map.size >= this._capacity) {
+      this.evict(key, value, now);
+    }
+    let idx = this.findEmptySlot();
+    if (idx === -1) {
+      idx = this.hand;
+    }
+    this.buffer[idx] = {
+      key,
+      value,
+      refBit: false,
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 0
+    };
+    this.map.set(key, idx);
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  findEmptySlot() {
+    for (let i = 0; i < this._capacity; i++) {
+      if (this.buffer[i] === null) return i;
+    }
+    return -1;
+  }
+  evict(newKey, newValue, now) {
+    while (true) {
+      const entry = this.buffer[this.hand];
+      if (entry) {
+        if (entry.refBit) {
+          entry.refBit = false;
+          this.hand = (this.hand + 1) % this._capacity;
+        } else {
+          this.map.delete(entry.key);
+          this._evictions++;
+          this.onEvict?.(entry.key, entry.value);
+          this.emit({
+            event: "evict",
+            key: newKey,
+            value: newValue,
+            evictedKey: entry.key,
+            evictedValue: entry.value,
+            timestamp: now
+          });
+          this.buffer[this.hand] = null;
+          this.hand = (this.hand + 1) % this._capacity;
+          return;
+        }
+      } else {
+        this.hand = (this.hand + 1) % this._capacity;
+        return;
+      }
+    }
+  }
+  delete(key) {
+    const idx = this.map.get(key);
+    if (idx === void 0) return false;
+    const entry = this.buffer[idx];
+    this.buffer[idx] = null;
+    this.map.delete(key);
+    this.emit({ event: "delete", key, value: entry.value, timestamp: this.now() });
+    return true;
+  }
+  has(key) {
+    return this.map.has(key);
+  }
+  clear() {
+    this.buffer.fill(null);
+    this.map.clear();
+    this.hand = 0;
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    return this.map.size;
+  }
+  *keys() {
+    for (const entry of this.buffer) {
+      if (entry) yield entry.key;
+    }
+  }
+  *values() {
+    for (const entry of this.buffer) {
+      if (entry) yield entry.value;
+    }
+  }
+  *entries() {
+    for (const entry of this.buffer) {
+      if (entry) yield [entry.key, entry.value];
+    }
+  }
+  get strategy() {
+    return "CLOCK";
+  }
+  collectEntries() {
+    const result = [];
+    for (const entry of this.buffer) {
+      if (entry) {
+        result.push({
+          key: entry.key,
+          value: entry.value,
+          createdAt: entry.createdAt,
+          lastAccessed: entry.lastAccessed,
+          accessCount: entry.accessCount
+        });
+      }
+    }
+    return result;
+  }
+};
+
+// src/structures/count-min-sketch.ts
+var CountMinSketch = class {
+  table;
+  width;
+  depth;
+  seeds;
+  _totalCount = 0;
+  maxCount;
+  constructor(width = 1024, depth = 4) {
+    this.width = width;
+    this.depth = depth;
+    this.maxCount = width * 10;
+    this.table = Array.from({ length: depth }, () => new Uint32Array(width));
+    this.seeds = Array.from({ length: depth }, (_, i) => i * 2654435769 + 1779033703);
+  }
+  hash(key, seed) {
+    let h = seed;
+    for (let i = 0; i < key.length; i++) {
+      h = Math.imul(h ^ key.charCodeAt(i), 1540483477);
+      h ^= h >>> 13;
+      h = Math.imul(h, 1540483477);
+      h ^= h >>> 15;
+    }
+    return (h >>> 0) % this.width;
+  }
+  increment(key) {
+    for (let i = 0; i < this.depth; i++) {
+      const idx = this.hash(key, this.seeds[i]);
+      this.table[i][idx]++;
+    }
+    this._totalCount++;
+    if (this._totalCount >= this.maxCount) {
+      this.halve();
+    }
+  }
+  estimate(key) {
+    let min = Infinity;
+    for (let i = 0; i < this.depth; i++) {
+      const idx = this.hash(key, this.seeds[i]);
+      min = Math.min(min, this.table[i][idx]);
+    }
+    return min;
+  }
+  halve() {
+    for (let i = 0; i < this.depth; i++) {
+      for (let j = 0; j < this.width; j++) {
+        this.table[i][j] = this.table[i][j] >>> 1;
+      }
+    }
+    this._totalCount = Math.floor(this._totalCount / 2);
+  }
+  reset() {
+    for (let i = 0; i < this.depth; i++) {
+      this.table[i].fill(0);
+    }
+    this._totalCount = 0;
+  }
+  get totalCount() {
+    return this._totalCount;
+  }
+};
+
+// src/caches/w-tiny-lfu.ts
+var WTinyLFUCache = class extends BaseCache {
+  sketch;
+  // Window LRU
+  windowList = new DoublyLinkedList();
+  windowMap = /* @__PURE__ */ new Map();
+  windowCapacity;
+  // Main cache: probation (cold) + protected (hot) segments
+  probationList = new DoublyLinkedList();
+  probationMap = /* @__PURE__ */ new Map();
+  protectedList = new DoublyLinkedList();
+  protectedMap = /* @__PURE__ */ new Map();
+  protectedCapacity;
+  mainCapacity;
+  constructor(options) {
+    super(options);
+    const windowRatio = options.windowRatio ?? 0.01;
+    this.windowCapacity = Math.max(1, Math.floor(this._capacity * windowRatio));
+    this.mainCapacity = this._capacity - this.windowCapacity;
+    this.protectedCapacity = Math.max(1, Math.floor(this.mainCapacity * 0.8));
+    this.sketch = new CountMinSketch(Math.max(256, this._capacity * 10), 4);
+  }
+  get(key) {
+    const now = this.now();
+    let node = this.windowMap.get(key);
+    if (node) {
+      node.lastAccessed = now;
+      node.accessCount = (node.accessCount ?? 0) + 1;
+      this.windowList.moveToFront(node);
+      this.sketch.increment(key);
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    node = this.probationMap.get(key);
+    if (node) {
+      node.lastAccessed = now;
+      node.accessCount = (node.accessCount ?? 0) + 1;
+      this.sketch.increment(key);
+      this.probationList.remove(node);
+      this.probationMap.delete(key);
+      this.ensureProtectedCapacity(key, node.value, now);
+      this.protectedList.addToFront(node);
+      this.protectedMap.set(key, node);
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    node = this.protectedMap.get(key);
+    if (node) {
+      node.lastAccessed = now;
+      node.accessCount = (node.accessCount ?? 0) + 1;
+      this.protectedList.moveToFront(node);
+      this.sketch.increment(key);
+      this._hits++;
+      this.emit({ event: "get", key, value: node.value, timestamp: now });
+      return node.value;
+    }
+    this._misses++;
+    this.emit({ event: "get", key, timestamp: now });
+    return void 0;
+  }
+  set(key, value, _ttl) {
+    const now = this.now();
+    let node = this.windowMap.get(key);
+    if (node) {
+      node.value = value;
+      node.lastAccessed = now;
+      this.windowList.moveToFront(node);
+      this.sketch.increment(key);
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    node = this.probationMap.get(key);
+    if (node) {
+      node.value = value;
+      node.lastAccessed = now;
+      this.sketch.increment(key);
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    node = this.protectedMap.get(key);
+    if (node) {
+      node.value = value;
+      node.lastAccessed = now;
+      this.protectedList.moveToFront(node);
+      this.sketch.increment(key);
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    this.sketch.increment(key);
+    if (this.windowMap.size >= this.windowCapacity) {
+      this.evictFromWindow(key, value, now);
+    }
+    const newNode = createNode(key, value);
+    newNode.metadata = { createdAt: now };
+    newNode.lastAccessed = now;
+    newNode.accessCount = 0;
+    this.windowList.addToFront(newNode);
+    this.windowMap.set(key, newNode);
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  evictFromWindow(newKey, newValue, now) {
+    const windowVictim = this.windowList.removeLast();
+    if (!windowVictim) return;
+    this.windowMap.delete(windowVictim.key);
+    const mainSize = this.probationMap.size + this.protectedMap.size;
+    if (mainSize < this.mainCapacity) {
+      this.probationList.addToFront(windowVictim);
+      this.probationMap.set(windowVictim.key, windowVictim);
+      return;
+    }
+    const mainVictim = this.probationList.peekLast();
+    if (!mainVictim) {
+      this._evictions++;
+      this.onEvict?.(windowVictim.key, windowVictim.value);
+      this.emit({
+        event: "evict",
+        key: newKey,
+        value: newValue,
+        evictedKey: windowVictim.key,
+        evictedValue: windowVictim.value,
+        timestamp: now
+      });
+      return;
+    }
+    const candidateFreq = this.sketch.estimate(windowVictim.key);
+    const victimFreq = this.sketch.estimate(mainVictim.key);
+    if (candidateFreq > victimFreq) {
+      this.probationList.removeLast();
+      this.probationMap.delete(mainVictim.key);
+      this._evictions++;
+      this.onEvict?.(mainVictim.key, mainVictim.value);
+      this.emit({
+        event: "evict",
+        key: newKey,
+        value: newValue,
+        evictedKey: mainVictim.key,
+        evictedValue: mainVictim.value,
+        timestamp: now
+      });
+      this.probationList.addToFront(windowVictim);
+      this.probationMap.set(windowVictim.key, windowVictim);
+    } else {
+      this._evictions++;
+      this.onEvict?.(windowVictim.key, windowVictim.value);
+      this.emit({
+        event: "evict",
+        key: newKey,
+        value: newValue,
+        evictedKey: windowVictim.key,
+        evictedValue: windowVictim.value,
+        timestamp: now
+      });
+    }
+  }
+  ensureProtectedCapacity(newKey, newValue, now) {
+    if (this.protectedMap.size >= this.protectedCapacity) {
+      const demoted = this.protectedList.removeLast();
+      if (demoted) {
+        this.protectedMap.delete(demoted.key);
+        this.probationList.addToFront(demoted);
+        this.probationMap.set(demoted.key, demoted);
+      }
+    }
+    const mainSize = this.probationMap.size + this.protectedMap.size;
+    if (mainSize >= this.mainCapacity) {
+      const victim = this.probationList.removeLast();
+      if (victim) {
+        this.probationMap.delete(victim.key);
+        this._evictions++;
+        this.onEvict?.(victim.key, victim.value);
+        this.emit({
+          event: "evict",
+          key: newKey,
+          value: newValue,
+          evictedKey: victim.key,
+          evictedValue: victim.value,
+          timestamp: now
+        });
+      }
+    }
+  }
+  delete(key) {
+    let node = this.windowMap.get(key);
+    if (node) {
+      this.windowList.remove(node);
+      this.windowMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: this.now() });
+      return true;
+    }
+    node = this.probationMap.get(key);
+    if (node) {
+      this.probationList.remove(node);
+      this.probationMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: this.now() });
+      return true;
+    }
+    node = this.protectedMap.get(key);
+    if (node) {
+      this.protectedList.remove(node);
+      this.protectedMap.delete(key);
+      this.emit({ event: "delete", key, value: node.value, timestamp: this.now() });
+      return true;
+    }
+    return false;
+  }
+  has(key) {
+    return this.windowMap.has(key) || this.probationMap.has(key) || this.protectedMap.has(key);
+  }
+  clear() {
+    this.windowList.clear();
+    this.windowMap.clear();
+    this.probationList.clear();
+    this.probationMap.clear();
+    this.protectedList.clear();
+    this.protectedMap.clear();
+    this.sketch.reset();
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    return this.windowMap.size + this.probationMap.size + this.protectedMap.size;
+  }
+  *keys() {
+    for (const node of this.windowList) yield node.key;
+    for (const node of this.protectedList) yield node.key;
+    for (const node of this.probationList) yield node.key;
+  }
+  *values() {
+    for (const node of this.windowList) yield node.value;
+    for (const node of this.protectedList) yield node.value;
+    for (const node of this.probationList) yield node.value;
+  }
+  *entries() {
+    for (const node of this.windowList) yield [node.key, node.value];
+    for (const node of this.protectedList) yield [node.key, node.value];
+    for (const node of this.probationList) yield [node.key, node.value];
+  }
+  get strategy() {
+    return "W-TINYLFU";
+  }
+  collectEntries() {
+    const result = [];
+    const collect = (list, tier) => {
+      for (const node of list) {
+        result.push({
+          key: node.key,
+          value: node.value,
+          createdAt: node.metadata?.createdAt ?? 0,
+          lastAccessed: node.lastAccessed ?? 0,
+          accessCount: node.accessCount ?? 0,
+          tier
+        });
+      }
+    };
+    collect(this.windowList, "cold");
+    collect(this.protectedList, "hot");
+    collect(this.probationList, "cold");
+    return result;
+  }
+};
+
+// src/caches/lru-k.ts
+var LRUKCache = class extends BaseCache {
+  store = /* @__PURE__ */ new Map();
+  k;
+  /** Keys with < K accesses, in insertion order for FIFO eviction. */
+  correlatedKeys = /* @__PURE__ */ new Set();
+  constructor(options) {
+    super(options);
+    this.k = options.k ?? 2;
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    const now = this.now();
+    const hadFullHistory = entry.history.length >= this.k;
+    entry.lastAccessed = now;
+    entry.accessCount++;
+    entry.history.push(now);
+    if (entry.history.length > this.k) {
+      entry.history.shift();
+    }
+    if (!hadFullHistory && entry.history.length >= this.k) {
+      this.correlatedKeys.delete(key);
+    }
+    this._hits++;
+    this.emit({ event: "get", key, value: entry.value, timestamp: now });
+    return entry.value;
+  }
+  set(key, value, _ttl) {
+    const now = this.now();
+    const existing = this.store.get(key);
+    if (existing) {
+      existing.value = value;
+      existing.lastAccessed = now;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.store.size >= this._capacity) {
+      this.evict(key, value, now);
+    }
+    this.store.set(key, {
+      key,
+      value,
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 0,
+      history: [now]
+    });
+    if (this.k > 1) {
+      this.correlatedKeys.add(key);
+    }
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  evict(newKey, newValue, now) {
+    let victimKey;
+    if (this.correlatedKeys.size > 0) {
+      let oldestTime = Infinity;
+      for (const key of this.correlatedKeys) {
+        const entry = this.store.get(key);
+        const firstAccess = entry.history[0];
+        if (firstAccess < oldestTime) {
+          oldestTime = firstAccess;
+          victimKey = key;
+        }
+      }
+      if (victimKey !== void 0) {
+        this.correlatedKeys.delete(victimKey);
+      }
+    } else {
+      let oldestKth = Infinity;
+      for (const [key, entry] of this.store) {
+        if (this.correlatedKeys.has(key)) continue;
+        const kthAccess = entry.history[0];
+        if (kthAccess < oldestKth) {
+          oldestKth = kthAccess;
+          victimKey = key;
+        }
+      }
+    }
+    if (victimKey !== void 0) {
+      const victim = this.store.get(victimKey);
+      this.store.delete(victimKey);
+      this._evictions++;
+      this.onEvict?.(victimKey, victim.value);
+      this.emit({
+        event: "evict",
+        key: newKey,
+        value: newValue,
+        evictedKey: victimKey,
+        evictedValue: victim.value,
+        timestamp: now
+      });
+    }
+  }
+  delete(key) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    this.store.delete(key);
+    this.correlatedKeys.delete(key);
+    this.emit({ event: "delete", key, value: entry.value, timestamp: this.now() });
+    return true;
+  }
+  has(key) {
+    return this.store.has(key);
+  }
+  clear() {
+    this.store.clear();
+    this.correlatedKeys.clear();
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    return this.store.size;
+  }
+  *keys() {
+    for (const key of this.store.keys()) {
+      yield key;
+    }
+  }
+  *values() {
+    for (const entry of this.store.values()) {
+      yield entry.value;
+    }
+  }
+  *entries() {
+    for (const entry of this.store.values()) {
+      yield [entry.key, entry.value];
+    }
+  }
+  get strategy() {
+    return "LRU-K";
+  }
+  collectEntries() {
+    const result = [];
+    for (const entry of this.store.values()) {
+      result.push({
+        key: entry.key,
+        value: entry.value,
+        createdAt: entry.createdAt,
+        lastAccessed: entry.lastAccessed,
+        accessCount: entry.accessCount
+      });
+    }
+    return result;
+  }
+};
+
+// src/caches/sieve.ts
+var SieveCache = class extends BaseCache {
+  head = null;
+  tail = null;
+  hand = null;
+  map = /* @__PURE__ */ new Map();
+  constructor(options) {
+    super(options);
+  }
+  get(key) {
+    const node = this.map.get(key);
+    if (!node) {
+      this._misses++;
+      this.emit({ event: "get", key, timestamp: this.now() });
+      return void 0;
+    }
+    node.visited = true;
+    node.lastAccessed = this.now();
+    node.accessCount++;
+    this._hits++;
+    this.emit({ event: "get", key, value: node.value, timestamp: this.now() });
+    return node.value;
+  }
+  set(key, value, _ttl) {
+    const now = this.now();
+    const existing = this.map.get(key);
+    if (existing) {
+      existing.value = value;
+      existing.visited = true;
+      existing.lastAccessed = now;
+      this.emit({ event: "set", key, value, timestamp: now });
+      return;
+    }
+    if (this.map.size >= this._capacity) {
+      this.evict(key, value, now);
+    }
+    const node = {
+      key,
+      value,
+      visited: false,
+      createdAt: now,
+      lastAccessed: now,
+      accessCount: 0,
+      prev: null,
+      next: null
+    };
+    if (this.head) {
+      node.next = this.head;
+      this.head.prev = node;
+      this.head = node;
+    } else {
+      this.head = node;
+      this.tail = node;
+    }
+    this.map.set(key, node);
+    this.emit({ event: "set", key, value, timestamp: now });
+  }
+  evict(newKey, newValue, now) {
+    let candidate = this.hand ?? this.tail;
+    if (!candidate) return;
+    while (candidate.visited) {
+      candidate.visited = false;
+      candidate = candidate.next ?? this.head;
+    }
+    this.hand = candidate.next ?? this.head;
+    if (this.hand === candidate) {
+      this.hand = null;
+    }
+    this.removeNode(candidate);
+    this.map.delete(candidate.key);
+    this._evictions++;
+    this.onEvict?.(candidate.key, candidate.value);
+    this.emit({
+      event: "evict",
+      key: newKey,
+      value: newValue,
+      evictedKey: candidate.key,
+      evictedValue: candidate.value,
+      timestamp: now
+    });
+  }
+  delete(key) {
+    const node = this.map.get(key);
+    if (!node) return false;
+    if (this.hand === node) {
+      this.hand = node.next ?? this.head;
+      if (this.hand === node) {
+        this.hand = null;
+      }
+    }
+    this.removeNode(node);
+    this.map.delete(key);
+    this.emit({ event: "delete", key, value: node.value, timestamp: this.now() });
+    return true;
+  }
+  has(key) {
+    return this.map.has(key);
+  }
+  clear() {
+    this.head = null;
+    this.tail = null;
+    this.hand = null;
+    this.map.clear();
+    this.emit({ event: "clear", key: "", timestamp: this.now() });
+  }
+  get size() {
+    return this.map.size;
+  }
+  *keys() {
+    let current = this.head;
+    while (current) {
+      yield current.key;
+      current = current.next;
+    }
+  }
+  *values() {
+    let current = this.head;
+    while (current) {
+      yield current.value;
+      current = current.next;
+    }
+  }
+  *entries() {
+    let current = this.head;
+    while (current) {
+      yield [current.key, current.value];
+      current = current.next;
+    }
+  }
+  get strategy() {
+    return "SIEVE";
+  }
+  collectEntries() {
+    const result = [];
+    let current = this.head;
+    while (current) {
+      result.push({
+        key: current.key,
+        value: current.value,
+        createdAt: current.createdAt,
+        lastAccessed: current.lastAccessed,
+        accessCount: current.accessCount
+      });
+      current = current.next;
+    }
+    return result;
+  }
+  removeNode(node) {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+    node.prev = null;
+    node.next = null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ARCCache,
+  BaseCache,
+  ClockCache,
+  FIFOCache,
+  LFUCache,
+  LIFOCache,
+  LRUCache,
+  LRUKCache,
+  MRUCache,
+  RRCache,
+  SLRUCache,
+  SieveCache,
+  TTLCache,
+  TwoTierCache,
+  WTinyLFUCache
+});