@mandujs/core 0.24.0 → 0.25.1

package/src/utils/__tests__/lru-cache.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Phase 17 — LRUCache behaviour matrix.
+ *
+ * Covers:
+ *   - Default + custom maxSize
+ *   - Eviction order (LRU semantics, not FIFO)
+ *   - `get` promotes the entry, `has` does not
+ *   - `onEvict` fires for LRU pressure / delete / clear
+ *   - Backward-compat numeric constructor
+ *   - Stats bookkeeping
+ */
+
+import { describe, test, expect } from "bun:test";
+import { LRUCache } from "../lru-cache";
+
+describe("LRUCache", () => {
+  test("default maxSize is 1000 when no options passed", () => {
+    const cache = new LRUCache<string, number>();
+    // Insert 1000 — all fit. The 1001st evicts the first.
+    for (let i = 0; i < 1000; i++) cache.set(`k${i}`, i);
+    expect(cache.size).toBe(1000);
+    expect(cache.has("k0")).toBe(true);
+
+    cache.set("k1000", 1000);
+    expect(cache.size).toBe(1000);
+    expect(cache.has("k0")).toBe(false);
+    expect(cache.has("k1000")).toBe(true);
+  });
+
+  test("numeric constructor is still supported (backward-compat)", () => {
+    const cache = new LRUCache<string, string>(3);
+    cache.set("a", "1");
+    cache.set("b", "2");
+    cache.set("c", "3");
+    cache.set("d", "4"); // evicts "a"
+    expect(cache.has("a")).toBe(false);
+    expect(cache.size).toBe(3);
+  });
+
+  test("rejects invalid maxSize", () => {
+    expect(() => new LRUCache({ maxSize: 0 })).toThrow();
+    expect(() => new LRUCache({ maxSize: -1 })).toThrow();
+    expect(() => new LRUCache({ maxSize: Number.NaN })).toThrow();
+  });
+
+  test("evicts least-recently-used entry, not FIFO", () => {
+    const cache = new LRUCache<string, number>({ maxSize: 3 });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+    // Touch "a" so it becomes most-recently-used.
+    cache.get("a");
+    // Now inserting "d" must evict "b" (oldest), not "a".
+    cache.set("d", 4);
+    expect(cache.has("a")).toBe(true);
+    expect(cache.has("b")).toBe(false);
+    expect(cache.has("c")).toBe(true);
+    expect(cache.has("d")).toBe(true);
+  });
+
+  test("has() does NOT promote (read-only probe)", () => {
+    const cache = new LRUCache<string, number>({ maxSize: 3 });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+    // `has` on "a" must not reorder. Inserting "d" should still evict "a".
+    expect(cache.has("a")).toBe(true);
+    cache.set("d", 4);
+    expect(cache.has("a")).toBe(false);
+    expect(cache.has("b")).toBe(true);
+  });
+
+  test("updating an existing key re-inserts as MRU but does not fire onEvict", () => {
+    const evicted: Array<[string, number]> = [];
+    const cache = new LRUCache<string, number>({
+      maxSize: 3,
+      onEvict: (k, v) => evicted.push([k, v]),
+    });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+    cache.set("a", 10); // update, a becomes MRU
+    expect(evicted).toHaveLength(0);
+    cache.set("d", 4); // should evict "b" (now oldest), not "a"
+    expect(evicted).toEqual([["b", 2]]);
+    expect(cache.get("a")).toBe(10);
+  });
+
+  test("onEvict fires on LRU pressure with (key, value)", () => {
+    const evicted: Array<[string, number]> = [];
+    const cache = new LRUCache<string, number>({
+      maxSize: 2,
+      onEvict: (k, v) => evicted.push([k, v]),
+    });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3); // evicts "a"
+    cache.set("d", 4); // evicts "b"
+    expect(evicted).toEqual([
+      ["a", 1],
+      ["b", 2],
+    ]);
+  });
+
+  test("onEvict fires on delete() for present keys only", () => {
+    const evicted: Array<[string, number]> = [];
+    const cache = new LRUCache<string, number>({
+      maxSize: 5,
+      onEvict: (k, v) => evicted.push([k, v]),
+    });
+    cache.set("x", 1);
+    expect(cache.delete("x")).toBe(true);
+    expect(cache.delete("x")).toBe(false); // already gone
+    expect(cache.delete("missing")).toBe(false);
+    expect(evicted).toEqual([["x", 1]]);
+  });
+
+  test("onEvict fires for every entry during clear()", () => {
+    const evicted: string[] = [];
+    const cache = new LRUCache<string, number>({
+      maxSize: 10,
+      onEvict: (k) => evicted.push(k),
+    });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+    cache.clear();
+    expect(evicted.sort()).toEqual(["a", "b", "c"]);
+    expect(cache.size).toBe(0);
+  });
+
+  test("onEvict errors are swallowed (must not corrupt state)", () => {
+    const cache = new LRUCache<string, number>({
+      maxSize: 2,
+      onEvict: () => {
+        throw new Error("boom");
+      },
+    });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    // Would throw during eviction if errors weren't caught.
+    expect(() => cache.set("c", 3)).not.toThrow();
+    expect(cache.size).toBe(2);
+    expect(cache.has("a")).toBe(false);
+  });
+
+  test("getWithStats records hits/misses; getStats reports hit rate", () => {
+    const cache = new LRUCache<string, number>({ maxSize: 10 });
+    cache.set("a", 1);
+    cache.getWithStats("a"); // hit
+    cache.getWithStats("a"); // hit
+    cache.getWithStats("b"); // miss
+    const stats = cache.getStats();
+    expect(stats.hits).toBe(2);
+    expect(stats.misses).toBe(1);
+    expect(stats.hitRate).toBeCloseTo(2 / 3);
+    expect(stats.size).toBe(1);
+    expect(stats.maxSize).toBe(10);
+    cache.resetStats();
+    expect(cache.getStats().hits).toBe(0);
+    expect(cache.getStats().misses).toBe(0);
+  });
+
+  test("entries() yields LRU → MRU order", () => {
+    const cache = new LRUCache<string, number>({ maxSize: 5 });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+    cache.get("a"); // a becomes MRU
+    const keys = [...cache.entries()].map(([k]) => k);
+    expect(keys).toEqual(["b", "c", "a"]);
+  });
+
+  test("fill-past-max proof: 1001 writes against a 1000-entry cache evict exactly the oldest", () => {
+    const cache = new LRUCache<number, number>({ maxSize: 1000 });
+    for (let i = 0; i < 1000; i++) cache.set(i, i);
+    expect(cache.size).toBe(1000);
+    expect(cache.has(0)).toBe(true);
+
+    cache.set(1000, 1000);
+    expect(cache.size).toBe(1000); // still bounded
+    expect(cache.has(0)).toBe(false); // oldest gone
+    expect(cache.has(1000)).toBe(true); // newest present
+    expect(cache.has(500)).toBe(true); // middle survives
+  });
+});

