@warlock.js/cache 5.30.0 → 5.32.0

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

@@ -38,9 +38,7 @@ TTL rules: a number or a bare numeric string (`"90"`) is **seconds**; `"500ms"`
 ## Return shape — discriminated union
 
 ```ts
-type LockOutcome<T> =
-  | { acquired: true; value: T }
-  | { acquired: false };
+type LockOutcome<T> = { acquired: true; value: T } | { acquired: false };
 ```
 
 Unambiguous even when `fn` returns `undefined`. Narrow with TS:
@@ -49,7 +47,7 @@ Unambiguous even when `fn` returns `undefined`. Narrow with TS:
 const outcome = await cache.lock("lock.x", "1m", async () => compute());
 
 if (outcome.acquired) {
-  console.log(outcome.value);   // typed
+  console.log(outcome.value); // typed
 } else {
   console.log("someone else is running");
 }
@@ -60,19 +58,15 @@ if (outcome.acquired) {
 ### Cron on only one server
 
 ```ts
-cron.daily("3am", () =>
-  cache.lock("lock.cleanup", "30m", () => db.cleanup()),
-);
+cron.daily("3am", () => cache.lock("lock.cleanup", "30m", () => db.cleanup()));
 ```
 
 ### Idempotent webhook
 
 ```ts
 app.post("/webhooks/stripe", async (req, res) => {
-  const outcome = await cache.lock(
-    `webhook.stripe.${req.body.id}`,
-    "24h",
-    () => processStripeEvent(req.body),
+  const outcome = await cache.lock(`webhook.stripe.${req.body.id}`, "24h", () =>
+    processStripeEvent(req.body),
   );
 
   if (!outcome.acquired) {
@@ -97,13 +91,13 @@ await cache.lock(
 
 ## Driver behavior
 
-| Driver | Cross-process safe? |
-|--------|:-:|
-| `redis` | ✅ Native `SET … NX EX`, Lua release |
-| `pg` | ✅ `INSERT … ON CONFLICT`, one-statement release |
+| Driver                              |                Cross-process safe?                |
+| ----------------------------------- | :-----------------------------------------------: |
+| `redis`                             |       ✅ Native `SET … NX EX`, Lua release        |
+| `pg`                                | ✅ `INSERT … ON CONFLICT`, one-statement release  |
 | `memory` / `memoryExtended` / `lru` | ❌ In-process only (exclusive within the process) |
-| `file` | ⚠️ Single-host only (exclusive create) |
-| `null` | n/a — always "acquires" |
+| `file`                              |      ⚠️ Single-host only (exclusive create)       |
+| `null`                              |              n/a — always "acquires"              |
 
 ## Gotchas
 

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

@@ -12,10 +12,10 @@ When you'll touch the same prefix more than a couple of times, grab a scoped han
 ```ts
 const chat = cache.namespace(`chats.${id}`, { ttl: "30d", tags: [`user.${userId}`] });
 
-await chat.set("messages.10", msg);          // chats.<id>.messages.10, 30d, user.<userId>
-await chat.set("draft", d, { ttl: "1h" });   // per-call ttl wins
-await chat.tags(["unread"]).set("ping", p);  // tags merge: user.<userId> + unread
-await chat.clear();                           // sugar for removeNamespace
+await chat.set("messages.10", msg); // chats.<id>.messages.10, 30d, user.<userId>
+await chat.set("draft", d, { ttl: "1h" }); // per-call ttl wins
+await chat.tags(["unread"]).set("ping", p); // tags merge: user.<userId> + unread
+await chat.clear(); // sugar for removeNamespace
 ```
 
 Scopes are pure views — same connection, same driver, no extra state. Per-call options always win over scope defaults; tags merge additively.
@@ -24,9 +24,9 @@ Scopes are pure views — same connection, same driver, no extra state. Per-call
 
 ```ts
 const chat = cache.namespace(`chats.${id}`, { ttl: "30d" });
-const typing = chat.namespace("typing", { ttl: "5s" });  // overrides parent ttl
+const typing = chat.namespace("typing", { ttl: "5s" }); // overrides parent ttl
 
-await typing.set("user.42", true);                       // chats.<id>.typing.user.42, 5s
+await typing.set("user.42", true); // chats.<id>.typing.user.42, 5s
 ```
 
 Nested scopes inherit defaults and can override. Tags accumulate.
@@ -41,14 +41,14 @@ Inline prefixes are still fine for one-off writes.
 
 ## Plain `removeNamespace` when you already have the prefix
 
-When you *do* know the prefix string and don't need a scoped handle for repeated reads/writes:
+When you _do_ know the prefix string and don't need a scoped handle for repeated reads/writes:
 
 ```ts
 await cache.set("user:1:profile", profile);
-await cache.set("user:1:prefs",   prefs);
+await cache.set("user:1:prefs", prefs);
 await cache.set("user:2:profile", otherProfile);
 
-await cache.removeNamespace("user.1");  // drops both user:1 entries, keeps user:2
+await cache.removeNamespace("user.1"); // drops both user:1 entries, keeps user:2
 ```
 
 Cheaper than tags (no reverse index to maintain). Every real driver supports it — memory family and `lru` by prefix-scan, `file` by directory (including dotted sibling keys like `ns.a`), `redis` by non-blocking `SCAN` (not `KEYS`), `pg` by key/`LIKE` prefix; `null` no-ops. Namespace strings are treated as data, not glob/path input — see the `pick-cache-driver` topic for the file-path-containment and redis-glob-escaping details.
@@ -71,10 +71,8 @@ options: {
 ```ts
 const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
 
-await feed.swr(
-  "home",
-  { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] },
-  () => buildHomeFeed(userId),
+await feed.swr("home", { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] }, () =>
+  buildHomeFeed(userId),
 );
 // stored at feed.<userId>.home, tagged [user.<userId>, computed]
 ```

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

@@ -24,21 +24,21 @@ const hits = await cache.similar<T>(queryVec, {
 
 ## Capability matrix
 
-| Driver | `similar()` |
-|---|---|
+| Driver                              | `similar()`                                        |
+| ----------------------------------- | -------------------------------------------------- |
 | `memory` / `memoryExtended` / `lru` | ✅ Brute force (O(N)) — dev only past ~10k entries |
-| `pg` *with* `options.pg.vector` | ✅ pgvector + HNSW/IVFFlat index |
-| `pg` *without* `options.pg.vector` | ❌ Throws `CacheUnsupportedError` |
-| `redis` | ❌ Throws (RediSearch on backlog) |
-| `file` | ❌ Throws |
-| `null` | Returns `[]` |
+| `pg` _with_ `options.pg.vector`     | ✅ pgvector + HNSW/IVFFlat index                   |
+| `pg` _without_ `options.pg.vector`  | ❌ Throws `CacheUnsupportedError`                  |
+| `redis`                             | ❌ Throws (RediSearch on backlog)                  |
+| `file`                              | ❌ Throws                                          |
+| `null`                              | Returns `[]`                                       |
 
 ## Always-true facts
 
 1. **Cache is embedding-agnostic.** Caller computes vectors. The cache stores and ranks; it doesn't call out to an embedder.
 2. **Only entries written with `set({ vector })` show up.** A plain `set` adds the entry as KV — invisible to `similar()`.
 3. **Score = cosine similarity** in `[0, 1]` for typical embedding spaces. The `pg` driver computes `1 - (embedding <=> $1::vector)` so the score matches the memory drivers.
-4. **Tag filter narrows the candidate pool *before* ranking** — union semantics (entry must carry at least one of the listed tags).
+4. **Tag filter narrows the candidate pool _before_ ranking** — union semantics (entry must carry at least one of the listed tags).
 5. **Dimension mismatch throws `CacheConfigurationError`** at both `set({ vector })` and `similar()` time. Don't switch embedders without re-indexing.
 6. **TTL + LRU eviction also drop the vector** — expired or evicted entries are invisible to `similar()`.
 
@@ -51,7 +51,7 @@ const queryVec = await embed(prompt);
 const hits = await cache.similar<Answer>(queryVec, { topK: 1, threshold: 0.92 });
 
 if (hits.length > 0) {
-  return hits[0].value;     // skip the LLM call
+  return hits[0].value; // skip the LLM call
 }
 
 const answer = await llm.complete(prompt);

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

@@ -12,7 +12,7 @@ Tags let you invalidate by a label rather than by enumerating every key. Use the
 ```ts
 // Inline — terser when you know the tags up front
 await cache.set("user:1:profile", profile, { tags: ["users", "tenant-42"] });
