tick-cache 1.0.0

package/dist/index.cjs

@@ -0,0 +1,718 @@
+"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, {
+  TtlWheelCache: () => TtlWheelCache
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/constants.ts
+var NIL = -1;
+var BUCKET_NONE = -1;
+var BUCKET_OVERFLOW = -2;
+
+// src/entry-store.ts
+function fillI32(arr, value) {
+  arr.fill(value);
+}
+var EntryStore = class {
+  maxEntries;
+  cap;
+  sizeAllocated;
+  // next fresh id
+  freeList;
+  // LIFO stack of free ids
+  freeCount;
+  // number of free ids in the stack
+  // SoA refs
+  keyRef;
+  valRef;
+  // SoA metadata
+  expiresTick;
+  ttlMs;
+  // Original TTL in milliseconds (for updateTTLOnGet)
+  wheelNext;
+  wheelPrev;
+  lruNext;
+  lruPrev;
+  wheelBucket;
+  constructor(opts) {
+    const { maxEntries } = opts;
+    if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+      throw new Error("maxEntries must be a positive integer");
+    }
+    this.maxEntries = maxEntries;
+    const initialCap = opts.initialCap ?? Math.min(1024, maxEntries);
+    if (!Number.isInteger(initialCap) || initialCap <= 0) {
+      throw new Error("initialCap must be a positive integer");
+    }
+    if (initialCap > maxEntries) {
+      throw new Error("initialCap cannot exceed maxEntries");
+    }
+    this.cap = initialCap;
+    this.sizeAllocated = 0;
+    this.freeList = new Int32Array(maxEntries);
+    this.freeCount = 0;
+    this.keyRef = new Array(this.cap);
+    this.valRef = new Array(this.cap);
+    this.expiresTick = new Uint32Array(this.cap);
+    this.ttlMs = new Uint32Array(this.cap);
+    this.wheelNext = new Int32Array(this.cap);
+    this.wheelPrev = new Int32Array(this.cap);
+    this.lruNext = new Int32Array(this.cap);
+    this.lruPrev = new Int32Array(this.cap);
+    this.wheelBucket = new Int32Array(this.cap);
+    fillI32(this.wheelNext, NIL);
+    fillI32(this.wheelPrev, NIL);
+    fillI32(this.lruNext, NIL);
+    fillI32(this.lruPrev, NIL);
+    fillI32(this.wheelBucket, BUCKET_NONE);
+  }
+  debug() {
+    return {
+      cap: this.cap,
+      sizeAllocated: this.sizeAllocated,
+      freeCount: this.freeCount
+    };
+  }
+  /**
+   * Allocate an entryId.
+   * Returns -1 if impossible (at maxEntries and no free slot).
+   */
+  allocId() {
+    if (this.freeCount > 0) {
+      const reused = this.freeList[--this.freeCount];
+      this.resetSlot(reused);
+      return reused;
+    }
+    if (this.sizeAllocated >= this.maxEntries) return -1;
+    const id = this.sizeAllocated++;
+    if (id >= this.cap) {
+      this.ensureCapacity(id + 1);
+    }
+    this.resetSlot(id);
+    return id;
+  }
+  /**
+   * Store key and value for the given entry ID.
+   * Should be called after allocating an entry ID.
+   */
+  setEntry(id, key, value) {
+    if (!Number.isInteger(id) || id < 0 || id >= this.cap) {
+      throw new Error(`invalid entryId: ${id}`);
+    }
+    this.keyRef[id] = key;
+    this.valRef[id] = value;
+  }
+  /**
+   * Free an entryId back to the free list.
+   * Throws on double-free.
+   */
+  freeId(id) {
+    if (!Number.isInteger(id) || id < 0 || id >= this.cap) {
+      throw new Error(`invalid entryId: ${id}`);
+    }
+    if (this.keyRef[id] === void 0) {
+      throw new Error(`double-free detected for entryId=${id}`);
+    }
+    this.resetSlot(id);
+    this.freeList[this.freeCount++] = id;
+  }
+  /**
+   * Reset all SoA fields for a slot to the neutral state.
+   */
+  resetSlot(id) {
+    this.keyRef[id] = void 0;
+    this.valRef[id] = void 0;
+    this.expiresTick[id] = 0;
+    this.ttlMs[id] = 0;
+    this.wheelNext[id] = NIL;
+    this.wheelPrev[id] = NIL;
+    this.lruNext[id] = NIL;
+    this.lruPrev[id] = NIL;
+    this.wheelBucket[id] = BUCKET_NONE;
+  }
+  /**
+   * Growth strategy: doubling, capped at maxEntries.
+   * Copies typed arrays.
+   */
+  ensureCapacity(required) {
+    if (required <= this.cap) return;
+    let newCap = this.cap;
+    while (newCap < required) {
+      const prevCap = newCap;
+      newCap = Math.min(newCap * 2, this.maxEntries);
+      if (newCap === prevCap) {
+        throw new Error(
+          `cannot grow capacity to ${required} (maxEntries=${this.maxEntries})`
+        );
+      }
+    }
+    this.keyRef.length = newCap;
+    this.valRef.length = newCap;
+    const oldExpires = this.expiresTick;
+    this.expiresTick = new Uint32Array(newCap);
+    this.expiresTick.set(oldExpires);
+    const oldTtlMs = this.ttlMs;
+    this.ttlMs = new Uint32Array(newCap);
+    this.ttlMs.set(oldTtlMs);
+    const oldWheelNext = this.wheelNext;
+    const oldWheelPrev = this.wheelPrev;
+    const oldLruNext = this.lruNext;
+    const oldLruPrev = this.lruPrev;
+    const oldWheelBucket = this.wheelBucket;
+    this.wheelNext = new Int32Array(newCap);
+    this.wheelPrev = new Int32Array(newCap);
+    this.lruNext = new Int32Array(newCap);
+    this.lruPrev = new Int32Array(newCap);
+    this.wheelBucket = new Int32Array(newCap);
+    fillI32(this.wheelNext, NIL);
+    fillI32(this.wheelPrev, NIL);
+    fillI32(this.lruNext, NIL);
+    fillI32(this.lruPrev, NIL);
+    fillI32(this.wheelBucket, BUCKET_NONE);
+    this.wheelNext.set(oldWheelNext);
+    this.wheelPrev.set(oldWheelPrev);
+    this.lruNext.set(oldLruNext);
+    this.lruPrev.set(oldLruPrev);
+    this.wheelBucket.set(oldWheelBucket);
+    this.cap = newCap;
+  }
+};
+
+// src/timer-wheel.ts
+function isPowerOfTwo(n) {
+  return n > 0 && (n & n - 1) === 0;
+}
+var TimerWheel = class {
+  store;
+  ticker;
+  wheelSize;
+  wheelMask;
+  horizonTicks;
+  budgetPerTick;
+  // Heads of bucket lists
+  wheelHeads;
+  // Overflow list head (uses store.wheelNext/Prev too)
+  overflowHead = NIL;
+  overflowCountApprox = 0;
+  // Current processed tick (discrete)
+  nowTick;
+  // continuation state when budget is exceeded mid-advance
+  pendingTargetTick = null;
+  constructor(opts) {
+    this.store = opts.store;
+    this.ticker = opts.ticker;
+    if (!Number.isInteger(opts.wheelSize) || opts.wheelSize < 2 || !isPowerOfTwo(opts.wheelSize)) {
+      throw new Error("wheelSize must be a power of two >= 2");
+    }
+    if (!Number.isInteger(opts.budgetPerTick) || opts.budgetPerTick <= 0) {
+      throw new Error("budgetPerTick must be a positive integer");
+    }
+    this.wheelSize = opts.wheelSize;
+    this.wheelMask = this.wheelSize - 1;
+    this.horizonTicks = this.wheelSize;
+    this.budgetPerTick = opts.budgetPerTick;
+    this.wheelHeads = new Int32Array(this.wheelSize);
+    this.wheelHeads.fill(NIL);
+    this.nowTick = opts.initialNowTick ?? this.ticker.nowTick();
+  }
+  stats() {
+    return {
+      nowTick: this.nowTick,
+      horizonTicks: this.horizonTicks,
+      overflowCountApprox: this.overflowCountApprox
+    };
+  }
+  /**
+   * Schedule or reschedule an entryId to expire at expTick.
+   * This method will unlink it from wherever it currently is (if any), then link it.
+   */
+  schedule(id, expTick) {
+    if (!Number.isInteger(expTick) || expTick < 0) {
+      throw new Error("expTick must be a non-negative integer");
+    }
+    if (expTick <= this.nowTick) {
+      throw new Error(
+        `Cannot schedule in the past: expTick=${expTick}, nowTick=${this.nowTick}`
+      );
+    }
+    this.unlink(id);
+    this.store.expiresTick[id] = expTick >>> 0;
+    const delta = expTick - this.nowTick;
+    if (delta > this.horizonTicks) {
+      this.linkOverflow(id);
+    } else {
+      const bucket = this.bucketOf(expTick);
+      this.linkWheelHead(id, bucket);
+    }
+  }
+  /**
+   * Unlink an id from wheel or overflow if it is linked. O(1).
+   */
+  unlink(id) {
+    const b = this.store.wheelBucket[id];
+    if (b === BUCKET_NONE) return;
+    if (b === BUCKET_OVERFLOW) {
+      this.unlinkOverflow(id);
+      return;
+    }
+    this.unlinkWheel(id, b);
+  }
+  /**
+   * Advance time to current ticker time (monotonic) and process expirations.
+   * Returns true if fully caught up, false if budget exceeded and needs another call.
+   */
+  advanceToNow(onExpire) {
+    const targetTick = this.ticker.nowTick();
+    return this.advanceToTick(targetTick, onExpire);
+  }
+  /**
+   * - Processes ticks in order: (nowTick+1 .. targetTick)
+   * - Drift is naturally coalesced by processing multiple ticks at once, but guarded by budget.
+   */
+  advanceToTick(targetTick, onExpire) {
+    if (!Number.isInteger(targetTick) || targetTick < 0) throw new Error("targetTick must be a non-negative integer");
+    if (this.pendingTargetTick !== null) {
+      targetTick = Math.max(targetTick, this.pendingTargetTick);
+    }
+    let processed = 0;
+    while (this.nowTick < targetTick) {
+      this.nowTick++;
+      processed += this.drainOverflowWithinHorizon(processed, onExpire);
+      if (processed >= this.budgetPerTick) {
+        this.pendingTargetTick = targetTick;
+        return false;
+      }
+      const bucket = this.bucketOf(this.nowTick);
+      processed += this.processBucket(bucket, processed, onExpire);
+      if (processed >= this.budgetPerTick) {
+        this.pendingTargetTick = targetTick;
+        return false;
+      }
+    }
+    this.pendingTargetTick = null;
+    return true;
+  }
+  // ---- Wheel internals ----
+  bucketOf(tick) {
+    return tick & this.wheelMask;
+  }
+  linkWheelHead(id, bucket) {
+    const head = this.wheelHeads[bucket];
+    this.store.wheelBucket[id] = bucket;
+    this.store.wheelPrev[id] = NIL;
+    this.store.wheelNext[id] = head;
+    if (head !== NIL) this.store.wheelPrev[head] = id;
+    this.wheelHeads[bucket] = id;
+  }
+  unlinkWheel(id, bucket) {
+    const prev = this.store.wheelPrev[id];
+    const next = this.store.wheelNext[id];
+    if (prev !== NIL) {
+      this.store.wheelNext[prev] = next;
+    } else {
+      this.wheelHeads[bucket] = next;
+    }
+    if (next !== NIL) {
+      this.store.wheelPrev[next] = prev;
+    }
+    this.store.wheelPrev[id] = NIL;
+    this.store.wheelNext[id] = NIL;
+    this.store.wheelBucket[id] = BUCKET_NONE;
+  }
+  // ---- Overflow internals ----
+  linkOverflow(id) {
+    const head = this.overflowHead;
+    this.store.wheelBucket[id] = BUCKET_OVERFLOW;
+    this.store.wheelPrev[id] = NIL;
+    this.store.wheelNext[id] = head;
+    if (head !== NIL) this.store.wheelPrev[head] = id;
+    this.overflowHead = id;
+    this.overflowCountApprox++;
+  }
+  unlinkOverflow(id) {
+    const prev = this.store.wheelPrev[id];
+    1;
+    const next = this.store.wheelNext[id];
+    3;
+    if (prev !== NIL) {
+      this.store.wheelNext[prev] = next;
+    } else {
+      this.overflowHead = next;
+    }
+    if (next !== NIL) {
+      this.store.wheelPrev[next] = prev;
+    }
+    this.store.wheelPrev[id] = NIL;
+    this.store.wheelNext[id] = NIL;
+    this.store.wheelBucket[id] = BUCKET_NONE;
+    if (this.overflowCountApprox > 0) this.overflowCountApprox--;
+  }
+  /**
+   * Move overflow entries into the wheel when they are close enough.
+   * Unsorted overflow list: we scan until we hit budget.
+   */
+  drainOverflowWithinHorizon(processedSoFar, onExpire) {
+    let processed = 0;
+    let cursor = this.overflowHead;
+    while (cursor !== NIL && processedSoFar + processed < this.budgetPerTick) {
+      const id = cursor;
+      const nextCursor = this.store.wheelNext[id];
+      const exp = this.store.expiresTick[id] >>> 0;
+      const delta = exp - this.nowTick;
+      if (delta <= this.horizonTicks) {
+        this.unlinkOverflow(id);
+        if (exp <= this.nowTick) {
+          onExpire(id);
+        } else {
+          this.linkWheelHead(id, this.bucketOf(exp));
+        }
+        processed++;
+      }
+      cursor = nextCursor;
+    }
+    return processed;
+  }
+  /**
+   * Process a wheel bucket (batch).
+   * For each entry:
+   * - if expired (expTick <= nowTick): expire
+   * - else: guardrail: move to correct bucket if necessary
+   */
+  processBucket(bucket, processedSoFar, onExpire) {
+    let processed = 0;
+    let cursor = this.wheelHeads[bucket];
+    while (cursor !== NIL && processedSoFar + processed < this.budgetPerTick) {
+      const id = cursor;
+      const nextCursor = this.store.wheelNext[id];
+      const exp = this.store.expiresTick[id] >>> 0;
+      if (exp <= this.nowTick) {
+        this.unlinkWheel(id, bucket);
+        onExpire(id);
+      } else {
+        const correctBucket = this.bucketOf(exp);
+        if (correctBucket !== bucket) {
+          this.unlinkWheel(id, bucket);
+          this.linkWheelHead(id, correctBucket);
+        }
+      }
+      processed++;
+      cursor = nextCursor;
+    }
+    return processed;
+  }
+};
+
+// src/monotone-time.ts
+var import_node_perf_hooks = require("perf_hooks");
+var PerfTimeSource = class {
+  nowMs() {
+    return import_node_perf_hooks.performance.now();
+  }
+};
+var MonotoneTicker = class {
+  tickMs;
+  time;
+  constructor(opts) {
+    if (!Number.isFinite(opts.tickMs) || opts.tickMs <= 0) {
+      throw new Error("tickMs must be > 0");
+    }
+    this.tickMs = opts.tickMs;
+    this.time = opts.time ?? new PerfTimeSource();
+  }
+  nowTick() {
+    const ms = this.time.nowMs();
+    return Math.floor(ms / this.tickMs);
+  }
+};
+
+// src/lru-list.ts
+var LruList = class {
+  store;
+  head;
+  tail;
+  constructor(store) {
+    this.store = store;
+    this.head = NIL;
+    this.tail = NIL;
+  }
+  /**
+   * Link an entry to the head of the LRU list (most recent position).
+   */
+  linkHead(id) {
+    const oldHead = this.head;
+    this.store.lruNext[id] = oldHead;
+    this.store.lruPrev[id] = NIL;
+    if (oldHead !== NIL) {
+      this.store.lruPrev[oldHead] = id;
+    } else {
+      this.tail = id;
+    }
+    this.head = id;
+  }
+  /**
+   * Remove an entry from the LRU list.
+   */
+  unlink(id) {
+    const prev = this.store.lruPrev[id];
+    const next = this.store.lruNext[id];
+    if (prev !== NIL) {
+      this.store.lruNext[prev] = next;
+    } else {
+      this.head = next;
+    }
+    if (next !== NIL) {
+      this.store.lruPrev[next] = prev;
+    } else {
+      this.tail = prev;
+    }
+    this.store.lruNext[id] = NIL;
+    this.store.lruPrev[id] = NIL;
+  }
+  /**
+   * Move an entry to the head (mark as recently used).
+   * Optimization: if already at head, does nothing.
+   */
+  touch(id) {
+    if (this.head === id) {
+      return;
+    }
+    this.unlink(id);
+    this.linkHead(id);
+  }
+  /**
+   * Get the tail (least recently used) entry ID.
+   * Returns NIL if the list is empty.
+   */
+  getTail() {
+    return this.tail;
+  }
+  /**
+   * Check if the list is empty.
+   */
+  isEmpty() {
+    return this.head === NIL;
+  }
+  /**
+   * Reset the list to empty state.
+   */
+  reset() {
+    this.head = NIL;
+    this.tail = NIL;
+  }
+};
+
+// src/ttl-wheel-cache.ts
+var TtlWheelCache = class {
+  // Core components
+  store;
+  wheel;
+  ticker;
+  keyIndex;
+  lru;
+  // Configuration
+  maxEntries;
+  updateTTLOnGet;
+  ttlAutopurge;
+  tickMs;
+  onDispose;
+  // Cleanup interval
+  intervalId;
+  constructor(options) {
+    this.maxEntries = options.maxEntries;
+    this.updateTTLOnGet = options.updateTTLOnGet ?? false;
+    this.ttlAutopurge = options.ttlAutopurge ?? true;
+    this.onDispose = options.onDispose;
+    this.tickMs = options.tickMs ?? 50;
+    const wheelSize = options.wheelSize ?? 4096;
+    const budgetPerTick = options.budgetPerTick ?? 2e5;
+    this.store = new EntryStore({
+      maxEntries: options.maxEntries
+    });
+    this.keyIndex = /* @__PURE__ */ new Map();
+    this.lru = new LruList(this.store);
+    this.ticker = new MonotoneTicker({
+      tickMs: this.tickMs,
+      time: options.time
+    });
+    this.wheel = new TimerWheel({
+      store: this.store,
+      ticker: this.ticker,
+      wheelSize,
+      budgetPerTick
+    });
+    if (this.ttlAutopurge) {
+      this.startCleanupInterval();
+    }
+  }
+  set(key, value, ttlMs) {
+    if (!this.ttlAutopurge) {
+      this.advanceWheel();
+    }
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+      return;
+    }
+    const existingId = this.keyIndex.get(key);
+    if (existingId !== void 0) {
+      const oldValue = this.store.valRef[existingId];
+      this.store.valRef[existingId] = value;
+      this.store.ttlMs[existingId] = ttlMs;
+      const expireTick = this.ticker.nowTick() + Math.floor(ttlMs / this.ticker.tickMs);
+      this.wheel.schedule(existingId, expireTick);
+      this.lru.touch(existingId);
+      if (this.onDispose && oldValue !== void 0) {
+        this.onDispose(key, oldValue, "set");
+      }
+    } else {
+      while (this.keyIndex.size >= this.maxEntries) {
+        const evicted = this.evictLru();
+        if (!evicted) {
+          throw new Error("Failed to evict LRU entry");
+        }
+      }
+      const id = this.store.allocId();
+      if (id === NIL) {
+        throw new Error("Failed to allocate entry ID");
+      }
+      this.store.setEntry(id, key, value);
+      this.store.ttlMs[id] = ttlMs;
+      this.keyIndex.set(key, id);
+      const expireTick = this.ticker.nowTick() + Math.floor(ttlMs / this.ticker.tickMs);
+      this.wheel.schedule(id, expireTick);
+      this.lru.linkHead(id);
+    }
+  }
+  get(key) {
+    if (!this.ttlAutopurge) {
+      this.advanceWheel();
+    }
+    const id = this.keyIndex.get(key);
+    if (id === void 0) {
+      return void 0;
+    }
+    const expireTick = this.store.expiresTick[id];
+    const nowTick = this.ticker.nowTick();
+    if (expireTick <= nowTick) {
+      this.onExpireEntry(id, "ttl");
+      return void 0;
+    }
+    this.lru.touch(id);
+    if (this.updateTTLOnGet) {
+      const ttl = this.store.ttlMs[id];
+      if (ttl > 0) {
+        const newExpireTick = this.ticker.nowTick() + Math.floor(ttl / this.ticker.tickMs);
+        this.wheel.schedule(id, newExpireTick);
+      }
+    }
+    return this.store.valRef[id];
+  }
+  has(key) {
+    if (!this.ttlAutopurge) {
+      this.advanceWheel();
+    }
+    const id = this.keyIndex.get(key);
+    if (id === void 0) {
+      return false;
+    }
+    const expireTick = this.store.expiresTick[id];
+    const nowTick = this.ticker.nowTick();
+    if (expireTick <= nowTick) {
+      this.onExpireEntry(id, "ttl");
+      return false;
+    }
+    return true;
+  }
+  delete(key) {
+    if (!this.ttlAutopurge) {
+      this.advanceWheel();
+    }
+    const id = this.keyIndex.get(key);
+    if (id === void 0) {
+      return false;
+    }
+    this.removeEntry(id, "delete");
+    return true;
+  }
+  clear() {
+    const ids = Array.from(this.keyIndex.values());
+    for (const id of ids) {
+      this.removeEntry(id, "clear");
+    }
+  }
+  size() {
+    return this.keyIndex.size;
+  }
+  stats() {
+    return {
+      size: this.size()
+    };
+  }
+  close() {
+    if (this.intervalId !== void 0) {
+      clearInterval(this.intervalId);
+      this.intervalId = void 0;
+    }
+  }
+  /**
+   * Advance the timer wheel and process expirations.
+   * Called automatically in active mode (ttlAutopurge=false).
+   */
+  advanceWheel() {
+    this.wheel.advanceToNow((id) => {
+      this.onExpireEntry(id, "ttl");
+    });
+  }
+  removeEntry(id, reason) {
+    const key = this.store.keyRef[id];
+    const value = this.store.valRef[id];
+    if (key !== void 0) {
+      this.keyIndex.delete(key);
+    }
+    this.wheel.unlink(id);
+    this.lru.unlink(id);
+    this.store.freeId(id);
+    if (this.onDispose && key !== void 0 && value !== void 0) {
+      this.onDispose(key, value, reason);
+    }
+  }
+  onExpireEntry(id, reason) {
+    this.removeEntry(id, reason);
+  }
+  evictLru() {
+    const tail = this.lru.getTail();
+    if (tail === NIL) {
+      return false;
+    }
+    this.removeEntry(tail, "lru");
+    return true;
+  }
+  startCleanupInterval() {
+    this.intervalId = setInterval(() => {
+      this.advanceWheel();
+    }, this.tickMs);
+    this.intervalId.unref();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TtlWheelCache
+});