package/src/utils/lru-cache.ts

@@ -1,75 +1,172 @@
-/**
- * 간단한 LRU (Least Recently Used) 캐시 구현
- */
-export class LRUCache<K, V> {
-  private cache: Map<K, V>;
-  private readonly maxSize: number;
-  private _hits = 0;
-  private _misses = 0;
-
-  constructor(maxSize: number = 100) {
-    this.cache = new Map();
-    this.maxSize = maxSize;
-  }
-
-  get(key: K): V | undefined {
-    const value = this.cache.get(key);
-    if (value !== undefined) {
-      this.cache.delete(key);
-      this.cache.set(key, value);
-    }
-    return value;
-  }
-
-  getWithStats(key: K): V | undefined {
-    const value = this.get(key);
-    if (value !== undefined) {
-      this._hits++;
-    } else {
-      this._misses++;
-    }
-    return value;
-  }
-
-  set(key: K, value: V): void {
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    } else if (this.cache.size >= this.maxSize) {
-      const firstKey = this.cache.keys().next().value;
-      if (firstKey !== undefined) {
-        this.cache.delete(firstKey);
-      }
-    }
-    this.cache.set(key, value);
-  }
-
-  has(key: K): boolean {
-    return this.cache.has(key);
-  }
-
-  delete(key: K): boolean {
-    return this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  get size(): number {
-    return this.cache.size;
-  }
-
-  getStats(): { hits: number; misses: number; hitRate: number } {
-    const total = this._hits + this._misses;
-    return {
-      hits: this._hits,
-      misses: this._misses,
-      hitRate: total > 0 ? this._hits / total : 0,
-    };
-  }
-
-  resetStats(): void {
-    this._hits = 0;
-    this._misses = 0;
-  }
-}
+/**
+ * 간단한 LRU (Least Recently Used) 캐시 구현.
+ *
+ * Phase 17 — bounded caches for memory safety. Used by:
+ *   - `client/router.ts` patternCache (compiled route regex cache)
+ *   - `client/use-fetch.ts` fetchCache (browser data cache)
+ *   - `bundler/dev.ts` perFileTimers (debounce map)
+ *
+ * O(1) get / set on top of `Map` insertion order:
+ *   - `get` re-inserts the entry so it becomes the newest
+ *   - `set` evicts the first (oldest) key when over `maxSize`
+ *
+ * Optional `onEvict` callback fires when an entry is dropped through LRU
+ * pressure OR explicit `delete`/`clear` — lets callers release resources
+ * attached to the value (e.g. `clearTimeout(timer)` for debounce maps).
+ */
+export interface LRUCacheOptions<K, V> {
+  /** Maximum number of entries. Defaults to `1000`. */
+  maxSize?: number;
+  /**
+   * Fired when an entry leaves the cache. Called for LRU eviction,
+   * `delete(key)`, and each entry during `clear()`. Errors are swallowed
+   * so a bad callback cannot corrupt cache state.
+   */
+  onEvict?: (key: K, value: V) => void;
+}
+
+export class LRUCache<K, V> {
+  private cache: Map<K, V>;
+  private readonly maxSize: number;
+  private readonly onEvict?: (key: K, value: V) => void;
+  private _hits = 0;
+  private _misses = 0;
+
+  /**
+   * Dual constructor signature for backward compatibility with the
+   * original `new LRUCache(200)` call sites:
+   *
+   *   - `new LRUCache(maxSize)` — legacy numeric form
+   *   - `new LRUCache({ maxSize, onEvict })` — options form
+   */
+  constructor(options?: number | LRUCacheOptions<K, V>) {
+    this.cache = new Map();
+    if (typeof options === "number") {
+      this.maxSize = options;
+    } else {
+      this.maxSize = options?.maxSize ?? 1000;
+      this.onEvict = options?.onEvict;
+    }
+    if (!Number.isFinite(this.maxSize) || this.maxSize < 1) {
+      throw new Error(`LRUCache: maxSize must be >= 1 (got ${this.maxSize})`);
+    }
+  }
+
+  /**
+   * Retrieve a value AND promote it to the most-recently-used position.
+   * Returns `undefined` for misses. `has()` does NOT promote.
+   */
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // Re-insert to mark as most-recently-used.
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  /**
+   * Same as `get` but also increments hit/miss counters.
+   * Use `getStats()` to read the tallies.
+   */
+  getWithStats(key: K): V | undefined {
+    const value = this.get(key);
+    if (value !== undefined) {
+      this._hits++;
+    } else {
+      this._misses++;
+    }
+    return value;
+  }
+
+  /**
+   * Insert / update an entry. If at capacity, evicts the oldest entry
+   * and fires `onEvict` for it.
+   */
+  set(key: K, value: V): void {
+    if (this.cache.has(key)) {
+      // Update in place → delete then re-insert so the new value is
+      // positioned at the MRU end. No eviction callback here (same key).
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      // At capacity → drop the oldest.
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        const oldValue = this.cache.get(firstKey) as V;
+        this.cache.delete(firstKey);
+        this.fireEvict(firstKey, oldValue);
+      }
+    }
+    this.cache.set(key, value);
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  /**
+   * Explicit removal. Fires `onEvict` for the removed entry. Returns
+   * `true` iff the key was present.
+   */
+  delete(key: K): boolean {
+    const value = this.cache.get(key);
+    const existed = this.cache.delete(key);
+    if (existed) {
+      this.fireEvict(key, value as V);
+    }
+    return existed;
+  }
+
+  /**
+   * Drop every entry. Fires `onEvict` for each before clearing so
+   * callers can bulk-release resources (e.g. clear every timer).
+   */
+  clear(): void {
+    if (this.onEvict) {
+      // Iterate BEFORE clearing so the callback sees a valid entry.
+      for (const [k, v] of this.cache) {
+        this.fireEvict(k, v);
+      }
+    }
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Read-only iteration for introspection (metrics, debug dumps).
+   * Yields entries in LRU → MRU order.
+   */
+  *entries(): IterableIterator<[K, V]> {
+    yield* this.cache.entries();
+  }
+
+  getStats(): { hits: number; misses: number; hitRate: number; size: number; maxSize: number } {
+    const total = this._hits + this._misses;
+    return {
+      hits: this._hits,
+      misses: this._misses,
+      hitRate: total > 0 ? this._hits / total : 0,
+      size: this.cache.size,
+      maxSize: this.maxSize,
+    };
+  }
+
+  resetStats(): void {
+    this._hits = 0;
+    this._misses = 0;
+  }
+
+  private fireEvict(key: K, value: V): void {
+    if (!this.onEvict) return;
+    try {
+      this.onEvict(key, value);
+    } catch {
+      // Swallow — a bad callback must not corrupt cache state. Users
+      // who need error visibility can wrap their own callback.
+    }
+  }
+}