-await cache.set("user:1:prefs",   prefs,   { tags: ["users", "tenant-42"] });
+await cache.set("user:1:prefs", prefs, { tags: ["users", "tenant-42"] });
 
 // Fluent — useful when you already have a tagged handle
 const users = cache.tags(["users"]);
@@ -34,11 +34,11 @@ Multi-tag is **union** semantics: an entry is invalidated if it carries **at lea
 
 ## When to reach for tags vs namespaces
 
-| Use case | Reach for |
-| --- | --- |
-| The keys share a known prefix | `cache.removeNamespace("prefix")` (the `use-cache-namespace` topic) |
-| The keys are spread across prefixes, tied by entity | Tags |
-| Both apply | Tags — more flexible; cheap on most drivers |
+| Use case                                            | Reach for                                                           |
+| --------------------------------------------------- | ------------------------------------------------------------------- |
+| The keys share a known prefix                       | `cache.removeNamespace("prefix")` (the `use-cache-namespace` topic) |
+| The keys are spread across prefixes, tied by entity | Tags                                                                |
+| Both apply                                          | Tags — more flexible; cheap on most drivers                         |
 
 Namespaces are cheaper (no reverse index). Tags are more powerful (any key can carry any tag).
 
@@ -48,13 +48,13 @@ Subsequent `set("user:1", ...)` with **no** `tags` leaves previous associations
 
 ## Driver behavior
 
