@warlock.js/cache 5.24.0 → 5.25.0

package/llms.txt

@@ -21,7 +21,7 @@
 - [use-cache-lock](@warlock.js/cache/use-cache-lock/SKILL.md): (no description)
 - [use-cache-namespace](@warlock.js/cache/use-cache-namespace/SKILL.md): (no description)
 - [use-cache-similarity](@warlock.js/cache/use-cache-similarity/SKILL.md): (no description)
-- [use-cache-tags](@warlock.js/cache/use-cache-tags/SKILL.md): Tag-based invalidation — attach tags on write, then cache.tags([...]).invalidate() drops every key bound to any of those tags. Triggers: `cache.tags`, `invalidate`, `cache.set` with `tags`; "invalidate every key tagged users", "drop everything for tenant 42", "bulk cache invalidation without knowing keys", "tag a cached value"; typical import `import { cache } from "@warlock.js/cache"`. Skip: prefix-based drop — `@warlock.js/cache/use-cache-namespace/SKILL.md`; HOF memoization with tags — `@warlock.js/cache/use-cached-hof/SKILL.md`; SWR — `@warlock.js/cache/use-swr/SKILL.md`; competing libs `cache-manager` tags, Next.js `revalidateTag`.
+- [use-cache-tags](@warlock.js/cache/use-cache-tags/SKILL.md): (no description)
 - [use-cache-update-merge](@warlock.js/cache/use-cache-update-merge/SKILL.md): (no description)
 - [use-cache-utils](@warlock.js/cache/use-cache-utils/SKILL.md): (no description)
 - [use-cached-hof](@warlock.js/cache/use-cached-hof/SKILL.md): (no description)

package/package.json

