@warlock.js/cache 5.19.0 → 5.20.0

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

@@ -1,57 +1,57 @@
----
-name: use-cache-bulk
-description: "Bulk operations — cache.many / cache.setMany in @warlock.js/cache; use when you need to use cache bulk."
----
-
-# Bulk operations — `cache.many` / `cache.setMany`
-
-Read or write a batch of keys in one call instead of awaiting them one at a time.
-
-## Read many — `many(keys)`
-
-```ts
-import { cache } from "@warlock.js/cache";
-
-const [alice, bob, carol] = await cache.many(["user.1", "user.2", "user.3"]);
-```
-
-- Returns an array **positionally aligned** with `keys`.
-- Missing keys come back as `null` (same as `get`), so the result length always
-  equals the input length — zip them back together by index.
-
-```ts
-const ids = [1, 2, 3];
-const users = await cache.many(ids.map((id) => `user.${id}`));
-
-const missingIds = ids.filter((_, index) => users[index] === null);
-// fetch only the misses from the origin…
-```
-
-## Write many — `setMany(items, ttl?)`
-
-```ts
-await cache.setMany({
-  "user.1": alice,
-  "user.2": bob,
-  "user.3": carol,
-}, 3600); // optional TTL (seconds) applied to every entry
-```
-
-- Keys are the object keys; values are the object values.
-- The optional second arg is a single TTL (seconds) applied to **all** entries —
-  there's no per-entry TTL or `tags` knob here. When you need tags or mixed TTLs,
-  loop with [`cache.set`](@warlock.js/cache/configure-set-options/SKILL.md) and
-  the rich options object instead.
-
-## Performance note
-
-On every driver these run their underlying `get`/`set` calls **concurrently**
-(`Promise.all`) on the shared connection; on the memory family it's effectively
-instant. There's no partial-failure handling — if one write rejects, the
-returned promise rejects.
-
-## See also
-
-- [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — single-key `get` / `set` / `remember`
-- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — per-entry TTL, tags, conflict policy
-- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — invalidate a batch by tag
+---
+name: use-cache-bulk
+description: 'Bulk reads/writes via cache.many(keys[]) → values[] (nulls for misses, order preserved) and cache.setMany(record, ttl?) → void. Triggers: `cache.many`, `cache.setMany`, "get multiple keys at once", "batch read cache", "warm the cache", "preload many keys", "mget", "mset"; typical import `import { cache } from "@warlock.js/cache"`. Skip: tag-based bulk invalidation — `@warlock.js/cache/use-cache-tags/SKILL.md`; single-key ops — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `ioredis` `MGET`/`MSET`.'
+---
+
+# Bulk operations — `cache.many` / `cache.setMany`
+
+Read or write a batch of keys in one call instead of awaiting them one at a time.
+
+## Read many — `many(keys)`
+
+```ts
+import { cache } from "@warlock.js/cache";
+
+const [alice, bob, carol] = await cache.many(["user.1", "user.2", "user.3"]);
+```
+
+- Returns an array **positionally aligned** with `keys`.
+- Missing keys come back as `null` (same as `get`), so the result length always
+  equals the input length — zip them back together by index.
+
+```ts
+const ids = [1, 2, 3];
+const users = await cache.many(ids.map((id) => `user.${id}`));
+
+const missingIds = ids.filter((_, index) => users[index] === null);
+// fetch only the misses from the origin…
+```
+
+## Write many — `setMany(items, ttl?)`
+
+```ts
+await cache.setMany({
+  "user.1": alice,
+  "user.2": bob,
+  "user.3": carol,
+}, 3600); // optional TTL (seconds) applied to every entry
+```
+
+- Keys are the object keys; values are the object values.
+- The optional second arg is a single TTL (seconds) applied to **all** entries —
+  there's no per-entry TTL or `tags` knob here. When you need tags or mixed TTLs,
+  loop with [`cache.set`](@warlock.js/cache/configure-set-options/SKILL.md) and
+  the rich options object instead.
+
+## Performance note
+
+On every driver these run their underlying `get`/`set` calls **concurrently**
+(`Promise.all`) on the shared connection; on the memory family it's effectively
+instant. There's no partial-failure handling — if one write rejects, the
+returned promise rejects.
+
+## See also
+
+- [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — single-key `get` / `set` / `remember`
+- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — per-entry TTL, tags, conflict policy
+- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — invalidate a batch by tag

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

@@ -1,85 +1,85 @@
----
-name: use-cache-list
-description: "Lists — the cache.list<T>(key) sub-API in @warlock.js/cache; use when you need to use cache list."
----
-
-# Lists — the `cache.list<T>(key)` sub-API
-
-Dedicated accessor for ordered collections — queues, recent-N buffers, sliding windows. Keeps the flat `CacheDriver` contract lean while giving list-shaped data a typed, purpose-built surface.
-
-## Shape
-
-```ts
-const recent = cache.list<Event>("recent-events");
-
-await recent.push(event);                    // append to tail — returns new length
-await recent.unshift(priorityEvent);          // prepend to head — returns new length
-const tail = await recent.pop();              // remove + return tail
-const head = await recent.shift();            // remove + return head
-const first10 = await recent.slice(0, 10);    // view — does not mutate
-const all = await recent.all();
-const count = await recent.length();
-await recent.trim(0, 99);                     // keep only indices 0..99 inclusive
-await recent.clear();
-```
-
-## Type safety
-
-The generic flows through every method. Pass the element type at the accessor call, not on each method:
-
-```ts
-type Event = { type: string; at: number };
-const queue = cache.list<Event>("jobs:queue");
-
-await queue.push({ type: "import", at: Date.now() });   // ✓
-await queue.push("not an event" as never);              // ✗ at the caller
-```
-
-## Current performance characteristics
-
-The default implementation (used by memory, memoryExtended, LRU, file, **and redis today**) stores the entire list as a single cache entry and does read-mutate-write on every op. Correct for every driver, O(n) per op.
-
-Redis-native `LPUSH` / `RPUSH` / `LRANGE` / `LTRIM` is planned for v2.1 (see `domains/cache/backlog.md`). Until then, treat Redis list ops as O(n) and avoid very large lists on Redis.
-
-## Concurrency warning
-
-List writes on memory / file / LRU drivers **race** when two callers push simultaneously — the default read-mutate-write loop has no lock. If you need safe concurrent list writes today, wrap pushes in a distributed-lock pattern (see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md)) or use a single writer.
-
-Single-process memory with a single writer (typical test / script usage) is fine.
-
-## Empty-list cleanup
-
-When a list becomes empty (e.g. after successive `pop()` / `shift()` / `trim(0, -1)`), the backing cache entry is **removed** — `cache.get(key)` returns `null`, not `[]`. This keeps the store from accumulating empty list entries.
-
-```ts
-await recent.push("a");
-await recent.pop();
-await cache.get("recent-events");   // null, not []
-```
-
-## Typical recipes
-
-```ts
-// Recent-N audit log
-const audit = cache.list<AuditEntry>("audit:recent");
-await audit.unshift(entry);          // newest at head
-await audit.trim(0, 999);             // keep most-recent 1000
-
-// Lightweight job queue (single-node)
-const queue = cache.list<Job>("jobs:pending");
-await queue.push(job);
-const next = await queue.shift();     // FIFO
-
-// Stack
-const stack = cache.list<Frame>("stack");
-await stack.push(frame);
-const top = await stack.pop();        // LIFO
-```
-
-## What lists are NOT for
-
-- Unordered uniqueness — no native set today; use a plain object/Map in memory, or roll your own via `cache.get/set`.
-- Hash / field maps — same; use individual keys with a shared prefix.
-- Ordered top-N with scoring — no sorted-set analog today.
-
-These are tracked as candidates for v3.
+---
+name: use-cache-list
+description: 'Ordered collections via cache.list<T>(key) — push / unshift / pop / shift / slice / all / length / trim / clear. Triggers: `cache.list`, `push`, `unshift`, `pop`, `shift`, `slice`, `trim`, `clear`; "job queue in cache", "keep most recent N events", "audit log buffer", "FIFO queue"; typical import `import { cache } from "@warlock.js/cache"`. Skip: locking around list writes — `@warlock.js/cache/use-cache-lock/SKILL.md`; competing libs `bullmq`, `bee-queue`, `bull`, `ioredis` `LPUSH`; native `Array.push`.'
+---
+
+# Lists — the `cache.list<T>(key)` sub-API
+
+Dedicated accessor for ordered collections — queues, recent-N buffers, sliding windows. Keeps the flat `CacheDriver` contract lean while giving list-shaped data a typed, purpose-built surface.
+
+## Shape
+
+```ts
+const recent = cache.list<Event>("recent-events");
+
+await recent.push(event);                    // append to tail — returns new length
+await recent.unshift(priorityEvent);          // prepend to head — returns new length
+const tail = await recent.pop();              // remove + return tail
+const head = await recent.shift();            // remove + return head
+const first10 = await recent.slice(0, 10);    // view — does not mutate
+const all = await recent.all();
+const count = await recent.length();
+await recent.trim(0, 99);                     // keep only indices 0..99 inclusive
+await recent.clear();
+```
+
+## Type safety
+
+The generic flows through every method. Pass the element type at the accessor call, not on each method:
+
+```ts
+type Event = { type: string; at: number };
+const queue = cache.list<Event>("jobs:queue");
+
+await queue.push({ type: "import", at: Date.now() });   // ✓
+await queue.push("not an event" as never);              // ✗ at the caller
+```
+
+## Current performance characteristics
+
+The default implementation (used by memory, memoryExtended, LRU, file, **and redis today**) stores the entire list as a single cache entry and does read-mutate-write on every op. Correct for every driver, O(n) per op.
+
+Redis-native `LPUSH` / `RPUSH` / `LRANGE` / `LTRIM` is planned for v2.1 (see `domains/cache/backlog.md`). Until then, treat Redis list ops as O(n) and avoid very large lists on Redis.
+
+## Concurrency warning
+
+List writes on memory / file / LRU drivers **race** when two callers push simultaneously — the default read-mutate-write loop has no lock. If you need safe concurrent list writes today, wrap pushes in a distributed-lock pattern (see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md)) or use a single writer.
+
+Single-process memory with a single writer (typical test / script usage) is fine.
+
+## Empty-list cleanup
+
+When a list becomes empty (e.g. after successive `pop()` / `shift()` / `trim(0, -1)`), the backing cache entry is **removed** — `cache.get(key)` returns `null`, not `[]`. This keeps the store from accumulating empty list entries.
+
+```ts
+await recent.push("a");
+await recent.pop();
+await cache.get("recent-events");   // null, not []
+```
+
+## Typical recipes
+
+```ts
+// Recent-N audit log
+const audit = cache.list<AuditEntry>("audit:recent");
+await audit.unshift(entry);          // newest at head
+await audit.trim(0, 999);             // keep most-recent 1000
+
+// Lightweight job queue (single-node)
+const queue = cache.list<Job>("jobs:pending");
+await queue.push(job);
+const next = await queue.shift();     // FIFO
+
+// Stack
+const stack = cache.list<Frame>("stack");
+await stack.push(frame);
+const top = await stack.pop();        // LIFO
+```
+
+## What lists are NOT for
+
+- Unordered uniqueness — no native set today; use a plain object/Map in memory, or roll your own via `cache.get/set`.
+- Hash / field maps — same; use individual keys with a shared prefix.
+- Ordered top-N with scoring — no sorted-set analog today.
+
+These are tracked as candidates for v3.

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

