@checkstack/cache-utils 0.2.23 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @checkstack/cache-utils
 
+## 0.3.0
+
+### Minor Changes
+
+- bd41130: feat(cache-utils): add `CachedScope.wrapManyBatched` (epoch-guarded batched read-through)
+
+  `wrapManyBatched(ids, { keyFor, load })` serves cache hits and loads the MISSES
+  in ONE batched call (unlike `wrapMany`, which runs a loader per id), returning
+  values in input order. Crucially it carries the SAME per-key epoch guard as
+  `wrap`: a value is only written back if its key was not invalidated during the
+  load, so a concurrent mutation that invalidates a key mid-load truly wins the
+  race and cannot be clobbered by an in-flight loader's stale write. It also fails
+  open (a `provider.get` error is treated as a miss). This is the primitive the
+  auth `role -> access-rule ids` cache uses to keep its batched miss-load without
+  giving up the staleness guarantee the single-key `wrap` path already had.
+
+## 0.2.24
+
+### Patch Changes
+
+- @checkstack/cache-api@0.3.19
+
 ## 0.2.23
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/cache-utils",
-  "version": "0.2.23",
+  "version": "0.3.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "tooling"
@@ -8,11 +8,11 @@
   "type": "module",
   "main": "src/index.ts",
   "dependencies": {
-    "@checkstack/cache-api": "0.3.18"
+    "@checkstack/cache-api": "0.3.19"
   },
   "devDependencies": {
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.7.2",
+    "@checkstack/scripts": "0.7.3",
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0"
   },

package/src/cached-scope.test.ts

@@ -258,6 +258,96 @@ describe("createCachedScope", () => {
     });
   });
 
