test(utils): add tests for misc, MemCache, and DiskCache

Adds 54 new specs covering the three core utility modules:

- misc: env(), seconds(), ms(), HTTPError (19 specs)
- MemCache: set/get, TTL expiry, has, getOr, delete, clear,
  expires, invalidate (24 specs)
- DiskCache: set/get round-trip, TTL expiry, persistence across
  instances, invalidate, path traversal prevention (11 specs)

Author: marcoscaceres

tests/utils/disk-cache.test.js

@@ -0,0 +1,113 @@
+import { DiskCache } from "../../build/utils/disk-cache.js";
+import { mkdtemp, rm, readdir } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+
+describe("utils/DiskCache", () => {
+  let tempDir;
+  let originalDataDir;
+
+  beforeEach(async () => {
+    originalDataDir = process.env.DATA_DIR;
+    tempDir = await mkdtemp(join(tmpdir(), "disk-cache-test-"));
+    process.env.DATA_DIR = tempDir;
+  });
+
+  afterEach(async () => {
+    if (originalDataDir !== undefined) {
+      process.env.DATA_DIR = originalDataDir;
+    } else {
+      delete process.env.DATA_DIR;
+    }
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("round-trips set and get", async () => {
+    const cache = new DiskCache({ ttl: 60_000, path: "test-cache" });
+    await cache.set("greeting", "hello");
+    const result = await cache.get("greeting");
+    expect(result).toBe("hello");
+  });
+
+  it("returns undefined for missing key", async () => {
+    const cache = new DiskCache({ ttl: 60_000, path: "test-cache" });
+    const result = await cache.get("nonexistent");
+    expect(result).toBeUndefined();
+  });
+
+  it("stores complex objects", async () => {
+    const cache = new DiskCache({ ttl: 60_000, path: "test-cache" });
+    const data = { name: "test", items: [1, 2, 3], nested: { a: true } };
+    await cache.set("complex", data);
+    const result = await cache.get("complex");
+    expect(result).toEqual(data);
+  });
+
+  it("overwrites existing values", async () => {
+    const cache = new DiskCache({ ttl: 60_000, path: "test-cache" });
+    await cache.set("key", "old");
+    await cache.set("key", "new");
+    expect(await cache.get("key")).toBe("new");
+  });
+
+  it("persists to disk and reads back in a fresh instance", async () => {
+    const opts = { ttl: 60_000, path: "test-cache" };
+    const cache1 = new DiskCache(opts);
+    await cache1.set("persist", "data");
+
+    // A new instance should read from disk
+    const cache2 = new DiskCache(opts);
+    expect(await cache2.get("persist")).toBe("data");
+  });
+
+  describe("TTL expiry", () => {
+    it("returns undefined for expired entries", async () => {
+      // Use a very short TTL
+      const cache = new DiskCache({ ttl: 1, path: "test-cache" });
+      await cache.set("key", "value");
+
+      // Wait briefly to ensure TTL expires
+      await new Promise(resolve => setTimeout(resolve, 10));
+      expect(await cache.get("key")).toBeUndefined();
+    });
+
+    it("returns stale value when allowStale is true", async () => {
+      const cache = new DiskCache({ ttl: 1, path: "test-cache" });
+      await cache.set("key", "value");
+
+      await new Promise(resolve => setTimeout(resolve, 10));
+      expect(await cache.get("key", true)).toBe("value");
+    });
+  });
+
+  describe("invalidate()", () => {
+    it("removes expired entries from memory and disk", async () => {
+      const cache = new DiskCache({ ttl: 1, path: "test-cache" });
+      await cache.set("a", 1);
+      await cache.set("b", 2);
+
+      await new Promise(resolve => setTimeout(resolve, 10));
+      await cache.invalidate();
+
+      expect(await cache.get("a", true)).toBeUndefined();
+      expect(await cache.get("b", true)).toBeUndefined();
+    });
+  });
+
+  describe("path traversal prevention", () => {
+    it("rejects keys with path traversal (..)", async () => {
+      const cache = new DiskCache({ ttl: 60_000, path: "test-cache" });
+      await expectAsync(cache.set("foo/../evil", "data")).toBeRejected();
+    });
+
+    it("rejects keys with double slashes", async () => {
+      const cache = new DiskCache({ ttl: 60_000, path: "test-cache" });
+      await expectAsync(cache.set("foo//bar", "data")).toBeRejected();
+    });
+
+    it("rejects keys with dot segments", async () => {
+      const cache = new DiskCache({ ttl: 60_000, path: "test-cache" });
+      await expectAsync(cache.set("foo/./bar", "data")).toBeRejected();
+    });
+  });
+});

tests/utils/mem-cache.test.js

@@ -0,0 +1,194 @@
+import { MemCache } from "../../build/utils/mem-cache.js";
+
+describe("utils/MemCache", () => {
+  describe("set() and get()", () => {
+    it("stores and retrieves a value", () => {
+      const cache = new MemCache(10_000);
+      cache.set("key1", "value1");
+      expect(cache.get("key1")).toBe("value1");
+    });
+
+    it("returns undefined for missing key", () => {
+      const cache = new MemCache(10_000);
+      expect(cache.get("nonexistent")).toBeUndefined();
+    });
+
+    it("overwrites existing value", () => {
+      const cache = new MemCache(10_000);
+      cache.set("key", "old");
+      cache.set("key", "new");
+      expect(cache.get("key")).toBe("new");
+    });
+
+    it("works with non-string values", () => {
+      const cache = new MemCache(10_000);
+      cache.set("obj", { a: 1 });
+      expect(cache.get("obj")).toEqual({ a: 1 });
+      cache.set("arr", [1, 2, 3]);
+      expect(cache.get("arr")).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe("TTL expiry", () => {
+    it("returns undefined for expired entries", () => {
+      const cache = new MemCache(1000); // 1 second TTL
+      // Set entry with a time 2 seconds in the past
+      cache.set("old", "stale", Date.now() - 2000);
+      expect(cache.get("old")).toBeUndefined();
+    });
+
+    it("returns value for non-expired entries", () => {
+      const cache = new MemCache(10_000);
+      cache.set("fresh", "value", Date.now());
+      expect(cache.get("fresh")).toBe("value");
+    });
+
+    it("returns stale value when allowStale is true", () => {
+      const cache = new MemCache(1000);
+      cache.set("old", "stale", Date.now() - 2000);
+      expect(cache.get("old", true)).toBe("stale");
+    });
+
+    it("deletes expired entry from cache on non-stale get", () => {
+      const cache = new MemCache(1000);
+      cache.set("old", "stale", Date.now() - 2000);
+      // First get removes it
+      expect(cache.get("old")).toBeUndefined();
+      // Even stale get now returns undefined because it was deleted
+      expect(cache.get("old", true)).toBeUndefined();
+    });
+  });
+
+  describe("has()", () => {
+    it("returns true for existing non-expired key", () => {
+      const cache = new MemCache(10_000);
+      cache.set("key", "val");
+      expect(cache.has("key")).toBeTrue();
+    });
+
+    it("returns false for missing key", () => {
+      const cache = new MemCache(10_000);
+      expect(cache.has("missing")).toBeFalse();
+    });
+
+    it("returns false for expired key without stale option", () => {
+      const cache = new MemCache(1000);
+      cache.set("old", "val", Date.now() - 2000);
+      expect(cache.has("old")).toBeFalse();
+    });
+
+    it("returns true for expired key with stale option", () => {
+      const cache = new MemCache(1000);
+      cache.set("old", "val", Date.now() - 2000);
+      expect(cache.has("old", true)).toBeTrue();
+    });
+  });
+
+  describe("getOr()", () => {
+    it("returns cached value if present", () => {
+      const cache = new MemCache(10_000);
+      cache.set("key", "cached");
+      const result = cache.getOr("key", () => "default");
+      expect(result).toBe("cached");
+    });
+
+    it("calls defaultFunction and caches result for missing key", () => {
+      const cache = new MemCache(10_000);
+      let callCount = 0;
+      const factory = () => {
+        callCount++;
+        return "computed";
+      };
+      expect(cache.getOr("key", factory)).toBe("computed");
+      expect(callCount).toBe(1);
+
+      // Second call uses cached value
+      expect(cache.getOr("key", factory)).toBe("computed");
+      expect(callCount).toBe(1);
+    });
+
+    it("recomputes when entry has expired", () => {
+      const cache = new MemCache(1000);
+      cache.set("key", "old", Date.now() - 2000);
+      const result = cache.getOr("key", () => "fresh");
+      expect(result).toBe("fresh");
+    });
+  });
+
+  describe("delete()", () => {
+    it("removes an entry", () => {
+      const cache = new MemCache(10_000);
+      cache.set("key", "val");
+      expect(cache.delete("key")).toBeTrue();
+      expect(cache.get("key")).toBeUndefined();
+    });
+
+    it("returns false for nonexistent key", () => {
+      const cache = new MemCache(10_000);
+      expect(cache.delete("nonexistent")).toBeFalse();
+    });
+  });
+
+  describe("clear()", () => {
+    it("removes all entries", () => {
+      const cache = new MemCache(10_000);
+      cache.set("a", 1);
+      cache.set("b", 2);
+      cache.set("c", 3);
+      cache.clear();
+      expect(cache.get("a")).toBeUndefined();
+      expect(cache.get("b")).toBeUndefined();
+      expect(cache.get("c")).toBeUndefined();
+    });
+  });
+
+  describe("expires()", () => {
+    it("returns remaining TTL for a valid entry", () => {
+      const cache = new MemCache(10_000);
+      cache.set("key", "val", Date.now());
+      const remaining = cache.expires("key");
+      // Should be close to 10_000 but we give some tolerance
+      expect(remaining).toBeGreaterThan(9_900);
+      expect(remaining).toBeLessThanOrEqual(10_000);
+    });
+
+    it("returns 0 for missing key", () => {
+      const cache = new MemCache(10_000);
+      expect(cache.expires("nonexistent")).toBe(0);
+    });
+
+    it("returns 0 for expired key", () => {
+      const cache = new MemCache(1000);
+      cache.set("old", "val", Date.now() - 2000);
+      expect(cache.expires("old")).toBe(0);
+    });
+  });
+
+  describe("invalidate()", () => {
+    it("removes expired entries and returns their keys", () => {
+      const cache = new MemCache(1000);
+      cache.set("old1", "v1", Date.now() - 2000);
+      cache.set("old2", "v2", Date.now() - 3000);
+      cache.set("fresh", "v3", Date.now());
+
+      const invalidated = cache.invalidate();
+      expect(invalidated).toContain("old1");
+      expect(invalidated).toContain("old2");
+      expect(invalidated).not.toContain("fresh");
+    });
+
+    it("returns empty array when nothing is expired", () => {
+      const cache = new MemCache(10_000);
+      cache.set("a", 1);
+      cache.set("b", 2);
+      expect(cache.invalidate()).toEqual([]);
+    });
+
+    it("makes expired entries inaccessible", () => {
+      const cache = new MemCache(1000);
+      cache.set("old", "val", Date.now() - 2000);
+      cache.invalidate();
+      expect(cache.get("old", true)).toBeUndefined();
+    });
+  });
+});