@@ -5,9 +5,9 @@
     "environment": "server"
   },
   "dependencies": {
-    "@warlock.js/fs": "5.24.0",
+    "@warlock.js/fs": "5.25.0",
     "@mongez/reinforcements": "^4.0.2",
-    "@warlock.js/logger": "5.24.0",
+    "@warlock.js/logger": "5.25.0",
     "ms": "^2.1.3"
   },
   "peerDependencies": {
@@ -46,7 +46,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.24.0",
+  "version": "5.25.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/apply-cache-patterns/SKILL.md

@@ -1,98 +1,98 @@
----
-name: apply-cache-patterns
-description: 'Compose cache primitives into real-world patterns — remember() memoization, cross-node stampede protection via a distributed lock (onConflict: ''create''), negative caching, and per-tenant scoping. Triggers: `cache.remember`, `cache.set` with `onConflict: "create"`, `globalPrefix`; "memoize this function", "prevent cache stampede across nodes", "cache not-found results", "per-tenant cache scoping"; typical import `import { cache } from "@warlock.js/cache"`. Skip: counters — `@warlock.js/cache/use-cache-atomic/SKILL.md`; bulk get/set — `@warlock.js/cache/use-cache-bulk/SKILL.md`; TTL constants/utilities — `@warlock.js/cache/use-cache-utils/SKILL.md`; named lock wrapper — `@warlock.js/cache/use-cache-lock/SKILL.md`; SWR — `@warlock.js/cache/use-swr/SKILL.md`; competing libs `lru-cache`, `node-cache`, `keyv`.'
----
-
-# Real-world caching patterns
-
-Common shapes — the "general patterns" file. Specialized topics have dedicated skills: [`use-cache-tags`](@warlock.js/cache/use-cache-tags/SKILL.md), [`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md), [`use-swr`](@warlock.js/cache/use-swr/SKILL.md), [`use-cache-lock`](@warlock.js/cache/use-cache-lock/SKILL.md), [`use-cache-list`](@warlock.js/cache/use-cache-list/SKILL.md).
-
-## Memoize an expensive function — `remember`
-
-```ts
-const user = await cache.remember(`user:${id}`, "1h", async () => {
-  return db.users.find(id);   // runs only on cache miss
-});
-```
-
-- The callback runs once per miss.
-- Concurrent callers for the same key share the in-flight promise (stampede protection) — within one Node process.
+---
+name: apply-cache-patterns
+description: 'Compose cache primitives into real-world patterns — remember() memoization, cross-node stampede protection via a distributed lock (onConflict: ''create''), negative caching, and per-tenant scoping. Triggers: `cache.remember`, `cache.set` with `onConflict: "create"`, `globalPrefix`; "memoize this function", "prevent cache stampede across nodes", "cache not-found results", "per-tenant cache scoping"; typical import `import { cache } from "@warlock.js/cache"`. Skip: counters — `@warlock.js/cache/use-cache-atomic/SKILL.md`; bulk get/set — `@warlock.js/cache/use-cache-bulk/SKILL.md`; TTL constants/utilities — `@warlock.js/cache/use-cache-utils/SKILL.md`; named lock wrapper — `@warlock.js/cache/use-cache-lock/SKILL.md`; SWR — `@warlock.js/cache/use-swr/SKILL.md`; competing libs `lru-cache`, `node-cache`, `keyv`.'
+---
+
+# Real-world caching patterns
+
+Common shapes — the "general patterns" file. Specialized topics have dedicated skills: [`use-cache-tags`](@warlock.js/cache/use-cache-tags/SKILL.md), [`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md), [`use-swr`](@warlock.js/cache/use-swr/SKILL.md), [`use-cache-lock`](@warlock.js/cache/use-cache-lock/SKILL.md), [`use-cache-list`](@warlock.js/cache/use-cache-list/SKILL.md).
+
+## Memoize an expensive function — `remember`
+
+```ts
+const user = await cache.remember(`user:${id}`, "1h", async () => {
+  return db.users.find(id);   // runs only on cache miss
+});
+```
+
+- The callback runs once per miss.
+- Concurrent callers for the same key share the in-flight promise (stampede protection) — within one Node process.
 - `null` is the only miss. `0`, `false` and `""` are cached like any other value, so `remember` doesn't recompute them. A callback returning `null` is not cached, so the callback re-runs on the next call: to cache a "not found," store a sentinel (see negative caching below).
 - Stampede protection is per process, even on redis. To run something once across servers, wrap it in `cache.lock()` on `redis` or `pg`.
-
-## Cross-process stampede protection — distributed lock via `onConflict`
-
-`remember`'s lock is per-process. For cross-node safety, acquire a short-lived distributed lock before doing expensive work:
-
-```ts
-const lockKey = `lock:build-report:${reportId}`;
-const acquired = await cache.set(lockKey, process.pid, {
-  onConflict: "create",
-  ttl: "2m",
-});
-
-if (!acquired.wasSet) {
-  // another node is already building — wait or skip
-  return cache.get(`report:${reportId}`);
-}
-
-try {
-  const report = await buildExpensiveReport(reportId);
-  await cache.set(`report:${reportId}`, report, "1h");
-  return report;
-} finally {
-  await cache.remove(lockKey);
-}
-```
-
-This requires a driver with atomic `SET NX` — Redis is native, memory/LRU/file emulate (single-process only). For a higher-level wrapper that does the lock-and-release for you, see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
-
-## Negative caching
-
-Cache "not found" results with a shorter TTL to avoid hammering the origin:
-
-```ts
-const user = await cache.remember(`user:${id}`, "5m", async () => {
-  const found = await db.users.find(id);
-  return found ?? { __miss: true };
-});
-
-if (user?.__miss) {
-  return null;
-}
-```
-
+
+## Cross-process stampede protection — distributed lock via `onConflict`
+
+`remember`'s lock is per-process. For cross-node safety, acquire a short-lived distributed lock before doing expensive work:
+
+```ts
+const lockKey = `lock:build-report:${reportId}`;
+const acquired = await cache.set(lockKey, process.pid, {
+  onConflict: "create",
+  ttl: "2m",
+});
+
+if (!acquired.wasSet) {
+  // another node is already building — wait or skip
+  return cache.get(`report:${reportId}`);
+}
+
+try {
+  const report = await buildExpensiveReport(reportId);
+  await cache.set(`report:${reportId}`, report, "1h");
+  return report;
+} finally {
+  await cache.remove(lockKey);
+}
+```
+
+This requires a driver with atomic `SET NX` — Redis is native, memory/LRU/file emulate (single-process only). For a higher-level wrapper that does the lock-and-release for you, see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
+
+## Negative caching
+
+Cache "not found" results with a shorter TTL to avoid hammering the origin:
+
+```ts
+const user = await cache.remember(`user:${id}`, "5m", async () => {
+  const found = await db.users.find(id);
+  return found ?? { __miss: true };
+});
+
+if (user?.__miss) {
+  return null;
+}
+```
+
 Don't return raw `null` inside `remember` to "cache the miss": `null` is the miss sentinel, so the callback re-runs every time and the origin still gets hammered. The `{ __miss: true }` sentinel is what skips the next call.
-
-## Per-tenant caching
-
-```ts
-// In cache config:
-options: {
-  redis: {
-    url: "...",
-    globalPrefix: () => `tenant-${currentContext.tenantId}`,
-  },
-}
-
-// At the call site — no tenancy awareness needed:
-await cache.set("user:1", user, "1h");
-// Actual key: "tenant-42.user.1"
-```
-
-Clear a tenant out:
-```ts
-await cache.removeNamespace("");   // when globalPrefix is set, flush scopes to it
-// or
-await cache.tags([`tenant-${tenantId}`]).invalidate();
-```
-
-## See also
-
-- [`@warlock.js/cache/use-cache-atomic/SKILL.md`](@warlock.js/cache/use-cache-atomic/SKILL.md) — `increment` / `decrement` counters
-- [`@warlock.js/cache/use-cache-bulk/SKILL.md`](@warlock.js/cache/use-cache-bulk/SKILL.md) — `many` / `setMany`
-- [`@warlock.js/cache/use-cache-utils/SKILL.md`](@warlock.js/cache/use-cache-utils/SKILL.md) — `CACHE_FOR` constants and TTL/key helpers
-- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — tag-based invalidation
-- [`@warlock.js/cache/use-cache-namespace/SKILL.md`](@warlock.js/cache/use-cache-namespace/SKILL.md) — scoped handles and `removeNamespace`
-- [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md) — stale-while-revalidate for slow upstreams
-- [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md) — `cached()` HOF for declarative memoization
+
+## Per-tenant caching
+
+```ts
+// In cache config:
+options: {
+  redis: {
+    url: "...",
+    globalPrefix: () => `tenant-${currentContext.tenantId}`,
+  },
+}
+
+// At the call site — no tenancy awareness needed:
+await cache.set("user:1", user, "1h");
+// Actual key: "tenant-42.user.1"
+```
+
+Clear a tenant out:
+```ts
+await cache.removeNamespace("");   // when globalPrefix is set, flush scopes to it
+// or
+await cache.tags([`tenant-${tenantId}`]).invalidate();
+```
+
+## See also
+
+- [`@warlock.js/cache/use-cache-atomic/SKILL.md`](@warlock.js/cache/use-cache-atomic/SKILL.md) — `increment` / `decrement` counters
+- [`@warlock.js/cache/use-cache-bulk/SKILL.md`](@warlock.js/cache/use-cache-bulk/SKILL.md) — `many` / `setMany`
+- [`@warlock.js/cache/use-cache-utils/SKILL.md`](@warlock.js/cache/use-cache-utils/SKILL.md) — `CACHE_FOR` constants and TTL/key helpers
+- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — tag-based invalidation
+- [`@warlock.js/cache/use-cache-namespace/SKILL.md`](@warlock.js/cache/use-cache-namespace/SKILL.md) — scoped handles and `removeNamespace`
+- [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md) — stale-while-revalidate for slow upstreams
+- [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md) — `cached()` HOF for declarative memoization

package/skills/configure-set-options/SKILL.md

@@ -1,102 +1,102 @@
----
-name: configure-set-options
-description: 'Configure cache.set''s third argument — ttl, expiresAt, tags, onConflict (create / update / upsert), driver, vector. Triggers: `cache.set`, `ttl`, `expiresAt`, `tags`, `onConflict`, `driver`, `vector`, `CacheSetResult`, `wasSet`; "set a key only if missing", "set with absolute deadline", "attach tags inline", "route one cache call to redis"; typical import `import { cache } from "@warlock.js/cache"`. Skip: tag fluent API — `@warlock.js/cache/use-cache-tags/SKILL.md`; vector queries — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `keyv`, `ioredis`.'
----
-
-# The `set` options object
-
-`cache.set(key, value, ttlOrOptions?)` — the 3rd argument accepts three shapes.
-
-## The three shapes
-
-```ts
-// 1. Number — seconds
-await cache.set("name", "Jane", 600);
-
-// 2. String — human-readable duration, parsed via `ms`
-await cache.set("name", "Jane", "10m");   // "1s", "30m", "1h", "7d", "2 weeks"
-
-// 3. Options object
-await cache.set("user:1", user, {
-  ttl: "1h",
-  expiresAt: new Date("2026-12-31"),
-  tags: ["users"],
-  onConflict: "create",
-  driver: "redis",
-});
-```
-
-## Option keys
-
-| Key | Type | Notes |
-| --- | --- | --- |
-| `ttl` | `number \| string` | Relative expiry. Mutually exclusive with `expiresAt`. |
-| `expiresAt` | `number \| Date` | Absolute deadline (epoch ms or Date). Must be in the future. Mutually exclusive with `ttl`. |
-| `tags` | `string[]` | Inline equivalent of `cache.tags([...]).set(...)`. See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md). |
-| `onConflict` | `"create" \| "update" \| "upsert"` | See below. Default `"upsert"`. |
-| `driver` | `string` | Per-call driver override by registered name. |
-| `vector` | `number[]` | Embedding indexed alongside the entry for [`cache.similar()`](@warlock.js/cache/use-cache-similarity/SKILL.md). Drivers without similarity support throw `CacheUnsupportedError`. |
-
+---
+name: configure-set-options
+description: 'Configure cache.set''s third argument — ttl, expiresAt, tags, onConflict (create / update / upsert), driver, vector. Triggers: `cache.set`, `ttl`, `expiresAt`, `tags`, `onConflict`, `driver`, `vector`, `CacheSetResult`, `wasSet`; "set a key only if missing", "set with absolute deadline", "attach tags inline", "route one cache call to redis"; typical import `import { cache } from "@warlock.js/cache"`. Skip: tag fluent API — `@warlock.js/cache/use-cache-tags/SKILL.md`; vector queries — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `keyv`, `ioredis`.'
+---
+
+# The `set` options object
+
+`cache.set(key, value, ttlOrOptions?)` — the 3rd argument accepts three shapes.
+
+## The three shapes
+
+```ts
+// 1. Number — seconds
+await cache.set("name", "Jane", 600);
+
+// 2. String — human-readable duration, parsed via `ms`
+await cache.set("name", "Jane", "10m");   // "1s", "30m", "1h", "7d", "2 weeks"
+
+// 3. Options object
+await cache.set("user:1", user, {
+  ttl: "1h",
+  expiresAt: new Date("2026-12-31"),
+  tags: ["users"],
+  onConflict: "create",
+  driver: "redis",
+});
+```
+
+## Option keys
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `ttl` | `number \| string` | Relative expiry. Mutually exclusive with `expiresAt`. |
+| `expiresAt` | `number \| Date` | Absolute deadline (epoch ms or Date). Must be in the future. Mutually exclusive with `ttl`. |
+| `tags` | `string[]` | Inline equivalent of `cache.tags([...]).set(...)`. See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md). |
+| `onConflict` | `"create" \| "update" \| "upsert"` | See below. Default `"upsert"`. |
+| `driver` | `string` | Per-call driver override by registered name. |
+| `vector` | `number[]` | Embedding indexed alongside the entry for [`cache.similar()`](@warlock.js/cache/use-cache-similarity/SKILL.md). Drivers without similarity support throw `CacheUnsupportedError`. |
+
 ## TTL parsing
 
 - Number or bare numeric string (`"3600"`) = **seconds**. Fractions and sub-second values (`0.5`, `"500ms"`) round **up** to whole seconds, never 0.
 - `0` / `Infinity` = no expiry. `NaN`, negative and unparseable values throw `CacheConfigurationError`.
 - `cache.lock()` refuses any TTL that never expires.
 
