@warlock.js/cache 4.0.171 → 4.1.1

package/skills/handle-cache-errors/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: handle-cache-errors
+description: 'Cache error classes — CacheError base, CacheConfigurationError, CacheConnectionError, CacheDriverNotInitializedError, CacheUnsupportedError, CacheConcurrencyError. Triggers: `CacheError`, `CacheConfigurationError`, `CacheConnectionError`, `CacheDriverNotInitializedError`, `CacheUnsupportedError`, `CacheConcurrencyError`; "catch cache errors at the boundary", "degrade when update or merge throws", "what does CacheUnsupportedError mean", "fall back when redis is down"; typical import `import { CacheError, CacheConfigurationError, CacheUnsupportedError } from "@warlock.js/cache"`. Skip: choosing a supported driver — `@warlock.js/cache/pick-cache-driver/SKILL.md`; observing errors via events — `@warlock.js/cache/observe-cache/SKILL.md`; competing libs ignore — generic `Error` patterns.'
+---
+
+# Error classes
+
+All cache errors extend `CacheError` which extends `Error`. Use `instanceof` to react selectively.
+
+```ts
+import {
+  CacheError,
+  CacheConfigurationError,
+  CacheConnectionError,
+  CacheDriverNotInitializedError,
+  CacheUnsupportedError,
+  CacheConcurrencyError,
+} from "@warlock.js/cache";
+```
+
+| Class | When it's thrown | How to react |
+| --- | --- | --- |
+| `CacheError` | Abstract base — don't throw directly, match against it to catch any cache error | `catch (e) { if (e instanceof CacheError) … }` |
+| `CacheConfigurationError` | Bad TTL string, `ttl` + `expiresAt` together, `expiresAt` in the past, missing required driver option (e.g. redis without url/host, file without directory), attempting to use an unregistered driver name | Fix the config / call site. Never catch at runtime — this is a programmer error, not a user-facing one. |
+| `CacheConnectionError` | Declared for driver connection failures. Not thrown by any built-in driver today (Redis currently logs the error and emits an `"error"` event instead of throwing on failed connect). | Reserved for future use. |
+| `CacheDriverNotInitializedError` | Any data op called before `cache.init()` / `cache.use()` | Call `cache.init()` at app startup. Tests often forget this — add a `beforeEach`. |
+| `CacheUnsupportedError` | Driver doesn't implement the requested op. Today: `update` / `merge` on the file driver; `set({ vector })` and `similar()` on file / redis / pg-without-`vector`-config. | Switch driver (memory family for dev similarity, `pg` with `vector` config for production), or queue the op. |
+| `CacheConcurrencyError` | Declared for future optimistic-concurrency exhaustion on Redis `update()` | Not thrown today. Reserved for the v2.1 `WATCH`/`MULTI` implementation. |
+
+## Special case — `setNX` unsupported
+
+Calling `cache.setNX(...)` on a driver that doesn't implement it throws a plain `Error`, not a `CacheUnsupportedError`:
+
+```ts
+// Error: "setNX is not supported by the current cache driver: memory"
+```
+
+This is legacy. The v2-preferred way is `cache.set(k, v, { onConflict: "create" })` which works on every driver (Redis native, others emulated). See [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md).
+
+## Patterns
+
+### Catch-all at the boundary
+
+```ts
+try {
+  await doCachedWork();
+} catch (error) {
+  if (error instanceof CacheError) {
+    logger.warn("cache unavailable, degrading", error);
+    await doWorkWithoutCache();
+    return;
+  }
+  throw error;
+}
+```
+
+### Selective — configuration vs runtime
+
+```ts
+try {
+  await cache.set("k", v, userSuppliedOptions);
+} catch (error) {
+  if (error instanceof CacheConfigurationError) {
+    return res.status(400).json({ error: "invalid TTL options" });
+  }
+  throw error;
+}
+```
+
+### Driver-missing fallback
+
+```ts
+try {
+  await cache.merge("user:1", { lastSeen: Date.now() });
+} catch (error) {
+  if (error instanceof CacheUnsupportedError) {
+    // File driver in dev — degrade gracefully
+    const current = await cache.get("user:1");
+    await cache.set("user:1", { ...current, lastSeen: Date.now() });
+    return;
+  }
+  throw error;
+}
+```
+
+## Things the driver does NOT throw
+
+- **Missing keys** — `get()` returns `null`, never throws. Tests checking "key not in cache" should assert `resolves.toBeNull()`, not `rejects.toThrow`.
+- **Expired entries** — `get()` returns `null` and emits `"miss"` + `"expired"` events. No throw.
+- **Flush on empty** — `flush()` succeeds silently when there's nothing to flush.
+- **Concurrent writes clobbering each other** — last-write-wins by default. Use `update()` or `onConflict: "create"` if you need protection.