-| Driver | Tag invalidation |
-| --- | :-: |
-| `null` | noop |
+| Driver                              |                       Tag invalidation                       |
+| ----------------------------------- | :----------------------------------------------------------: |
+| `null`                              |                             noop                             |
 | `memory` / `memoryExtended` / `lru` | ✓ (separate index store; eviction and expiry never touch it) |
-| `file` | ✓ (serialized index) |
-| `redis` | ✓ (native SET inside the prefix) |
-| `pg` | ✓ (JSON-array merge on the index row) |
+| `file`                              |                     ✓ (serialized index)                     |
+| `redis`                             |               ✓ (native SET inside the prefix)               |
+| `pg`                                |            ✓ (JSON-array merge on the index row)             |
 
 The index uses driver primitives (`tagAdd` / `tagMembers` / `tagRemove`), so concurrent tagged writes never drop members. It stores un-prefixed keys, `invalidate()` deletes exactly the members it read, writes prune up to 20 dead members, and `remove()` / `pull()` detach the key. Tags are global across scopes. Across servers, use `redis` or `pg` so every server shares one index.
 
@@ -76,7 +76,7 @@ Tags re-apply on every successful refresh — see the `use-swr` topic.
 const getUser = cached(fn, { key: (id) => `user.${id}`, ttl: "1h", tags: ["users"] });
 const getPosts = cached(fn, { key: (u) => `posts.by.${u}`, ttl: "30m", tags: ["users", "posts"] });
 