+  describe("wrapManyBatched", () => {
+    it("serves hits and loads misses in ONE batched call, in input order", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "hc",
+      });
+
+      // Warm 'a' only.
+      await provider.set("hc:e:a", "cached:a");
+
+      const load = mock(async (miss: string[]) => miss.map((id) => `db:${id}`));
+      const result = await scope.wrapManyBatched(["a", "b", "c"], {
+        keyFor: (id) => `e:${id}`,
+        load,
+      });
+
+      expect(result).toEqual(["cached:a", "db:b", "db:c"]);
+      // ONE batched load call, with exactly the miss ids (order preserved).
+      expect(load).toHaveBeenCalledTimes(1);
+      expect(load.mock.calls[0]![0]).toEqual(["b", "c"]);
+      // Misses were written back.
+      expect(await provider.get<string>("hc:e:b")).toBe("db:b");
+      expect(await provider.get<string>("hc:e:c")).toBe("db:c");
+    });
+
+    it("returns [] for an empty id list without loading", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "hc",
+      });
+      const load = mock(async () => []);
+      const result = await scope.wrapManyBatched<string, string>([], {
+        keyFor: (id) => id,
+        load,
+      });
+      expect(result).toEqual([]);
+      expect(load).not.toHaveBeenCalled();
+    });
+
+    it("fails open: a provider.get error treats the id as a miss", async () => {
+      const provider = createMemoryProvider();
+      provider.get = (async () => {
+        throw new Error("cache down");
+      }) as CacheProvider["get"];
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "hc",
+      });
+
+      const load = mock(async (miss: string[]) => miss.map((id) => `db:${id}`));
+      const result = await scope.wrapManyBatched(["a", "b"], {
+        keyFor: (id) => `e:${id}`,
+        load,
+      });
+      expect(result).toEqual(["db:a", "db:b"]); // all loaded from DB
+      expect(load.mock.calls[0]![0]).toEqual(["a", "b"]);
+    });
+
+    it("epoch check: an invalidate during the batched load blocks the stale write-back", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "p",
+      });
+
+      const gate = deferred<string[]>();
+      const load = mock(() => gate.promise);
+
+      const reading = scope.wrapManyBatched(["k1", "k2"], {
+        keyFor: (id) => id,
+        load,
+      });
+      // Wait until the batched load has actually started (its epochs are now
+      // captured), THEN invalidate ONE of the two keys mid-load.
+      while (load.mock.calls.length === 0) await Promise.resolve();
+      await scope.invalidate("k1");
+      gate.resolve(["stale:k1", "fresh:k2"]);
+      const result = await reading;
+
+      // Caller still receives the loaded values (its read began pre-mutation)...
+      expect(result).toEqual(["stale:k1", "fresh:k2"]);
+      // ...but the invalidated key must NOT be repopulated with the stale value,
+      // while the untouched key IS written back.
+      expect(await provider.has("p:k1")).toBe(false);
+      expect(await provider.get<string>("p:k2")).toBe("fresh:k2");
+    });
+  });
+
   describe("invalidate / invalidatePrefix", () => {
     it("invalidate removes a single key so the next read re-loads", async () => {
       const provider = createMemoryProvider();

package/src/cached-scope.ts

@@ -48,6 +48,30 @@ export interface CachedScope {
     },
   ): Promise<T[]>;
 
+  /**
+   * Per-entity caching for bulk reads whose MISSES are loaded in ONE batched
+   * call (not one loader per id like {@link wrapMany}). For each id, returns the
+   * cached value if present; the misses are collected and passed to
+   * {@link load} as a single array, and {@link load} returns their values in the
+   * SAME ORDER as the miss array.
+   *
+   * Unlike a hand-rolled `provider.get` + batched query + `provider.set`, this
+   * carries the SAME epoch guard as {@link wrap}: the epoch of each miss key is
+   * captured before {@link load} runs, and a value is only written back if the
+   * key was not invalidated during the load. So a mutation that invalidates a
+   * key mid-load truly wins the race and cannot be clobbered by an in-flight
+   * loader's stale write - matching {@link wrap}'s guarantee for a batched read.
+   */
+  wrapManyBatched<Id, T>(
+    ids: readonly Id[],
+    options: {
+      keyFor: (id: Id) => string;
+      /** Load the miss ids in one call, returning values in the same order. */
+      load: (missIds: Id[]) => Promise<T[]>;
+      ttlMs?: number;
+    },
+  ): Promise<T[]>;
+
   /**
    * Invalidate exactly one key. Safe to call from mutation paths.
    * Prefer this over prefix invalidation when you know the affected entity.
@@ -180,6 +204,61 @@ export function createCachedScope({
     );
   }
 
+  async function wrapManyBatched<Id, T>(
+    ids: readonly Id[],
+    options: {
+      keyFor: (id: Id) => string;
+      load: (missIds: Id[]) => Promise<T[]>;
+      ttlMs?: number;
+    },
+  ): Promise<T[]> {
+    if (ids.length === 0) {
+      return [];
+    }
+    const ttlMs = options.ttlMs ?? defaultTtlMs;
+    const keys = ids.map((id) => options.keyFor(id));
+
+    // Read every key in parallel; a get failure is treated as a MISS (fail open).
+    const cached = await Promise.all(
+      keys.map(async (key) => {
+        try {
+          return await provider.get<T>(key);
+        } catch (error) {
+          reportError("get", error);
+          return; // treat as a miss (fail open)
+        }
+      }),
+    );
+
+    const result = Array.from<T>({ length: ids.length });
+    const missIndices: number[] = [];
+    for (const [i, value] of cached.entries()) {
+      if (value === undefined) missIndices.push(i);
+      else result[i] = value;
+    }
+
+    if (missIndices.length > 0) {
+      // Capture each miss key's epoch BEFORE loading, so a concurrent
+      // invalidate during the load prevents its stale write (same guard as wrap).
+      const startEpochs = missIndices.map((i) => epochs.get(keys[i]!) ?? 0);
+      const loaded = await options.load(missIndices.map((i) => ids[i]!));
+      await Promise.all(
+        missIndices.map(async (i, j) => {
+          const value = loaded[j]!;
+          result[i] = value;
+          if ((epochs.get(keys[i]!) ?? 0) === startEpochs[j]) {
+            try {
+              await provider.set(keys[i]!, value, ttlMs);
+            } catch (error) {
+              reportError("set", error);
+            }
+          }
+        }),
+      );
+    }
+    return result;
+  }
+
   async function invalidate(key: string): Promise<void> {
     bumpEpoch(key);
     inflight.delete(key);
@@ -209,5 +288,12 @@ export function createCachedScope({
     }
   }
 
-  return { wrap, wrapMany, invalidate, invalidatePrefix, provider };
+  return {
+    wrap,
+    wrapMany,
+    wrapManyBatched,
+    invalidate,
+    invalidatePrefix,
+    provider,
+  };
 }