package/skills/observe-cache/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: observe-cache
+description: 'Cache observability — cache.metrics() for aggregate hit rate / latency p50/p95/p99 + event bus (cache.on(''hit'' / ''miss'' / ''set'' / ''removed'' / ''flushed'' / ''expired'' / ''error'', ...)). Triggers: `cache.metrics`, `cache.resetMetrics`, `cache.on`, `hit`, `miss`, `removed`, `flushed`, `error`, `hitRate`, `latencyMs`; "show cache hit rate", "page on cache errors", "is my cache being hit", "export metrics to prometheus"; typical import `import { cache } from "@warlock.js/cache"`. Skip: error classes — `@warlock.js/cache/handle-cache-errors/SKILL.md`; competing libs `prom-client`, `statsd-client`.'
+---
+
+# Cache observability — `cache.metrics()` and the event bus
+
+Two layers, different jobs.
+
+## Layer 1 — `cache.metrics()` for aggregate health
+
+Built-in collector subscribed to the manager's event bus. Returns a snapshot whenever you ask:
+
+```ts
+const m = cache.metrics();
+// {
+//   hits, misses, sets, removed, errors,
+//   hitRate,
+//   latencyMs: { p50, p95, p99, samples },
+//   byDriver: { memory: {...}, redis: {...} },
+//   startedAt,
+// }
+```
+
+**Lazy** — the collector attaches on the first `cache.metrics()` / `cache.resetMetrics()` call. Apps that never read metrics pay zero cost. Earlier events are not retroactively counted, so if you want metrics on every op including the first, call `cache.metrics()` once during startup right after `cache.init()`.
+
+**Survives `cache.use()` switches** — listens at the manager level, re-attaches to every loaded driver.
+
+**Latency** is sampled by the manager around `get` / `set` / `remove` into a circular buffer (default 1000 samples per driver). Percentiles are computed at snapshot time. Older samples age out, so percentiles reflect the recent ~1000 ops.
+
+`cache.resetMetrics()` zeroes counters + drops the buffer + bumps `startedAt`.
+
+## Layer 2 — Raw events for per-event reactions
+
+When you need to react to specific events (alerting, audit logs, debugging), subscribe to the event bus:
+
+```ts
+cache.on("error", ({ key, error }) => {
+  pagerDuty.trigger(`Cache error on ${key}`, error);
+});
+
+cache.on("miss", ({ key, driver }) => {
+  if (key.startsWith("hot.")) auditLog.miss(key, driver);
+});
+```
+
+Available events: `hit`, `miss`, `set`, `removed`, `flushed`, `expired`, `connected`, `disconnected`, `error`.
+
+Listeners attached via `cache.on(...)` survive driver switches the same way the metrics collector does.
+
+## Which one to reach for
+
+| Goal | Use |
+|---|---|
+| Show hit rate / latency in a dashboard | `cache.metrics()` |
+| Page on cache errors | `cache.on("error", ...)` |
+| Periodic export to Prometheus / StatsD | `cache.metrics()` + `setInterval` + `resetMetrics()` |
+| Audit log of every removal | `cache.on("removed", ...)` |
+| Detect a specific anti-pattern (e.g. always-miss key) | `cache.on("miss", ...)` |
+| Debug "is the cache being hit at all?" in dev | `cache.metrics()` once at the end of a flow |
+
+Both layers can coexist — events fire whether the metrics collector is attached or not.
+
+## Common shapes
+
+### Periodic export, then reset
+
+```ts
+setInterval(() => {
+  const snapshot = cache.metrics();
+  exporter.send(snapshot);
+  cache.resetMetrics();
+}, 60_000);
+```
+
+The snapshot now reflects the last minute of traffic, not the lifetime.
+
+### Boundary measurement
+
+```ts
+cache.resetMetrics();
+await runTrafficBurst();
+console.log(cache.metrics());
+```
+
+Useful for benchmarks, soak tests, "did the cache help?" before/after comparisons.
+
+### Per-driver isolation
+
+```ts
+const m = cache.metrics();
+console.log(`memory hit rate: ${m.byDriver.memory?.hitRate ?? 0}`);
+console.log(`redis p95: ${m.byDriver.redis?.latencyMs.p95 ?? 0}ms`);
+```
+
+Drivers that never fire events stay absent from `byDriver` — guard with `?.` and `?? 0`.
+
+## Things NOT to do
+
+- Don't subscribe to events to count things and ignore the built-in collector — that's exactly what it's built to do.
+- Don't call `cache.metrics()` on every request expecting per-request data — it returns a running aggregate. Use the event bus for per-call observability.
+- Don't expect lifetime percentiles. The buffer is bounded — for a 24h p95, sample-and-aggregate at your exporter, don't ask cache to remember every op forever.
+- Don't forget to attach early. If startup metrics matter, call `cache.metrics()` right after `cache.init()`.