-await cache.tags(["users"]).invalidate();   // drops both wrappers' caches
+await cache.tags(["users"]).invalidate(); // drops both wrappers' caches
 ```
 
 See the `use-cached-hof` topic.

package/skills/use-cache-update-merge/SKILL.md

@@ -24,7 +24,7 @@ await cache.update<UserState>("user:1:state", (current) => ({
 // Conditional update — return null to remove
 await cache.update<Session>("session:abc", (current) => {
   if (!current || current.expired) {
-    return null;          // removes the key
+    return null; // removes the key
   }
   return { ...current, extendedAt: Date.now() };
 });
@@ -67,18 +67,18 @@ await Promise.all(
   ),
 );
 
-await cache.get("counter");   // 10 — not a lost-update
+await cache.get("counter"); // 10 — not a lost-update
 ```
 
 The per-key lock map lives on the driver instance and is cleared after each chain link finishes. No leak.
 
 ## When to reach for what
 
-| Task | Use |
-| --- | --- |
-| "Add 1 to this counter" | `increment()` (Redis-atomic via `INCRBY`; in-process elsewhere) |
-| "Change one field on a cached object" | `merge()` |
-| "Read-decide-maybe-write, possibly remove" | `update()` |
-| "Only set if missing" | `set(k, v, { onConflict: "create" })` |
-| "Only set if already exists" | `set(k, v, { onConflict: "update" })` |
-| "Read-then-delete atomically" | `pull()` |
+| Task                                       | Use                                                             |
+| ------------------------------------------ | --------------------------------------------------------------- |
+| "Add 1 to this counter"                    | `increment()` (Redis-atomic via `INCRBY`; in-process elsewhere) |
+| "Change one field on a cached object"      | `merge()`                                                       |
+| "Read-decide-maybe-write, possibly remove" | `update()`                                                      |
+| "Only set if missing"                      | `set(k, v, { onConflict: "create" })`                           |
+| "Only set if already exists"               | `set(k, v, { onConflict: "update" })`                           |
+| "Read-then-delete atomically"              | `pull()`                                                        |

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

@@ -15,17 +15,17 @@ driver or do cache-adjacent work outside the manager.
 ```ts
 import { parseTtl, expiresAtToTtl, resolveTtl } from "@warlock.js/cache";
 
-parseTtl(3600);        // 3600
-parseTtl("1h");        // 3600  (duration string via `ms`)
-parseTtl(Infinity);    // Infinity (no expiry)
-parseTtl(-5);          // throws CacheConfigurationError
+parseTtl(3600); // 3600
+parseTtl("1h"); // 3600  (duration string via `ms`)
+parseTtl(Infinity); // Infinity (no expiry)
+parseTtl(-5); // throws CacheConfigurationError
 
 expiresAtToTtl(new Date(Date.now() + 60_000)); // ~60 (absolute → relative seconds)
-expiresAtToTtl(Date.now() - 1000);             // throws — deadline in the past
+expiresAtToTtl(Date.now() - 1000); // throws — deadline in the past
 
 // caller ttl > expiresAt > fallback; ttl+expiresAt together throws
-resolveTtl("1h", undefined, Infinity);         // 3600
-resolveTtl(undefined, undefined, 1800);        // 1800 (fallback)
+resolveTtl("1h", undefined, Infinity); // 3600
+resolveTtl(undefined, undefined, 1800); // 1800 (fallback)
 ```
 
 ## Option normalizers
@@ -36,10 +36,10 @@ Coerce the polymorphic 2nd/3rd argument of `set`/`remember` into a uniform shape
 ```ts
 import { normalizeToOptions, normalizeToRememberOptions } from "@warlock.js/cache";
 
-normalizeToOptions(60);                 // { ttl: 60 }
-normalizeToOptions("1h");               // { ttl: "1h" }
-normalizeToOptions({ tags: ["x"] });    // returned as-is
-normalizeToRememberOptions("1h");       // { ttl: "1h" }   (no expiresAt/onConflict)
+normalizeToOptions(60); // { ttl: 60 }
+normalizeToOptions("1h"); // { ttl: "1h" }
+normalizeToOptions({ tags: ["x"] }); // returned as-is
+normalizeToRememberOptions("1h"); // { ttl: "1h" }   (no expiresAt/onConflict)
 ```
 
 ## Key + tag helpers