-## `onConflict` policies
-
-Self-documenting enum; Redis maps these to `NX` / `XX` natively, others emulate.
-
-```ts
-// create — set only if key is missing
-const result = await cache.set("lock:jobs:import", workerId, {
-  onConflict: "create",
-  ttl: "5m",
-});
-// result: { wasSet: true, existing: null } on acquire
-//         { wasSet: false, existing: <prior workerId> } on conflict — someone else holds the lock
-
-if (!result.wasSet) {
-  // another worker is already running; abort.
-}
-
-// update — set only if key exists (don't resurrect expired sessions)
-await cache.set("session:abc", session, { onConflict: "update" });
-```
-
-Conditional writes (`"create"` / `"update"`) return a `CacheSetResult`; unconditional `"upsert"` returns the value or driver instance as before.
-
-## Mutually-exclusive validations
-
-Both of these throw `CacheConfigurationError`:
-
-```ts
-await cache.set("k", v, { ttl: "1h", expiresAt: Date.now() + 1000 });  // both set
-await cache.set("k", v, { expiresAt: Date.now() - 1000 });              // past deadline
-```
-
-## Inline tags vs `cache.tags([...]).set(...)`
-
-Both work; inline is terser when you're writing one value under known tags:
-
-```ts
-// Inline
-await cache.set("user:1", user, { tags: ["users", "tenant-42"] });
-
-// Fluent (useful when you already have a tagged instance)
-const users = cache.tags(["users"]);
-await users.set("user:1", user);
-await users.invalidate();   // drops every key tagged "users"
-```
-
-Inline tag semantics are **additive**, never replace. A subsequent `set("user:1", ...)` with no `tags` leaves previous associations intact (the tag index still points to the key), and a `set(..., { tags: [...] })` only appends the key to those tags' index entries — it never removes the key from tags it was bound to earlier. To drop stale bindings, invalidate the old tag explicitly via `cache.tags([...]).invalidate()`.
-
-## Back-compat note
-
-Every call site using the old positional-TTL shape keeps working:
-
-```ts
-await cache.set("k", v);           // no TTL — driver default
-await cache.set("k", v, 3600);     // seconds
-await cache.set("k", v, undefined); // same as no TTL
-```
+## `onConflict` policies
+
+Self-documenting enum; Redis maps these to `NX` / `XX` natively, others emulate.
+
+```ts
+// create — set only if key is missing
+const result = await cache.set("lock:jobs:import", workerId, {
+  onConflict: "create",
+  ttl: "5m",
+});
+// result: { wasSet: true, existing: null } on acquire
+//         { wasSet: false, existing: <prior workerId> } on conflict — someone else holds the lock
+
+if (!result.wasSet) {
+  // another worker is already running; abort.
+}
+
+// update — set only if key exists (don't resurrect expired sessions)
+await cache.set("session:abc", session, { onConflict: "update" });
+```
+
+Conditional writes (`"create"` / `"update"`) return a `CacheSetResult`; unconditional `"upsert"` returns the value or driver instance as before.
+
+## Mutually-exclusive validations
+
+Both of these throw `CacheConfigurationError`:
+
+```ts
+await cache.set("k", v, { ttl: "1h", expiresAt: Date.now() + 1000 });  // both set
+await cache.set("k", v, { expiresAt: Date.now() - 1000 });              // past deadline
+```
+
+## Inline tags vs `cache.tags([...]).set(...)`
+
+Both work; inline is terser when you're writing one value under known tags:
+
+```ts
+// Inline
+await cache.set("user:1", user, { tags: ["users", "tenant-42"] });
+
+// Fluent (useful when you already have a tagged instance)
+const users = cache.tags(["users"]);
+await users.set("user:1", user);
+await users.invalidate();   // drops every key tagged "users"
+```
+
+Inline tag semantics are **additive**, never replace. A subsequent `set("user:1", ...)` with no `tags` leaves previous associations intact (the tag index still points to the key), and a `set(..., { tags: [...] })` only appends the key to those tags' index entries — it never removes the key from tags it was bound to earlier. To drop stale bindings, invalidate the old tag explicitly via `cache.tags([...]).invalidate()`.
+
+## Back-compat note
+
+Every call site using the old positional-TTL shape keeps working:
+
+```ts
+await cache.set("k", v);           // no TTL — driver default
+await cache.set("k", v, 3600);     // seconds
+await cache.set("k", v, undefined); // same as no TTL
+```

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

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