package/skills/overview/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: overview
+description: 'Front-door orientation for `@warlock.js/cache` — multi-driver caching (memory / memoryExtended / lru / file / redis / pg / null / mock) with a single `cache` API: get/set/has/pull/remember, TTL shapes, tag-based invalidation, key namespaces, distributed locks, stale-while-revalidate, atomic update/merge, cache lists, vector similarity, metrics + events, and the `cached()` HOF. TRIGGER when: code imports from `@warlock.js/cache` (`cache`, `cached`, `setCacheConfigurations`, a `*CacheDriver`); user asks "what does @warlock.js/cache do", "which cache driver", "cache TTL / tags / invalidation", "distributed lock", "stale-while-revalidate", "semantic / vector cache", "compare with node-cache / keyv / cache-manager"; package.json adds `@warlock.js/cache`. Skip: specific task already known — load the matching task skill directly (`cache-basics`, `pick-cache-driver`, `configure-set-options`, `use-cache-tags`, `use-cache-namespace`, `use-cache-list`, `use-cache-lock`, `use-swr`, `use-cached-hof`, `use-cache-similarity`, `use-cache-update-merge`, `use-cache-atomic`, `use-cache-bulk`, `use-cache-utils`, `apply-cache-patterns`, `observe-cache`, `handle-cache-errors`, `configure-pg-cache`, `test-cache-code`).'
+---
+
+# `@warlock.js/cache` — overview
+
+One cache API over many drivers. Pick a driver (memory, memoryExtended, LRU, file, Redis, Postgres, null, mock), wire it once, and call `cache.get` / `cache.set` / `cache.remember` everywhere. On top of the key-value basics it adds tag invalidation, key namespaces, distributed locks, stale-while-revalidate, atomic update/merge, ordered lists, vector similarity, and built-in metrics + events.
+
+## When to reach for it
+
+- You need a cache abstraction that swaps drivers per environment (memory in dev, Redis in prod) without changing call sites.
+- You want more than get/set — tag-based bulk invalidation, locks for stampede safety, SWR for slow upstreams, or a semantic cache over vectors.
+- You're inside a Warlock app (the framework wires the driver from config) — or standalone, calling `setCacheConfigurations` + `cache.init` yourself.
+
+Skip if a plain `Map` covers your needs and you'll never need a second driver, TTLs, or invalidation.
+
+## The mental model in one paragraph
+
+A single `cache` singleton fronts a configured driver. `cache.set(key, value, options?)` writes (TTL via `ttl`/`expiresAt`, inline `tags`, `onConflict`, a per-call `driver` override, or a `vector` for similarity); `cache.get` / `has` / `pull` / `remove` / `many` / `remember` read. Tags let you invalidate sets of keys you can't enumerate ahead of time; namespaces auto-prefix keys with shared TTL/tag defaults; locks serialize work across processes; SWR serves stale-but-instant while refreshing in the background; `update`/`merge` do atomic read-modify-write; `list<T>(key)` gives ordered collections; `similar(vector, …)` does nearest-neighbor retrieval. `cache.metrics()` and `cache.on(event, …)` make it observable.
+
+## Skills index
+
+Nineteen task skills. Most apps start with `cache-basics` + `pick-cache-driver` + `configure-set-options`.
+
+### Foundations
+
+- [`cache-basics`](@warlock.js/cache/cache-basics/SKILL.md) — the `cache` singleton, primary ops (`set`/`get`/`has`/`pull`/`remove`/`many`/`forever`/`increment`/`decrement`/`remember`), TTL shapes, init flow. **Start here.**
+- [`pick-cache-driver`](@warlock.js/cache/pick-cache-driver/SKILL.md) — choose + configure a driver: `null` / `memory` / `memoryExtended` / `lru` / `file` / `redis` / `pg` / `mock`; `globalPrefix` for multi-tenant scoping.
+- [`configure-set-options`](@warlock.js/cache/configure-set-options/SKILL.md) — `cache.set`'s third argument: `ttl`, `expiresAt`, `tags`, `onConflict` (create/update/upsert), `driver`, `vector`.
+- [`configure-pg-cache`](@warlock.js/cache/configure-pg-cache/SKILL.md) — Postgres driver: KV-only (default) or pgvector mode; caller owns the `pg.Pool`, `driver.schema()` emits the DDL.
+
+### Invalidation + scoping
+
+- [`use-cache-tags`](@warlock.js/cache/use-cache-tags/SKILL.md) — tag on write, `cache.tags([...]).invalidate()` drops every bound key.
+- [`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md) — `cache.namespace(prefix, options?)` auto-prefixes keys with scope-level TTL/tag defaults and nested scopes.
+
+### Patterns
+
+- [`use-cached-hof`](@warlock.js/cache/use-cached-hof/SKILL.md) — `cached(fn, options)` wraps an async function; one declaration, many call sites, a bound `.invalidate(...args)`.
+- [`apply-cache-patterns`](@warlock.js/cache/apply-cache-patterns/SKILL.md) — `remember()` memoization, distributed locks via `onConflict: "create"`, negative caching, counters, per-tenant prefix, `CACHE_FOR.*` TTL constants.
+- [`use-cache-lock`](@warlock.js/cache/use-cache-lock/SKILL.md) — `cache.lock(key, ttl, fn)`: acquire → run → auto-release. For cron/imports/migrations and idempotent webhook/payment processing.
+- [`use-swr`](@warlock.js/cache/use-swr/SKILL.md) — `cache.swr(key, { freshTtl, staleTtl }, fn)`: instant when fresh, instant + background refresh when stale, blocks only when fully expired.
+- [`use-cache-update-merge`](@warlock.js/cache/use-cache-update-merge/SKILL.md) — atomic read-modify-write via `cache.update(key, fn)` / `cache.merge(key, partial)`, serialized per key, TTL-preserving.
+- [`use-cache-atomic`](@warlock.js/cache/use-cache-atomic/SKILL.md) — `cache.increment` / `cache.decrement` counters; per-driver atomicity + TTL behavior.
+- [`use-cache-bulk`](@warlock.js/cache/use-cache-bulk/SKILL.md) — `cache.many(keys)` / `cache.setMany(record, ttl?)` for batch reads/writes.
+- [`use-cache-list`](@warlock.js/cache/use-cache-list/SKILL.md) — `cache.list<T>(key)`: `push`/`unshift`/`pop`/`shift`/`slice`/`trim`/`clear` for queues, recent-N buffers, sliding windows.
+- [`use-cache-similarity`](@warlock.js/cache/use-cache-similarity/SKILL.md) — `cache.similar(vector, { topK, threshold?, tags? })` for semantic caches, RAG retrieval, nearest-neighbor lookup.
+
+### Operations
+
+- [`observe-cache`](@warlock.js/cache/observe-cache/SKILL.md) — `cache.metrics()` (hit rate, latency p50/p95/p99) + the event bus (`cache.on("hit" | "miss" | "set" | "removed" | "flushed" | "expired" | "connected" | "disconnected" | "error", …)`).
+- [`handle-cache-errors`](@warlock.js/cache/handle-cache-errors/SKILL.md) — the error classes: `CacheError`, `CacheConfigurationError`, `CacheConnectionError`, `CacheDriverNotInitializedError`, `CacheUnsupportedError`, `CacheConcurrencyError`.
+- [`test-cache-code`](@warlock.js/cache/test-cache-code/SKILL.md) — `MockCacheDriver` (behavioral assertions), `MemoryCacheDriver` (full-stack), `NullCacheDriver` (graceful degradation).
+
+### Utilities
+
+- [`use-cache-utils`](@warlock.js/cache/use-cache-utils/SKILL.md) — low-level re-exports: `parseTtl`, `parseCacheKey`, `resolveTtl`, `expiresAtToTtl`, `mergeTagSets`, `injectTags`, `cosineSimilarity`, and the `CACHE_FOR` TTL enum.
+
+## What this package deliberately doesn't do
+
+- **Be a database.** It's a cache — entries expire, drivers may evict. Don't store anything you can't recompute.
+- **Guarantee cross-driver feature parity.** Vector similarity needs a memory-family driver (`memory` / `memoryExtended` / `lru`, brute force) or `pg` with pgvector; `redis` and `file` raise `CacheUnsupportedError`. Locks/tags behave per driver. Unsupported ops raise `CacheUnsupportedError` rather than silently degrading.
+- **Own your Postgres pool.** The `pg` driver takes the `pg.Pool`/`Client` you already built and never closes it — connection lifecycle stays yours. (Redis is the opposite: you pass `url`/`host` options and the driver builds and owns the client, calling `quit()` on `disconnect()`.)
+
+## See also
+
+- [`@warlock.js/core/overview/SKILL.md`](@warlock.js/core/overview/SKILL.md) — wires the cache driver from app config and exposes the singleton.
+- `mongez-agent-kit-authoring-skills` (load via agent-kit sync) — how this becomes `.claude/skills/warlock-js-cache-overview/`.

package/skills/pick-cache-driver/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: pick-cache-driver
+description: 'Pick a cache driver — null / memory / memoryExtended / lru / file / redis / pg / mock — and configure it. Triggers: `cache.setCacheConfigurations`, `BaseCacheDriver`, `cache.use`, `cache.load`, `cache.driver`, `globalPrefix`; "which cache driver should I use", "configure redis driver", "register custom cache driver", "multi-tenant scoping"; typical import `import { cache, BaseCacheDriver } from "@warlock.js/cache"`. Skip: cache CRUD — `@warlock.js/cache/cache-basics/SKILL.md`; pg setup — `@warlock.js/cache/configure-pg-cache/SKILL.md`; competing libs `lru-cache`, `node-cache`, `keyv`, `ioredis`; native `Map`.'
+---
+
+# Cache drivers — pick the right one
+
+Seven production drivers + a mock driver ship in-box. Pick by durability, scope, and workload.
+
+| Driver | Process scope | Persists on restart | Good for | Avoid when |
+| --- | --- | --- | --- | --- |
+| `null` | — | — | Disabling cache in tests; feature-flagging off | You actually want caching |
+| `memory` | Single process | No | Hot in-process data with default TTL; smallest latency | Multi-process / multi-node |
+| `memoryExtended` | Single process | No | Sliding-window TTL (TTL resets on every read) | Any multi-process deploy |
+| `lru` | Single process | No | Bounded in-memory caches (capacity-based eviction) | Need cross-process sharing |
+| `file` | Single host | Yes | Build artefacts, local dev persistence across restarts | Concurrency (no locks); multi-host |
+| `redis` | Shared | Yes (Redis-managed) | Anything shared across processes / nodes | Single-process-only workload — overkill |
+| `pg` | Shared | Yes (Postgres-managed) | You already run Postgres; semantic caching / RAG via pgvector | High-throughput hot reads (Redis is faster) |
+
+## Capability matrix
+
+| Capability | null | memory | memoryExt | lru | file | redis | pg |
+| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
+| `set` / `get` / `remove` / `flush` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| TTL (number or string) | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Sliding TTL on read | — | — | ✓ | — | — | — | — |
+| `removeNamespace` | noop | ✓ | ✓ | ✓ (prefix-scan) | ✓ | ✓ | ✓ (LIKE prefix) |
+| `onConflict: "create"` / `"update"` | noop | emulated | emulated | emulated | emulated | native `NX`/`XX` | native (INSERT ON CONFLICT) |
+| Native increment / decrement | — | ✓ | ✓ | ✓ | ✓ | atomic `INCRBY`/`DECRBY` | ✓ |
+| `update()` / `merge()` | ✓ | ✓ | ✓ | ✓ | ✗ throws | ✓ (single-process safety only today) | ✓ |
+| List sub-API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (O(n) JSON blob today; native LPUSH/LRANGE in v2.1) | ✓ |
+| Tagged invalidation | noop | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (native GIN(tags)) |
+| `similar()` / `set({ vector })` | returns `[]` / noop | ✓ brute force | ✓ brute force | ✓ brute force | ✗ throws | ✗ throws (Phase 2 backlog) | ✓ (with `vector` config — pgvector) |
+
+## Global config TTL — accepts number or string
+
+```ts
+options: {
+  redis:  { url: "...", ttl: "7d" },   // string OK
+  memory: { ttl: 3600 },                // number OK
+  lru:    { capacity: 10_000 },         // LRU has no TTL option today
+  file:   { directory: () => "/var/cache/myapp", ttl: "1h" },
+  pg:     { client: pool, ttl: "1h" },                           // KV-only
+  // pg with pgvector:
+  // pg:  { client: pool, vector: { dimensions: 1536, index: "hnsw" } },
+}
+```
+
+## Global prefix (multi-tenant scoping)
+
+Every driver accepts `globalPrefix: string | (() => string)`. The function form runs per call — pair it with request-local async context to scope every cached key to the current tenant / user / client automatically:
+
+```ts
+options: {
+  redis: {
+    url: "...",
+    globalPrefix: () => `tenant-${currentContext.tenantId}`,
+  },
+}
+```
+
+## Registering a custom driver
+
+```ts
+import { BaseCacheDriver, cache } from "@warlock.js/cache";
+
+class MemcachedCacheDriver extends BaseCacheDriver<MyClient, MyOptions> {
+  public name = "memcached";
+  // … implement set / get / remove / flush / removeNamespace / connect
+}
+
+cache.setCacheConfigurations({
+  default: "memcached",
+  drivers: { memcached: MemcachedCacheDriver },
+  options: { memcached: { host: "localhost" } },
+});
+```
+
+Extending `BaseCacheDriver` gives you free: TTL parsing, key parsing, event emission, stampede-safe `remember`, deep-clone-on-read, default `update` / `merge` / `list` implementations.
+
+## Runtime driver options — `cache.use(name, options)`
+
+Some driver options can only be built at runtime (`pg`'s `client: pg.Pool`, pre-wired clients). Pass them as the second arg to `cache.use` / `cache.load` / `cache.driver` — they merge over `setCacheConfigurations({ options })` per-key, runtime wins.
+
+```ts
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+cache.setCacheConfigurations({
+  default: "pg",
+  drivers: { pg: PgCacheDriver },
+  options: { pg: { table: "cache" } },        // static
+});
+
+await cache.use("pg", { client: pool });       // runtime — skip init() in this case
+```
+
+Constraints:
+- The driver name must be registered in `setCacheConfigurations({ drivers })` — runtime options don't bypass registration.
+- Once a driver is loaded, calling `use`/`load`/`driver` again with **non-empty** new options throws `CacheConfigurationError`. Register a second driver name if you need a different config.
+- Calling without options (or with `{}`) on an already-loaded driver returns the cached instance silently.
+
+## Per-call driver override
+
+When most writes go to the default driver but one call needs a different one:
+
+```ts
+await cache.set("audit:event", event, { driver: "redis" });
+```
+
+The manager loads (and connects) the override driver lazily on first use, then routes that single operation through it without mutating `currentDriver`.
+
+## See also
+
+- [`@warlock.js/cache/configure-pg-cache/SKILL.md`](@warlock.js/cache/configure-pg-cache/SKILL.md) — full pg setup (KV-only and pgvector mode)
+- [`@warlock.js/cache/test-cache-code/SKILL.md`](@warlock.js/cache/test-cache-code/SKILL.md) — `MockCacheDriver` and `NullCacheDriver` for tests

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

@@ -0,0 +1,219 @@
+---
+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.