@@ -47,14 +47,14 @@ normalizeToRememberOptions("1h");       // { ttl: "1h" }   (no expiresAt/onConfl
 ```ts
 import { parseCacheKey, mergeTagSets, injectTags } from "@warlock.js/cache";
 
-parseCacheKey("users:1");                       // "users.1"
-parseCacheKey({ page: 1, q: "John" });          // "page.1.q.John"
+parseCacheKey("users:1"); // "users.1"
+parseCacheKey({ page: 1, q: "John" }); // "page.1.q.John"
 parseCacheKey("user:1", { globalPrefix: "app" }); // "app.user.1"
 
-mergeTagSets(["a", "b"], ["b", "c"]);           // ["a","b","c"] (deduped union)
-mergeTagSets(undefined, undefined);             // undefined
+mergeTagSets(["a", "b"], ["b", "c"]); // ["a","b","c"] (deduped union)
+mergeTagSets(undefined, undefined); // undefined
 
-injectTags({ ttl: "1h" }, ["unread"]);          // { ttl: "1h", tags: ["unread"] } (pure, no mutation)
+injectTags({ ttl: "1h" }, ["unread"]); // { ttl: "1h", tags: ["unread"] } (pure, no mutation)
 ```
 
 ## Vector scoring
@@ -64,7 +64,7 @@ import { cosineSimilarity } from "@warlock.js/cache";
 
 cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
 cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
-cosineSimilarity([1, 2, 3], [1, 2]);    // throws — dimension mismatch
+cosineSimilarity([1, 2, 3], [1, 2]); // throws — dimension mismatch
 ```
 
 Powers the brute-force `cache.similar()` on the memory drivers — reach for it

package/skills/use-cached-hof/SKILL.md

@@ -10,6 +10,7 @@ description: 'Wrap an async function with cached(fn, options) — declare the ca
 ## When to use
 
 Reach for `cached()` instead of `cache.remember()` when:
+
 - You have a function you'll call from many places.
 - You want the caching strategy declared once, not repeated at every call site.
 - You want `.invalidate()` available without manually deriving keys.
@@ -38,11 +39,11 @@ cached(fn, {
 
 ## Auto-key rules (shorthand only)
 
-| Args | Key |
-|------|-----|
-| None | `prefix` |
-| Any args | `prefix.<16 hex>` — sha1 of a stable JSON encoding of the args, truncated |
-| `Map` / `Set` / function / symbol / class instance / circular | throws `CacheConfigurationError` |
+| Args                                                          | Key                                                                       |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| None                                                          | `prefix`                                                                  |
+| Any args                                                      | `prefix.<16 hex>` — sha1 of a stable JSON encoding of the args, truncated |
+| `Map` / `Set` / function / symbol / class instance / circular | throws `CacheConfigurationError`                                          |
 
 The hash keeps distinct args on distinct keys (`("1.private", "")` ≠ `("1", "private")`). Object keys are sorted; `Date` → ISO string; order of args matters. Never build keys by hand: call `.invalidate(...args)`, which honours `config.driver`. When auto-key fails, use the options form with a custom `key` fn.
 
@@ -76,7 +77,7 @@ await getUser.invalidate(42);
 const getUser = cached(fn, { key: (id) => `user.${id}`, ttl: "1h", tags: ["users"] });
 const getPosts = cached(fn, { key: (u) => `posts.by.${u}`, ttl: "30m", tags: ["users", "posts"] });
 
-await cache.tags(["users"]).invalidate();   // drops both wrappers' caches
+await cache.tags(["users"]).invalidate(); // drops both wrappers' caches
 ```
 
 See the `use-cache-tags` topic.
