@warlock.js/cache 5.19.1 → 5.21.0

package/skills/test-cache-code/SKILL.md

@@ -1,219 +1,219 @@
----
-name: test-cache-code
-description: "Testing code that touches cache in @warlock.js/cache; use when you need to test cache code."
----
-
-# Testing code that touches cache
-
-Three good strategies — pick based on what you're testing.
-
-## Strategy 1 — `MockCacheDriver` for behavioral assertions (preferred)
-
-When you want to assert "did my service actually invalidate the cache after the update?" or "was `set` called with the right TTL?", reach for `MockCacheDriver`. It implements the full driver contract on a `Map` and adds three introspection helpers:
-
-- `wasCalled(operation, key?)` — was a given op invoked? Optional key matched post-`parseKey`.
-- `getStored(key)` — raw stored value, bypassing TTL handling and clone protection.
-- `reset()` — wipe storage, tag index, and call log in one call.
-- `callLog: CacheCall[]` — ordered record of every op (operation, parsed key, raw args, timestamp).
-
-```ts
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { cache, MockCacheDriver } from "@warlock.js/cache";
-
-describe("UserService.update", () => {
-  let driver: MockCacheDriver;
-
-  beforeEach(async () => {
-    cache.setCacheConfigurations({
-      default: "mock",
-      logging: false,
-      drivers: { mock: MockCacheDriver },
-      options: { mock: {} },
-    });
-    await cache.init();
-
-    driver = cache.currentDriver as MockCacheDriver;
-  });
-
-  afterEach(async () => {
-    driver.reset();
-    await cache.disconnect();
-  });
-
-  it("invalidates the user cache after update", async () => {
-    await new UserService().update(42, { name: "Jane" });
-
-    expect(driver.wasCalled("remove", "users.42")).toBe(true);
-  });
-
-  it("caches with the right TTL on read-through", async () => {
-    await new UserService().getProfile(1);
-
-    const setCall = driver.callLog.find((call) => call.operation === "set");
-    expect(setCall?.args[1]).toBe("1h");
-  });
-});
-```
-
-`wasCalled` normalizes object keys, so `wasCalled("set", { id: 1 })` and `wasCalled("set", "id.1")` match the same call.
-
-## Strategy 2 — `MemoryCacheDriver` for full-stack integration tests
-
-When you want the real read/write semantics (eviction, TTL expiry, similarity scoring) without the introspection ceremony, `MemoryCacheDriver` is the right pick. Same setup pattern as the mock — swap `MockCacheDriver` for `MemoryCacheDriver`.
-
-`MockCacheDriver` does NOT implement `similar()` — vector writes are recorded into the call log but nearest-neighbor scoring is not available. Tests that call `cache.similar(...)` should use the memory driver.
-
-## Strategy 3 — `NullCacheDriver` when you need cache *off*
-
-Use `NullCacheDriver` to disable caching entirely for code paths that should still work without a cache (graceful-degradation tests):
-
-```ts
-cache.setCacheConfigurations({
-  default: "null",
-  drivers: { null: NullCacheDriver },
-  options: { null: {} },
-});
-await cache.init();
-
-// All cache ops no-op; get() always returns null; set() silently discards.
-```
-
-## Mocking Redis (for driver-level tests, not app code)
-
-For tests that specifically exercise `RedisCacheDriver`, use `vi.mock("redis")` with an in-memory fake. Example (condensed from `redis-cache-driver.spec.ts`):
-
-```ts
-import { vi } from "vitest";
-
-class FakeRedisClient {
-  public store = new Map<string, string>();
-  private expires = new Map<string, number>();
-  public on() { return this; }
-  public async connect() {}
-  public async quit() {}
-  public async set(key: string, value: string, opts?: { EX?: number; NX?: boolean; XX?: boolean }) {
-    if (opts?.NX && this.store.has(key)) return null;
-    if (opts?.XX && !this.store.has(key)) return null;
-    this.store.set(key, value);
-    if (opts?.EX) this.expires.set(key, Date.now() + opts.EX * 1000);
-    return "OK";
-  }
-  public async get(key: string) {
-    const ttl = this.expires.get(key);
-    if (ttl && ttl < Date.now()) {
-      this.store.delete(key);
-      return null;
-    }
-    return this.store.get(key) ?? null;
-  }
-  public async del(keys: string | string[]) {
-    const arr = Array.isArray(keys) ? keys : [keys];
-    let count = 0;
-    for (const k of arr) if (this.store.delete(k)) count++;
-    return count;
-  }
-  public async keys(pattern: string) {
-    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
-    return [...this.store.keys()].filter((k) => regex.test(k));
-  }
-  public async flushAll() { this.store.clear(); this.expires.clear(); }
-  public async incrBy(key: string, n: number) {
-    const next = Number(this.store.get(key) ?? 0) + n;
-    this.store.set(key, String(next));
-    return next;
-  }
-  public async decrBy(key: string, n: number) { return this.incrBy(key, -n); }
-}
-
-const fakeClient = new FakeRedisClient();
-vi.mock("redis", () => ({ createClient: vi.fn(() => fakeClient) }));
-```
-
-**One-time gotcha:** `RedisCacheDriver` kicks off an async `loadRedis()` at module import that resolves its internal "redis is available" flag. Before running any test that calls `connect()`, wait a short tick after the first dynamic import so the flag flips. The in-tree spec uses:
-
-```ts
-async function importDriver() {
-  const mod = await import("./redis-cache-driver");
-  await new Promise((resolve) => setTimeout(resolve, 250));
-  return mod.RedisCacheDriver;
-}
-```
-
-## Silencing cache logs in tests
-
-The in-package vitest config runs `silent: true`, but if you're outside the package, explicitly disable logging:
-
-```ts
-cache.setCacheConfigurations({
-  default: "memory",
-  logging: false,             // <-- here
-  drivers: { memory: MemoryCacheDriver },
-  options: { memory: {} },
-});
-```
-
-Or per-driver: `driver.setLoggingState(false)`.
-
-## Spying on events
-
-Every driver emits `hit`, `miss`, `set`, `removed`, `flushed`, `expired`. Attach listeners to assert cache behavior without inspecting internal state:
-
-```ts
-const hits = vi.fn();
-cache.on("hit", hits);
-
-await service.getProfile("1");
-await service.getProfile("1");
-
-expect(hits).toHaveBeenCalledTimes(1);   // second call was a hit
-```
-
-Listeners registered via `cache.on(...)` automatically attach to any driver loaded later, so order of `on()` vs `init()` doesn't matter.
-
-## Tests for `update` / `merge` concurrency
-
-The chain-serialization guarantee is worth testing when your code fans out concurrent updates:
-
-```ts
-await cache.set("counter", 0);
-
-await Promise.all(
-  Array.from({ length: 10 }, () =>
-    cache.update<number>("counter", (c) => (c ?? 0) + 1),
-  ),
-);
-
-await expect(cache.get("counter")).resolves.toBe(10);
-```
-
-Runs in-process only — for cross-process safety see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
-
-## Testing similarity code paths
-
-`MemoryCacheDriver` runs `similar()` brute-force in-process — perfect for tests of code that calls `cache.similar(...)`. Use stable, hand-written vectors (don't call a real embedder in tests):
-
-```ts
-beforeEach(async () => {
-  cache.setCacheConfigurations({
-    default: "memory",
-    logging: false,
-    drivers: { memory: MemoryCacheDriver },
-    options: { memory: {} },
-  });
-  await cache.init();
-});
-
-it("returns the most similar doc above threshold", async () => {
-  await cache.set("a", { text: "alpha" }, { vector: [1, 0, 0] });
-  await cache.set("b", { text: "beta" },  { vector: [0, 1, 0] });
-
-  const hits = await cache.similar([1, 0, 0], { topK: 1, threshold: 0.5 });
-
-  expect(hits).toHaveLength(1);
-  expect(hits[0].key).toBe("a");
-});
-```
-
-## Testing the `pg` driver without a real Postgres
-
-The `pg` driver accepts any object satisfying `PgClientLike` (`{ query(text, values) }`). For unit tests, hand-roll a minimal Map-backed fake — see `src/drivers/pg-cache-driver.spec.ts` for a 60-line `FakePool` that recognizes the exact SQL shapes the driver issues. For integration coverage, gate a real-PG suite on a `POSTGRES_URL` env var and skip cleanly when unset.
+---
+name: test-cache-code
+description: 'Test code that touches cache — MockCacheDriver (behavioral assertions with wasCalled / callLog), MemoryCacheDriver (full-stack), NullCacheDriver (graceful-degradation). Triggers: `MockCacheDriver`, `MemoryCacheDriver`, `NullCacheDriver`, `wasCalled`, `callLog`, `getStored`, `reset`, `cache.on`; "assert cache was invalidated", "test code that uses cache.set", "mock cache in vitest", "test similarity without a real embedder", "stub the pg cache driver"; typical import `import { cache, MockCacheDriver, MemoryCacheDriver } from "@warlock.js/cache"`. Skip: real driver picks — `@warlock.js/cache/pick-cache-driver/SKILL.md`; competing libs `jest-mock`, `sinon`, `redis-mock`; native `vi.fn`.'
+---
+
+# Testing code that touches cache
+
+Three good strategies — pick based on what you're testing.
+
+## Strategy 1 — `MockCacheDriver` for behavioral assertions (preferred)
+
+When you want to assert "did my service actually invalidate the cache after the update?" or "was `set` called with the right TTL?", reach for `MockCacheDriver`. It implements the full driver contract on a `Map` and adds three introspection helpers:
+
+- `wasCalled(operation, key?)` — was a given op invoked? Optional key matched post-`parseKey`.
+- `getStored(key)` — raw stored value, bypassing TTL handling and clone protection.
+- `reset()` — wipe storage, tag index, and call log in one call.
+- `callLog: CacheCall[]` — ordered record of every op (operation, parsed key, raw args, timestamp).
+
+```ts
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { cache, MockCacheDriver } from "@warlock.js/cache";
+
+describe("UserService.update", () => {
+  let driver: MockCacheDriver;
+
+  beforeEach(async () => {
+    cache.setCacheConfigurations({
+      default: "mock",
+      logging: false,
+      drivers: { mock: MockCacheDriver },
+      options: { mock: {} },
+    });
+    await cache.init();
+
+    driver = cache.currentDriver as MockCacheDriver;
+  });
+
+  afterEach(async () => {
+    driver.reset();
+    await cache.disconnect();
+  });
+
+  it("invalidates the user cache after update", async () => {
+    await new UserService().update(42, { name: "Jane" });
+
+    expect(driver.wasCalled("remove", "users.42")).toBe(true);
+  });
+
+  it("caches with the right TTL on read-through", async () => {
+    await new UserService().getProfile(1);
+
+    const setCall = driver.callLog.find((call) => call.operation === "set");
+    expect(setCall?.args[1]).toBe("1h");
+  });
+});
+```
+
+`wasCalled` normalizes object keys, so `wasCalled("set", { id: 1 })` and `wasCalled("set", "id.1")` match the same call.
+
+## Strategy 2 — `MemoryCacheDriver` for full-stack integration tests
+
+When you want the real read/write semantics (eviction, TTL expiry, similarity scoring) without the introspection ceremony, `MemoryCacheDriver` is the right pick. Same setup pattern as the mock — swap `MockCacheDriver` for `MemoryCacheDriver`.
+
+`MockCacheDriver` does NOT implement `similar()` — vector writes are recorded into the call log but nearest-neighbor scoring is not available. Tests that call `cache.similar(...)` should use the memory driver.
+
+## Strategy 3 — `NullCacheDriver` when you need cache *off*
+
+Use `NullCacheDriver` to disable caching entirely for code paths that should still work without a cache (graceful-degradation tests):
+
+```ts
+cache.setCacheConfigurations({
+  default: "null",
+  drivers: { null: NullCacheDriver },
+  options: { null: {} },
+});
+await cache.init();
+
+// All cache ops no-op; get() always returns null; set() silently discards.
+```
+
+## Mocking Redis (for driver-level tests, not app code)
+
+For tests that specifically exercise `RedisCacheDriver`, use `vi.mock("redis")` with an in-memory fake. Example (condensed from `redis-cache-driver.spec.ts`):
+
+```ts
+import { vi } from "vitest";
+
+class FakeRedisClient {
+  public store = new Map<string, string>();
+  private expires = new Map<string, number>();
+  public on() { return this; }
+  public async connect() {}
+  public async quit() {}
+  public async set(key: string, value: string, opts?: { EX?: number; NX?: boolean; XX?: boolean }) {
+    if (opts?.NX && this.store.has(key)) return null;
+    if (opts?.XX && !this.store.has(key)) return null;
+    this.store.set(key, value);
+    if (opts?.EX) this.expires.set(key, Date.now() + opts.EX * 1000);
+    return "OK";
+  }
+  public async get(key: string) {
+    const ttl = this.expires.get(key);
+    if (ttl && ttl < Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return this.store.get(key) ?? null;
+  }
+  public async del(keys: string | string[]) {
+    const arr = Array.isArray(keys) ? keys : [keys];
+    let count = 0;
+    for (const k of arr) if (this.store.delete(k)) count++;
+    return count;
+  }
+  public async keys(pattern: string) {
+    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+    return [...this.store.keys()].filter((k) => regex.test(k));
+  }
+  public async flushAll() { this.store.clear(); this.expires.clear(); }
+  public async incrBy(key: string, n: number) {
+    const next = Number(this.store.get(key) ?? 0) + n;
+    this.store.set(key, String(next));
+    return next;
+  }
+  public async decrBy(key: string, n: number) { return this.incrBy(key, -n); }
+}
+
+const fakeClient = new FakeRedisClient();
+vi.mock("redis", () => ({ createClient: vi.fn(() => fakeClient) }));
+```
+
+**One-time gotcha:** `RedisCacheDriver` kicks off an async `loadRedis()` at module import that resolves its internal "redis is available" flag. Before running any test that calls `connect()`, wait a short tick after the first dynamic import so the flag flips. The in-tree spec uses:
+
+```ts
+async function importDriver() {
+  const mod = await import("./redis-cache-driver");
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  return mod.RedisCacheDriver;
+}
+```
+
+## Silencing cache logs in tests
+
+The in-package vitest config runs `silent: true`, but if you're outside the package, explicitly disable logging:
+
+```ts
+cache.setCacheConfigurations({
+  default: "memory",
+  logging: false,             // <-- here
+  drivers: { memory: MemoryCacheDriver },
+  options: { memory: {} },
+});
+```
+
+Or per-driver: `driver.setLoggingState(false)`.
+
+## Spying on events
+
+Every driver emits `hit`, `miss`, `set`, `removed`, `flushed`, `expired`. Attach listeners to assert cache behavior without inspecting internal state:
+
+```ts
+const hits = vi.fn();
+cache.on("hit", hits);
+
+await service.getProfile("1");
+await service.getProfile("1");
+
+expect(hits).toHaveBeenCalledTimes(1);   // second call was a hit
+```
+
+Listeners registered via `cache.on(...)` automatically attach to any driver loaded later, so order of `on()` vs `init()` doesn't matter.
+
+## Tests for `update` / `merge` concurrency
+
+The chain-serialization guarantee is worth testing when your code fans out concurrent updates:
+
+```ts
+await cache.set("counter", 0);
+
+await Promise.all(
+  Array.from({ length: 10 }, () =>
+    cache.update<number>("counter", (c) => (c ?? 0) + 1),
+  ),
+);
+
+await expect(cache.get("counter")).resolves.toBe(10);
+```
+
+Runs in-process only — for cross-process safety see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
+
+## Testing similarity code paths
+
+`MemoryCacheDriver` runs `similar()` brute-force in-process — perfect for tests of code that calls `cache.similar(...)`. Use stable, hand-written vectors (don't call a real embedder in tests):
+
+```ts
+beforeEach(async () => {
+  cache.setCacheConfigurations({
+    default: "memory",
+    logging: false,
+    drivers: { memory: MemoryCacheDriver },
+    options: { memory: {} },
+  });
+  await cache.init();
+});
+
+it("returns the most similar doc above threshold", async () => {
+  await cache.set("a", { text: "alpha" }, { vector: [1, 0, 0] });
+  await cache.set("b", { text: "beta" },  { vector: [0, 1, 0] });
+
+  const hits = await cache.similar([1, 0, 0], { topK: 1, threshold: 0.5 });
+
+  expect(hits).toHaveLength(1);
+  expect(hits[0].key).toBe("a");
+});
+```
+
+## Testing the `pg` driver without a real Postgres
+
+The `pg` driver accepts any object satisfying `PgClientLike` (`{ query(text, values) }`). For unit tests, hand-roll a minimal Map-backed fake — see `src/drivers/pg-cache-driver.spec.ts` for a 60-line `FakePool` that recognizes the exact SQL shapes the driver issues. For integration coverage, gate a real-PG suite on a `POSTGRES_URL` env var and skip cleanly when unset.

package/skills/use-cache-atomic/SKILL.md

@@ -1,67 +1,59 @@
----
-name: use-cache-atomic
-description: "Atomic counters — cache.increment / cache.decrement in @warlock.js/cache; use when you need to use cache atomic."
----
-
-# Atomic counters — `cache.increment` / `cache.decrement`
-
-Numeric counters that go up and down without a read-then-write race in your own
-code. Both return the **new** value after the operation.
-
-```ts
-import { cache } from "@warlock.js/cache";
-
-const views = await cache.increment(`post.${id}.views`);     // +1 → 1, 2, 3…
-const bulk = await cache.increment(`post.${id}.views`, 10);  // +10
-const left = await cache.decrement(`stock.${sku}`, 3);       // -3
-```
-
-- A missing key is treated as `0`, so the first `increment` returns `by` (default `1`).
-- `decrement(key, n)` is exactly `increment(key, -n)`.
-- The stored value must be numeric — incrementing a string/object throws:
-  `Error: Cannot increment non-numeric value for key: <key>`.
-
+---
+name: use-cache-atomic
+description: 'Atomic counters via cache.increment(key, by=1) / cache.decrement(key, by=1) — returns the new number, throws on non-numeric values. Triggers: `cache.increment`, `cache.decrement`, "view counter", "page views", "atomic counter", "decrement stock", "rate-limit counter", "INCRBY"; typical import `import { cache } from "@warlock.js/cache"`. Skip: read-modify-write of objects — `@warlock.js/cache/use-cache-update-merge/SKILL.md`; named-lock coordination — `@warlock.js/cache/use-cache-lock/SKILL.md`; competing libs `ioredis` `INCR`, native counters in a `Map`.'
+---
+
+# Atomic counters — `cache.increment` / `cache.decrement`
+
+Numeric counters that go up and down without a read-then-write race in your own
+code. Both return the **new** value after the operation.
+
+```ts
+import { cache } from "@warlock.js/cache";
+
+const views = await cache.increment(`post.${id}.views`);     // +1 → 1, 2, 3…
+const bulk = await cache.increment(`post.${id}.views`, 10);  // +10
+const left = await cache.decrement(`stock.${sku}`, 3);       // -3
+```
+
+- A missing key is treated as `0`, so the first `increment` returns `by` (default `1`).
+- `decrement(key, n)` is exactly `increment(key, -n)`.
+- The stored value must be numeric — incrementing a string/object throws:
+  `Error: Cannot increment non-numeric value for key: <key>`.
+
 ## Atomicity is per-driver
 
-| Driver | Guarantee |
-|---|---|
-| `redis` | Native `INCRBY` / `DECRBY` — atomic **across processes/nodes** |
-| memory family / `file` / `pg` | Read-modify-write — atomic **within one process** only |
-
-For a counter that multiple instances bump concurrently (a global rate limit, a
-shared tally), use the [`redis`](@warlock.js/cache/pick-cache-driver/SKILL.md)
-driver. In-memory counters are fine for single-node work.
-
-## TTL behavior differs too
-
-This is the gotcha to remember:
-
-- **Redis** `INCRBY` **preserves** the key's existing TTL.
-- **Memory-family / pg** write the new value through `set()` with the driver's
-  **default** TTL — they do **not** carry over the previous entry's remaining TTL.
-
-So if you need a counter that expires (a fixed window), set the TTL explicitly
-when you create it and don't rely on `increment` to keep a window alive on the
-in-memory drivers. For a value that should keep its TTL across edits, reach for
-[`cache.update`](@warlock.js/cache/use-cache-update-merge/SKILL.md), which
-preserves the remaining TTL.
-
-## Common shapes
-
-```ts
-// View counter
-await cache.increment(`post.${id}.views`);
-
-// Decrement stock, guard against oversell
-const remaining = await cache.decrement(`stock.${sku}`, qty);
-if (remaining < 0) {
-  await cache.increment(`stock.${sku}`, qty); // roll back
-  throw new Error("Out of stock");
-}
-```
-
-## See also
-
-- [`@warlock.js/cache/use-cache-update-merge/SKILL.md`](@warlock.js/cache/use-cache-update-merge/SKILL.md) — atomic read-modify-write for objects, TTL-preserving
-- [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md) — coordinate multi-step critical sections
-- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — when you need cross-node atomicity
+`increment`, `decrement`, `pull` and `update` are atomic, but only some drivers are atomic **across servers**:
+
+| Driver | `increment` / `decrement` | `pull` | `update` / `merge` |
+|---|---|---|---|
+| `redis` | cross-server (`INCRBY`) | cross-server (`GETDEL`) | cross-server (Lua compare-and-set, retries) |
+| `pg` | cross-server (one upsert) | cross-server (`DELETE … RETURNING`) | cross-server (compare-and-set, retries) |
+| `memory` / `memoryExtended` / `lru` / `mock` | one process | one process | one process |
+| `file` | one process | one process | not supported (throws) |
+
+Use `redis` or `pg` for anything several servers touch (rate limits, login throttles, one-time tokens); memory is per-process. On redis/pg the `update` callback may run more than once under contention: keep it side-effect free.
+
+## TTL is kept
+
+Every driver keeps the key's **remaining TTL** across `increment`/`decrement`, so a fixed-window counter can't turn permanent. Set the TTL when you create the counter (`cache.set(key, 0, "1m")`, then `increment`). Use [`cache.update`](@warlock.js/cache/use-cache-update-merge/SKILL.md) for objects.
+
+## Common shapes
+
+```ts
+// View counter
+await cache.increment(`post.${id}.views`);
+
+// Decrement stock, guard against oversell
+const remaining = await cache.decrement(`stock.${sku}`, qty);
+if (remaining < 0) {
+  await cache.increment(`stock.${sku}`, qty); // roll back
+  throw new Error("Out of stock");
+}
+```
+
+## See also
+
+- [`@warlock.js/cache/use-cache-update-merge/SKILL.md`](@warlock.js/cache/use-cache-update-merge/SKILL.md) — atomic read-modify-write for objects, TTL-preserving
+- [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md) — coordinate multi-step critical sections
+- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — when you need cross-node atomicity