@@ -1,104 +1,113 @@
----
-name: use-cache-lock
-description: "cache.lock() — distributed locks with auto-release in @warlock.js/cache; use when you need to use cache lock."
----
-
-# `cache.lock()` — distributed locks with auto-release
-
-`cache.lock(key, ttl, fn)` acquires a distributed lock, runs `fn`, and auto-releases (even on throw). Built on `set({ onConflict: "create" })` — Redis-native where available, emulated elsewhere.
-
-## When to use
-
-- A task should run on only **one server at a time** (cron jobs, imports, migrations).
-- Idempotent webhook or payment processing — dedup across retries.
-- Any time you'd otherwise write `try { … } finally { cache.remove(lockKey); }`.
-
-**Not for memoization** — use [`cached()`](@warlock.js/cache/use-cached-hof/SKILL.md) or `cache.remember()`.
-
-## Shape
-
-```ts
-// Primary — positional TTL
-await cache.lock(key, ttl, fn);
-
-// With options — owner for debugging, per-call driver override
-await cache.lock(key, { ttl, owner?, driver? }, fn);
-```
-
-**TTL is required.** Forgotten locks stay forever if the process crashes; the TTL is your safety net.
-
-## Return shape — discriminated union
-
-```ts
-type LockOutcome<T> =
-  | { acquired: true; value: T }
-  | { acquired: false };
-```
-
-Unambiguous even when `fn` returns `undefined`. Narrow with TS:
-
-```ts
-const outcome = await cache.lock("lock.x", "1m", async () => compute());
-
-if (outcome.acquired) {
-  console.log(outcome.value);   // typed
-} else {
-  console.log("someone else is running");
-}
-```
-
-## Recipes
-
-### Cron on only one server
-
-```ts
-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),
-  );
-
-  if (!outcome.acquired) {
-    return res.status(200).json({ status: "already-processed" });
-  }
-
-  res.status(200).json({ status: "processed" });
-});
-```
-
-### Batch job with debug-friendly owner
-
-```ts
-await cache.lock(
-  `lock.report.${date}`,
-  { ttl: "1h", owner: `worker.${process.env.HOSTNAME}` },
-  () => generateReport(date),
-);
-```
-
-`await cache.get("lock.report.2026-04-24")` reveals which worker holds the lock.
-
-## Driver behavior
-
-| Driver | Cross-process safe? |
-|--------|:-:|
-| `redis` | ✅ Native `SET … NX EX` |
-| `memory` / `memoryExtended` / `lru` | ❌ In-process only |
-| `file` | ⚠️ Single-host only (races across hosts) |
-| `null` | n/a — always "acquires" |
-
-## Gotchas
-
-- **Non-re-entrant in v1.** A recursive call for the same key gets `{ acquired: false }`.
-- **Don't release inside `fn`.** `lock()` handles release in `finally`. Manual `cache.remove(lockKey)` inside `fn` would let another process jump in mid-work.
-- **TTL shorter than `fn` runtime = race.** Pick a TTL with generous margin.
-- **Cross-server requires Redis.** Memory / LRU drivers don't coordinate across processes.
+---
+name: use-cache-lock
+description: 'Distributed lock via cache.lock(key, ttl, fn) — acquire, run fn, auto-release. Returns {acquired: true, value} or {acquired: false}. Triggers: `cache.lock`, `LockOutcome`, `acquired`, `owner`; "run cron on only one server", "idempotent webhook handler", "dedup payment processing", "lock a task across nodes"; typical import `import { cache } from "@warlock.js/cache"`. Skip: raw `onConflict: "create"` recipe — `@warlock.js/cache/apply-cache-patterns/SKILL.md`; memoization — `@warlock.js/cache/use-cached-hof/SKILL.md`; competing libs `redlock`, `async-mutex`, `proper-lockfile`.'
+---
+
+# `cache.lock()` — distributed locks with auto-release
+
+`cache.lock(key, ttl, fn)` acquires a distributed lock, runs `fn`, and auto-releases (even on throw). Built on `set({ onConflict: "create" })` — Redis-native where available, emulated elsewhere.
+
+## When to use
+
+- A task should run on only **one server at a time** (cron jobs, imports, migrations).
+- Idempotent webhook or payment processing — dedup across retries.
+- Any time you'd otherwise write `try { … } finally { cache.remove(lockKey); }`.
+
+**Not for memoization** — use [`cached()`](@warlock.js/cache/use-cached-hof/SKILL.md) or `cache.remember()`.
+
+## Shape
+
+```ts
+// Primary — positional TTL
+await cache.lock(key, ttl, fn);
+
+// With options — owner for debugging, per-call driver override
+await cache.lock(key, { ttl, owner?, driver? }, fn);
+```
+
+**TTL is required, finite and positive.** `0`, `Infinity`, negative, `NaN` and unparseable TTLs throw `CacheConfigurationError` before anything is written. A lock with no expiry blocks every server once its holder crashes.
+
+TTL rules: a number or a bare numeric string (`"90"`) is **seconds**; `"500ms"` and `0.5` round up to 1 s. There is no renewal or fencing, so the TTL must exceed the worst-case duration of `fn`.
+
+## Lock value and release
+
+- The stored value is `<owner>#<token>` (owner defaults to `pid.<pid>`; the token is random per acquisition). Match on the `<owner>#` prefix, never the bare owner.
+- Release is a compare-and-delete (atomic on memory, redis, pg): if your TTL expired and a successor acquired the key, your release leaves their lock alone.
+- A release error is logged and never replaces `fn`'s result or error.
+
+## Return shape — discriminated union
+
+```ts
+type LockOutcome<T> =
+  | { acquired: true; value: T }
+  | { acquired: false };
+```
+
+Unambiguous even when `fn` returns `undefined`. Narrow with TS:
+
+```ts
+const outcome = await cache.lock("lock.x", "1m", async () => compute());
+
+if (outcome.acquired) {
+  console.log(outcome.value);   // typed
+} else {
+  console.log("someone else is running");
+}
+```
+
+## Recipes
+
+### Cron on only one server
+
+```ts
+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),
+  );
+
+  if (!outcome.acquired) {
+    return res.status(200).json({ status: "already-processed" });
+  }
+
+  res.status(200).json({ status: "processed" });
+});
+```
+
+### Batch job with debug-friendly owner
+
+```ts
+await cache.lock(
+  `lock.report.${date}`,
+  { ttl: "1h", owner: `worker.${process.env.HOSTNAME}` },
+  () => generateReport(date),
+);
+```
+
+`await cache.get("lock.report.2026-04-24")` reveals which worker holds the lock.
+
+## Driver behavior
+
+| 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" |
+
+## Gotchas
+
+- **Non-re-entrant in v1.** A recursive call for the same key gets `{ acquired: false }`.
+- **Don't release inside `fn`.** `lock()` handles release in `finally`. Manual `cache.remove(lockKey)` inside `fn` would let another process jump in mid-work.
+- **TTL shorter than `fn` runtime = race.** Pick a TTL with generous margin; there is no renewal.
+- **Cross-server requires `redis` or `pg`.** Memory / LRU / file drivers don't coordinate across servers.