@@ -86,7 +87,7 @@ See the `use-cache-tags` topic.
 ```ts
 const getCategoryMeta = cached(
   (filters: Filters) => db.categories.meta(filters.category),
-  { key: (f) => `category.meta.${f.category}`, ttl: "1h" },   // ignores `sort`, `page`
+  { key: (f) => `category.meta.${f.category}`, ttl: "1h" }, // ignores `sort`, `page`
 );
 ```
 

package/skills/use-swr/SKILL.md

@@ -24,11 +24,11 @@ Use `cache.remember()` when freshness is non-negotiable — auth, balances, bill
      │  no upstream call  │  bg refresh        │  like a miss
 ```
 
-| Window | Behavior |
-|---|---|
-| `now < freshTtl` | Return cached. No upstream call. |
+| Window                      | Behavior                                                                                 |
+| --------------------------- | ---------------------------------------------------------------------------------------- |
+| `now < freshTtl`            | Return cached. No upstream call.                                                         |
 | `freshTtl ≤ now < staleTtl` | Return cached immediately. Run `fn()` in background; next read sees the refreshed value. |
-| `now ≥ staleTtl` | Block on `fn()`. Same as `remember()`. |
+| `now ≥ staleTtl`            | Block on `fn()`. Same as `remember()`.                                                   |
 
 ## API
 
@@ -57,12 +57,12 @@ await cache.swr(
 
 ## Driver support
 
-| Driver | Background refresh |
-|---|---|
-| memory / memoryExtended / lru / file / mock | ✅ Full |
-| redis | ✅ Full (sidecar key for staleAt — backwards-compatible) |
-| pg | ✅ Full (`stale_at TIMESTAMPTZ` column — provision via `driver.schema()`) |
-| null | ❌ Always-fetch (null caches nothing) |
+| Driver                                      | Background refresh                                                        |
+| ------------------------------------------- | ------------------------------------------------------------------------- |
+| memory / memoryExtended / lru / file / mock | ✅ Full                                                                   |
+| redis                                       | ✅ Full (sidecar key for staleAt — backwards-compatible)                  |
+| pg                                          | ✅ Full (`stale_at TIMESTAMPTZ` column — provision via `driver.schema()`) |
+| null                                        | ❌ Always-fetch (null caches nothing)                                     |
 
 ## Common shapes
 
@@ -78,9 +78,7 @@ await cache.swr(`dashboard.${tenantId}`, { freshTtl: "5m", staleTtl: "1h" }, ()
 );
 
 // Third-party API — degrade gracefully when upstream is down
-await cache.swr("exchange.rates", { freshTtl: "10m", staleTtl: "24h" }, () =>
-  fetchFromForexAPI(),
-);
+await cache.swr("exchange.rates", { freshTtl: "10m", staleTtl: "24h" }, () => fetchFromForexAPI());
 ```
 
 ## Through scoped caches
@@ -88,10 +86,8 @@ await cache.swr("exchange.rates", { freshTtl: "10m", staleTtl: "24h" }, () =>
 ```ts
 const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
 
-await feed.swr(
-  "home",
-  { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] },
-  () => buildHomeFeed(userId),
+await feed.swr("home", { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] }, () =>
+  buildHomeFeed(userId),
 );
 // stored at feed.<userId>.home, tagged [user.<userId>, computed]
 ```
@@ -99,6 +95,6 @@ await feed.swr(
 ## Things NOT to do
 
 - Don't use SWR when the user must see the latest data (auth, billing). Use `remember()` instead — block-until-fresh is the right semantic there.
-- Don't pick `freshTtl` to be the *same* as `staleTtl` thinking it disables the stale window — that throws. Pick a tight `freshTtl` and wider `staleTtl` that reflects how stale your product can tolerate being.
+- Don't pick `freshTtl` to be the _same_ as `staleTtl` thinking it disables the stale window — that throws. Pick a tight `freshTtl` and wider `staleTtl` that reflects how stale your product can tolerate being.
 - Don't ignore `error` events. A persistent stream of refresh failures means upstream is broken and the cache is masking it.
 - Don't reach for SWR on the null driver — it caches nothing, so SWR always blocks.