@warlock.js/cache 5.19.0 → 5.20.0

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

@@ -1,92 +1,92 @@
----
-name: handle-cache-errors
-description: "Error classes in @warlock.js/cache; use when you need to handle cache errors."
----
-
-# 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. |
-| `CacheError` (file driver, path containment) | A key/namespace, after percent-encoding, still resolves outside the cache root — `"Cache key resolves outside the cache directory: ..."`. Last line of defense against path traversal on top of the encoding step; should not happen in normal use. | Treat as a programmer/attacker-input error — don't retry; investigate the key source. See [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) for the encoding contract. |
-
-## 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.
+---
+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. |
+| `CacheError` (file driver, path containment) | A key/namespace, after percent-encoding, still resolves outside the cache root — `"Cache key resolves outside the cache directory: ..."`. Last line of defense against path traversal on top of the encoding step; should not happen in normal use. | Treat as a programmer/attacker-input error — don't retry; investigate the key source. See [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) for the encoding contract. |
+
+## 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/index.md

@@ -0,0 +1,20 @@
+---
+description: "Cache layer for Warlock apps with pluggable drivers (memory, LRU, file, Redis, Postgres). Exports `cache`, `CacheManager`, `cached`, `TaggedCache`, `ScopedCache`, `RedisCacheDriver`, `MemoryCacheDriver`, `MockCacheDriver`, `PgCacheDriver`. Use for: \"cache this query for 5 minutes\", \"invalidate every key for tenant 42\", \"stale-while-revalidate\", \"take a lock so only one worker runs this\", \"tag keys and flush the tag\", \"increment a counter in cache\". Not this package: HTTP response/page caching belongs to @warlock.js/core or web; persistent data is a @warlock.js/cascade model."
+---
+# @warlock.js/cache
+
+The `cache` singleton (a `CacheManager`) fronts one active driver. Everything, from `get`/`set` through `remember`, `swr`, `tags`, `namespace`, `lock` and `list`, works the same on any driver, so pick a driver once and write app code against `cache`.
+
+## The 80% path
+1. Orient: `overview.md`, `cache-basics.md`.
+2. Choose and configure a driver: `pick-cache-driver.md` (Postgres: `configure-pg-cache.md`; TTL and options: `configure-set-options.md`).
+3. Cache expensive reads with `remember` or the `cached` wrapper: `use-cached-hof.md`, `apply-cache-patterns.md`.
+4. Invalidate in groups: `use-cache-tags.md` or `use-cache-namespace.md`.
+5. Stampede protection and freshness: `use-swr.md`, `use-cache-lock.md`.
+6. Test with the mock driver: `test-cache-code.md`; errors and metrics: `handle-cache-errors.md`, `observe-cache.md`.
+
+## Conventions and pitfalls
+- Tags versus namespaces: tags are cross-cutting groups you flush together; a namespace is a key prefix you remove wholesale. Choose per invalidation need.
+- Check `configure-set-options.md` for TTL units, and avoid `forever` for data that can go stale.
+- Atomic counters, bulk ops, lists, merge and similarity have their own topics (`use-cache-atomic.md`, `use-cache-bulk.md`, `use-cache-list.md`, `use-cache-update-merge.md`, `use-cache-similarity.md`); do not hand-roll read-modify-write.
+- Not every driver supports every feature; check the driver topic first.

package/skills/observe-cache/SKILL.md

@@ -1,103 +1,103 @@
----
-name: observe-cache
-description: "Cache observability — cache.metrics() and the event bus in @warlock.js/cache; use when you need to observe cache."
----
-
-# 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()`.
+---
+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()`.