@warlock.js/cache 5.29.0 → 5.31.0

package/llms.txt

@@ -15,7 +15,7 @@
 - [overview](@warlock.js/cache/overview/SKILL.md): @warlock.js/cache overview for orientation and choosing the focused skill for the task.
 - [pick-cache-driver](@warlock.js/cache/pick-cache-driver/SKILL.md): Pick a cache driver — null / memory / memoryExtended / lru / file / redis / pg / mock — and configure it. Triggers: `cache.setCacheConfigurations`, `BaseCacheDriver`, `cache.use`, `cache.load`, `cache.driver`, `globalPrefix`; "which cache driver should I use", "configure redis driver", "register custom cache driver", "multi-tenant scoping"; typical import `import { cache, BaseCacheDriver } from "@warlock.js/cache"`. Skip: cache CRUD — the `cache-basics` topic; pg setup — the `configure-pg-cache` topic; competing libs `lru-cache`, `node-cache`, `keyv`, `ioredis`; native `Map`.
 - [test-cache-code](@warlock.js/cache/test-cache-code/SKILL.md): Test code that touches cache — MockCacheDriver (behavioral assertions with wasCalled / callLog), MemoryCacheDriver (full-stack), NullCacheDriver (graceful-degradation). Triggers: `MockCacheDriver`, `MemoryCacheDriver`, `NullCacheDriver`, `wasCalled`, `callLog`, `getStored`, `reset`, `cache.on`; "assert cache was invalidated", "test code that uses cache.set", "mock cache in vitest", "test similarity without a real embedder", "stub the pg cache driver"; typical import `import { cache, MockCacheDriver, MemoryCacheDriver } from "@warlock.js/cache"`. Skip: real driver picks — the `pick-cache-driver` topic; competing libs `jest-mock`, `sinon`, `redis-mock`; native `vi.fn`.
-- [use-cache-atomic](@warlock.js/cache/use-cache-atomic/SKILL.md): Atomic counters via cache.increment(key, by=1) / cache.decrement(key, by=1) — returns the new number, throws on non-numeric values. Triggers: `cache.increment`, `cache.decrement`, "view counter", "page views", "atomic counter", "decrement stock", "rate-limit counter", "INCRBY"; typical import `import { cache } from "@warlock.js/cache"`. Skip: read-modify-write of objects — the `use-cache-update-merge` topic; named-lock coordination — the `use-cache-lock` topic; competing libs `ioredis` `INCR`, native counters in a `Map`.
+- [use-cache-atomic](@warlock.js/cache/use-cache-atomic/SKILL.md): Atomic counters via cache.increment(key, by=1, { ttl }?) / cache.decrement(key, by=1) — returns the new number, throws on non-numeric values. Triggers: `cache.increment`, `cache.decrement`, "view counter", "page views", "atomic counter", "decrement stock", "rate-limit counter", "INCRBY"; typical import `import { cache } from "@warlock.js/cache"`. Skip: read-modify-write of objects — the `use-cache-update-merge` topic; named-lock coordination — the `use-cache-lock` topic; competing libs `ioredis` `INCR`, native counters in a `Map`.
 - [use-cache-bulk](@warlock.js/cache/use-cache-bulk/SKILL.md): 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 — the `use-cache-tags` topic; single-key ops — the `cache-basics` topic; competing libs `ioredis` `MGET`/`MSET`.
 - [use-cache-list](@warlock.js/cache/use-cache-list/SKILL.md): 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 — the `use-cache-lock` topic; competing libs `bullmq`, `bee-queue`, `bull`, `ioredis` `LPUSH`; native `Array.push`.
 - [use-cache-lock](@warlock.js/cache/use-cache-lock/SKILL.md): 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 — the `apply-cache-patterns` topic; memoization — the `use-cached-hof` topic; competing libs `redlock`, `async-mutex`, `proper-lockfile`.

package/package.json

@@ -5,9 +5,9 @@
     "environment": "server"
   },
   "dependencies": {
-    "@warlock.js/fs": "5.29.0",
+    "@warlock.js/fs": "5.31.0",
     "@mongez/reinforcements": "^4.0.2",
-    "@warlock.js/logger": "5.29.0",
+    "@warlock.js/logger": "5.31.0",
     "ms": "^2.1.3"
   },
   "peerDependencies": {
@@ -24,7 +24,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/warlockjs/cache"
+    "url": "git+https://github.com/warlockjs/framework.git",
+    "directory": "packages/cache"
   },
   "keywords": [
     "nodejs",
@@ -46,7 +47,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.29.0",
+  "version": "5.31.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

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

@@ -11,7 +11,7 @@ Common shapes — the "general patterns" file. Specialized shapes live in their
 
 ```ts
 const user = await cache.remember(`user:${id}`, "1h", async () => {
-  return db.users.find(id);   // runs only on cache miss
+  return db.users.find(id); // runs only on cache miss
 });
 ```
 
@@ -81,8 +81,9 @@ await cache.set("user:1", user, "1h");
 ```
 
 Clear a tenant out:
+
 ```ts
-await cache.removeNamespace("");   // when globalPrefix is set, flush scopes to it
+await cache.removeNamespace(""); // when globalPrefix is set, flush scopes to it
 // or
 await cache.tags([`tenant-${tenantId}`]).invalidate();
 ```

package/skills/cache-basics/SKILL.md

@@ -61,20 +61,22 @@ cache.setCacheConfigurations(config);
 await cache.init();
 ```
 
+`logging` turns the per-operation key log (`<key> fetched`, `<key> not found`, ...) on or off. Email addresses inside logged keys are masked (`user.member@example.com` logs as `u***@example.com`), in operation lines and in error lines (which are written even with logging off); other personal data in a key is logged as is, so keep it out of keys or turn logging off in production.
+
 ## Primary ops
 
 ```ts
 // Set + get
 await cache.set("user.1", user, "1h");
-const cached = await cache.get<User>("user.1");       // User | null
+const cached = await cache.get<User>("user.1"); // User | null
 
 // Presence + read-and-delete
-const exists = await cache.has("user.1");             // boolean
-const taken = await cache.pull<User>("user.1");        // returns then removes
+const exists = await cache.has("user.1"); // boolean
+const taken = await cache.pull<User>("user.1"); // returns then removes
 
 // Remove + flush
 await cache.remove("user.1");
-await cache.flush();                                   // wipe everything (current driver)
+await cache.flush(); // wipe everything (current driver)
 
 // Many at once — array positionally aligned with the keys (null for misses)
 const [u1, u2, u3] = await cache.many(["user.1", "user.2", "user.3"]);
@@ -84,9 +86,9 @@ const [u1, u2, u3] = await cache.many(["user.1", "user.2", "user.3"]);
 await cache.forever("config.version", "1.2.3");
 
 // Counters
-await cache.increment("post.42.views");                // +1, returns new value
-await cache.increment("post.42.views", 10);            // +10
-await cache.decrement("inventory.sku-x");              // -1
+await cache.increment("post.42.views"); // +1, returns new value
+await cache.increment("post.42.views", 10); // +10
+await cache.decrement("inventory.sku-x"); // -1
 
 // Memoize an expensive function
 const user = await cache.remember("user.1", "1h", async () => db.users.find(1));
@@ -94,23 +96,23 @@ const user = await cache.remember("user.1", "1h", async () => db.users.find(1));
 
 ## Pick a skill
 
-| If the task is about… | Load |
-| --- | --- |
-| Choosing a driver, configuring it, or understanding what each one does best | The `pick-cache-driver` topic |
-| The `set` options object (`ttl`, `expiresAt`, `tags`, `onConflict`, `driver`, `vector`) | The `configure-set-options` topic |
-| Memoization with `remember()`, counters, negative caching, per-tenant scoping, TTL constants | The `apply-cache-patterns` topic |
-| Scoped handles via `cache.namespace(prefix, options?)` | The `use-cache-namespace` topic |
-| Tag-based invalidation — `cache.tags([...]).invalidate()` | The `use-cache-tags` topic |
-| Stale-while-revalidate — `cache.swr(...)` | The `use-swr` topic |
-| Wrapping a function with `cached()` — HOF memoization with `.invalidate()` | The `use-cached-hof` topic |
-| Distributed locks — `cache.lock(key, ttl, fn)` with auto-release | The `use-cache-lock` topic |
-| Queues, recent-N buffers, `push`/`shift`/`trim` — the list sub-API | The `use-cache-list` topic |
-| Atomic read-modify-write via `update()` and `merge()` | The `use-cache-update-merge` topic |
-| Similarity retrieval — `set({ vector })` + `cache.similar(...)` | The `use-cache-similarity` topic |
-| Postgres driver setup (KV-only or with pgvector) | The `configure-pg-cache` topic |
-| `cache.metrics()` aggregate snapshot + event bus for per-event reactions | The `observe-cache` topic |
-| Error classes (`CacheConfigurationError`, `CacheUnsupportedError`, etc.) | The `handle-cache-errors` topic |
-| Tests that touch cache code paths — `MockCacheDriver`, `MemoryCacheDriver` | The `test-cache-code` topic |
+| If the task is about…                                                                        | Load                               |
+| -------------------------------------------------------------------------------------------- | ---------------------------------- |
+| Choosing a driver, configuring it, or understanding what each one does best                  | The `pick-cache-driver` topic      |
+| The `set` options object (`ttl`, `expiresAt`, `tags`, `onConflict`, `driver`, `vector`)      | The `configure-set-options` topic  |
+| Memoization with `remember()`, counters, negative caching, per-tenant scoping, TTL constants | The `apply-cache-patterns` topic   |
+| Scoped handles via `cache.namespace(prefix, options?)`                                       | The `use-cache-namespace` topic    |
+| Tag-based invalidation — `cache.tags([...]).invalidate()`                                    | The `use-cache-tags` topic         |
+| Stale-while-revalidate — `cache.swr(...)`                                                    | The `use-swr` topic                |
+| Wrapping a function with `cached()` — HOF memoization with `.invalidate()`                   | The `use-cached-hof` topic         |
+| Distributed locks — `cache.lock(key, ttl, fn)` with auto-release                             | The `use-cache-lock` topic         |
+| Queues, recent-N buffers, `push`/`shift`/`trim` — the list sub-API                           | The `use-cache-list` topic         |
+| Atomic read-modify-write via `update()` and `merge()`                                        | The `use-cache-update-merge` topic |
+| Similarity retrieval — `set({ vector })` + `cache.similar(...)`                              | The `use-cache-similarity` topic   |
+| Postgres driver setup (KV-only or with pgvector)                                             | The `configure-pg-cache` topic     |
+| `cache.metrics()` aggregate snapshot + event bus for per-event reactions                     | The `observe-cache` topic          |
+| Error classes (`CacheConfigurationError`, `CacheUnsupportedError`, etc.)                     | The `handle-cache-errors` topic    |
+| Tests that touch cache code paths — `MockCacheDriver`, `MemoryCacheDriver`                   | The `test-cache-code` topic        |
 
 ## Things NOT to do
 

package/skills/configure-pg-cache/SKILL.md

@@ -39,8 +39,8 @@ cache.setCacheConfigurations({
   options: {
     pg: {
       client: pool,
-      table: "warlock_cache",     // optional, default
-      ttl: "1h",                  // optional default
+      table: "warlock_cache", // optional, default
+      ttl: "1h", // optional default
       globalPrefix: "prod-app",
     },
   },

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

@@ -14,7 +14,7 @@ description: 'Configure cache.set''s third argument — ttl, expiresAt, tags, on
 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"
+await cache.set("name", "Jane", "10m"); // "1s", "30m", "1h", "7d", "2 weeks"
 
 // 3. Options object
 await cache.set("user:1", user, {
@@ -28,14 +28,14 @@ await cache.set("user:1", user, {
 
 ## 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 the `use-cache-tags` topic. |
-| `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()` (see the `use-cache-similarity` topic). Drivers without similarity support throw `CacheUnsupportedError`. |
+| 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 the `use-cache-tags` topic.                                                                                    |
+| `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()` (see the `use-cache-similarity` topic). Drivers without similarity support throw `CacheUnsupportedError`. |
 
 ## TTL parsing
 
@@ -71,8 +71,8 @@ Conditional writes (`"create"` / `"update"`) return a `CacheSetResult`; uncondit
 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
+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(...)`
@@ -86,7 +86,7 @@ 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"
+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()`.
@@ -96,7 +96,7 @@ Inline tag semantics are **additive**, never replace. A subsequent `set("user:1"
 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); // 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

@@ -18,14 +18,14 @@ import {
 } 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. |
+| 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 the `pick-cache-driver` topic for the encoding contract. |
 
 ## Special case — `setNX` unsupported

package/skills/index.md

@@ -1,11 +1,13 @@
 ---
-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."
+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`.
@@ -14,6 +16,7 @@ The `cache` singleton (a `CacheManager`) fronts one active driver. Everything, f
 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.

package/skills/observe-cache/SKILL.md

@@ -50,15 +50,15 @@ Listeners attached via `cache.on(...)` survive driver switches the same way the
 
 ## 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", ...)` |
+| 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", ...)`                                                                           |
 | See which tag invalidations ran, what they removed and how long they took | `cache.on("invalidated", ({ tags, keys, durationMs }) => ...)` — once per `tags([...]).invalidate()` |
-| 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 |
+| 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.
 

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

@@ -7,30 +7,30 @@ description: 'Pick a cache driver — null / memory / memoryExtended / lru / fil
 
 Seven production drivers + a mock driver ship in-box. Pick by durability, scope, and workload.
 
-| Driver | Process scope | Persists on restart | Good for | Avoid when |
-| --- | --- | --- | --- | --- |
-| `null` | — | — | Disabling cache in tests; feature-flagging off | You actually want caching |
-| `memory` | Single process | No | Hot in-process data with default TTL; smallest latency | Multi-process / multi-node |
-| `memoryExtended` | Single process | No | Sliding-window TTL (TTL resets on every read) | Any multi-process deploy |
-| `lru` | Single process | No | Bounded in-memory caches (capacity-based eviction) | Need cross-process sharing |
-| `file` | Single host | Yes | Build artefacts, local dev persistence across restarts | Concurrency (no locks); multi-host |
-| `redis` | Shared | Yes (Redis-managed) | Anything shared across processes / nodes | Single-process-only workload — overkill |
-| `pg` | Shared | Yes (Postgres-managed) | You already run Postgres; semantic caching / RAG via pgvector | High-throughput hot reads (Redis is faster) |
+| Driver           | Process scope  | Persists on restart    | Good for                                                      | Avoid when                                  |
+| ---------------- | -------------- | ---------------------- | ------------------------------------------------------------- | ------------------------------------------- |
+| `null`           | —              | —                      | Disabling cache in tests; feature-flagging off                | You actually want caching                   |
+| `memory`         | Single process | No                     | Hot in-process data with default TTL; smallest latency        | Multi-process / multi-node                  |
+| `memoryExtended` | Single process | No                     | Sliding-window TTL (TTL resets on every read)                 | Any multi-process deploy                    |
+| `lru`            | Single process | No                     | Bounded in-memory caches (capacity-based eviction)            | Need cross-process sharing                  |
+| `file`           | Single host    | Yes                    | Build artefacts, local dev persistence across restarts        | Concurrency (no locks); multi-host          |
+| `redis`          | Shared         | Yes (Redis-managed)    | Anything shared across processes / nodes                      | Single-process-only workload — overkill     |
+| `pg`             | Shared         | Yes (Postgres-managed) | You already run Postgres; semantic caching / RAG via pgvector | High-throughput hot reads (Redis is faster) |
 
 ## Capability matrix
 
-| Capability | null | memory | memoryExt | lru | file | redis | pg |
-| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
-| `set` / `get` / `remove` / `flush` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| TTL (number or string; numeric strings = seconds) | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Sliding TTL on read | — | — | ✓ | — | — | — | — |
-| `removeNamespace` | noop | ✓ | ✓ | ✓ (prefix-scan) | ✓ | ✓ | ✓ (LIKE prefix) |
-| `onConflict: "create"` / `"update"` | noop | emulated | emulated | emulated | emulated | native `NX`/`XX` | native (INSERT ON CONFLICT) |
-| `increment` / `decrement` / `pull` | — | one process | one process | one process | one process | **cross-server** | **cross-server** |
-| `update()` / `merge()` | ✓ | one process | one process | one process | ✗ throws | **cross-server** (compare-and-set) | **cross-server** (compare-and-set) |
-| List sub-API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (O(n) JSON blob today; native LPUSH/LRANGE in v2.1) | ✓ |
-| Tagged invalidation | noop | ✓ | ✓ | ✓ | ✓ (serialized index) | ✓ (native SET) | ✓ (JSON-array merge) |
-| `similar()` / `set({ vector })` | returns `[]` / noop | ✓ brute force | ✓ brute force | ✓ brute force | ✗ throws | ✗ throws (Phase 2 backlog) | ✓ (with `vector` config — pgvector) |
+| Capability                                        |        null         |    memory     |   memoryExt   |       lru       |         file         |                         redis                         |                 pg                  |
+| ------------------------------------------------- | :-----------------: | :-----------: | :-----------: | :-------------: | :------------------: | :---------------------------------------------------: | :---------------------------------: |
+| `set` / `get` / `remove` / `flush`                |          ✓          |       ✓       |       ✓       |        ✓        |          ✓           |                           ✓                           |                  ✓                  |
+| TTL (number or string; numeric strings = seconds) |          —          |       ✓       |       ✓       |        ✓        |          ✓           |                           ✓                           |                  ✓                  |
+| Sliding TTL on read                               |          —          |       —       |       ✓       |        —        |          —           |                           —                           |                  —                  |
+| `removeNamespace`                                 |        noop         |       ✓       |       ✓       | ✓ (prefix-scan) |          ✓           |                           ✓                           |           ✓ (LIKE prefix)           |
+| `onConflict: "create"` / `"update"`               |        noop         |   emulated    |   emulated    |    emulated     |       emulated       |                   native `NX`/`XX`                    |     native (INSERT ON CONFLICT)     |
+| `increment` / `decrement` / `pull`                |          —          |  one process  |  one process  |   one process   |     one process      |                   **cross-server**                    |          **cross-server**           |
+| `update()` / `merge()`                            |          ✓          |  one process  |  one process  |   one process   |       ✗ throws       |          **cross-server** (compare-and-set)           | **cross-server** (compare-and-set)  |
+| List sub-API                                      |          ✓          |       ✓       |       ✓       |        ✓        |          ✓           | ✓ (O(n) JSON blob today; native LPUSH/LRANGE in v2.1) |                  ✓                  |
+| Tagged invalidation                               |        noop         |       ✓       |       ✓       |        ✓        | ✓ (serialized index) |                    ✓ (native SET)                     |        ✓ (JSON-array merge)         |
+| `similar()` / `set({ vector })`                   | returns `[]` / noop | ✓ brute force | ✓ brute force |  ✓ brute force  |       ✗ throws       |              ✗ throws (Phase 2 backlog)               | ✓ (with `vector` config — pgvector) |
 
 ## Multi-server: use redis or pg
 
@@ -102,13 +102,14 @@ const pool = new Pool({ connectionString: process.env.DATABASE_URL });
 cache.setCacheConfigurations({
   default: "pg",
   drivers: { pg: PgCacheDriver },
-  options: { pg: { table: "cache" } },        // static
+  options: { pg: { table: "cache" } }, // static
 });
 
-await cache.use("pg", { client: pool });       // runtime — skip init() in this case
+await cache.use("pg", { client: pool }); // runtime — skip init() in this case
 ```
 
 Constraints:
+
 - The driver name must be registered in `setCacheConfigurations({ drivers })` — runtime options don't bypass registration.
 - Once a driver is loaded, calling `use`/`load`/`driver` again with **non-empty** new options throws `CacheConfigurationError`. Register a second driver name if you need a different config.
 - Calling without options (or with `{}`) on an already-loaded driver returns the cached instance silently.

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

@@ -63,7 +63,7 @@ When you want the real read/write semantics (eviction, TTL expiry, similarity sc
 
 `MockCacheDriver` does NOT implement `similar()` — vector writes are recorded into the call log but nearest-neighbor scoring is not available. Tests that call `cache.similar(...)` should use the memory driver.
 
-## Strategy 3 — `NullCacheDriver` when you need cache *off*
+## Strategy 3 — `NullCacheDriver` when you need cache _off_
 
 Use `NullCacheDriver` to disable caching entirely for code paths that should still work without a cache (graceful-degradation tests):
 
@@ -88,7 +88,9 @@ import { vi } from "vitest";
 class FakeRedisClient {
   public store = new Map<string, string>();
   private expires = new Map<string, number>();
-  public on() { return this; }
+  public on() {
+    return this;
+  }
   public async connect() {}
   public async quit() {}
   public async set(key: string, value: string, opts?: { EX?: number; NX?: boolean; XX?: boolean }) {
@@ -116,13 +118,18 @@ class FakeRedisClient {
     const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
     return [...this.store.keys()].filter((k) => regex.test(k));
   }
-  public async flushAll() { this.store.clear(); this.expires.clear(); }
+  public async flushAll() {
+    this.store.clear();
+    this.expires.clear();
+  }
   public async incrBy(key: string, n: number) {
     const next = Number(this.store.get(key) ?? 0) + n;
     this.store.set(key, String(next));
     return next;
   }
-  public async decrBy(key: string, n: number) { return this.incrBy(key, -n); }
+  public async decrBy(key: string, n: number) {
+    return this.incrBy(key, -n);
+  }
 }
 
 const fakeClient = new FakeRedisClient();
@@ -146,7 +153,7 @@ The in-package vitest config runs `silent: true`, but if you're outside the pack
 ```ts
 cache.setCacheConfigurations({
   default: "memory",
-  logging: false,             // <-- here
+  logging: false, // <-- here
   drivers: { memory: MemoryCacheDriver },
   options: { memory: {} },
 });
@@ -165,7 +172,7 @@ cache.on("hit", hits);
 await service.getProfile("1");
 await service.getProfile("1");
 
-expect(hits).toHaveBeenCalledTimes(1);   // second call was a hit
+expect(hits).toHaveBeenCalledTimes(1); // second call was a hit
 ```
 
 Listeners registered via `cache.on(...)` automatically attach to any driver loaded later, so order of `on()` vs `init()` doesn't matter.
@@ -178,9 +185,7 @@ The chain-serialization guarantee is worth testing when your code fans out concu
 await cache.set("counter", 0);
 
 await Promise.all(
-  Array.from({ length: 10 }, () =>
-    cache.update<number>("counter", (c) => (c ?? 0) + 1),
-  ),
+  Array.from({ length: 10 }, () => cache.update<number>("counter", (c) => (c ?? 0) + 1)),
 );
 
 await expect(cache.get("counter")).resolves.toBe(10);
@@ -205,7 +210,7 @@ beforeEach(async () => {
 
 it("returns the most similar doc above threshold", async () => {
   await cache.set("a", { text: "alpha" }, { vector: [1, 0, 0] });
-  await cache.set("b", { text: "beta" },  { vector: [0, 1, 0] });
+  await cache.set("b", { text: "beta" }, { vector: [0, 1, 0] });
 
   const hits = await cache.similar([1, 0, 0], { topK: 1, threshold: 0.5 });
 

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

@@ -1,6 +1,6 @@
 ---
 name: use-cache-atomic
-description: 'Atomic counters via cache.increment(key, by=1) / cache.decrement(key, by=1) — returns the new number, throws on non-numeric values. Triggers: `cache.increment`, `cache.decrement`, "view counter", "page views", "atomic counter", "decrement stock", "rate-limit counter", "INCRBY"; typical import `import { cache } from "@warlock.js/cache"`. Skip: read-modify-write of objects — the `use-cache-update-merge` topic; named-lock coordination — the `use-cache-lock` topic; competing libs `ioredis` `INCR`, native counters in a `Map`.'
+description: 'Atomic counters via cache.increment(key, by=1, { ttl }?) / cache.decrement(key, by=1) — returns the new number, throws on non-numeric values. Triggers: `cache.increment`, `cache.decrement`, "view counter", "page views", "atomic counter", "decrement stock", "rate-limit counter", "INCRBY"; typical import `import { cache } from "@warlock.js/cache"`. Skip: read-modify-write of objects — the `use-cache-update-merge` topic; named-lock coordination — the `use-cache-lock` topic; competing libs `ioredis` `INCR`, native counters in a `Map`.'
 ---
 
 # Atomic counters — `cache.increment` / `cache.decrement`
@@ -11,9 +11,9 @@ code. Both return the **new** value after the operation.
 ```ts
 import { cache } from "@warlock.js/cache";
 
-const views = await cache.increment(`post.${id}.views`);     // +1 → 1, 2, 3…
-const bulk = await cache.increment(`post.${id}.views`, 10);  // +10
-const left = await cache.decrement(`stock.${sku}`, 3);       // -3
+const views = await cache.increment(`post.${id}.views`); // +1 → 1, 2, 3…
+const bulk = await cache.increment(`post.${id}.views`, 10); // +10
+const left = await cache.decrement(`stock.${sku}`, 3); // -3
 ```
 
 - A missing key is treated as `0`, so the first `increment` returns `by` (default `1`).
@@ -25,18 +25,24 @@ const left = await cache.decrement(`stock.${sku}`, 3);       // -3
 
 `increment`, `decrement`, `pull` and `update` are atomic, but only some drivers are atomic **across servers**:
 
-| Driver | `increment` / `decrement` | `pull` | `update` / `merge` |
-|---|---|---|---|
-| `redis` | cross-server (`INCRBY`) | cross-server (`GETDEL`) | cross-server (Lua compare-and-set, retries) |
-| `pg` | cross-server (one upsert) | cross-server (`DELETE … RETURNING`) | cross-server (compare-and-set, retries) |
-| `memory` / `memoryExtended` / `lru` / `mock` | one process | one process | one process |
-| `file` | one process | one process | not supported (throws) |
+| Driver                                       | `increment` / `decrement` | `pull`                              | `update` / `merge`                          |
+| -------------------------------------------- | ------------------------- | ----------------------------------- | ------------------------------------------- |
+| `redis`                                      | cross-server (`INCRBY`)   | cross-server (`GETDEL`)             | cross-server (Lua compare-and-set, retries) |
+| `pg`                                         | cross-server (one upsert) | cross-server (`DELETE … RETURNING`) | cross-server (compare-and-set, retries)     |
+| `memory` / `memoryExtended` / `lru` / `mock` | one process               | one process                         | one process                                 |
+| `file`                                       | one process               | one process                         | not supported (throws)                      |
 
 Use `redis` or `pg` for anything several servers touch (rate limits, login throttles, one-time tokens); memory is per-process. On redis/pg the `update` callback may run more than once under contention: keep it side-effect free.
 
 ## TTL is kept
 
-Every driver keeps the key's **remaining TTL** across `increment`/`decrement`, so a fixed-window counter can't turn permanent. Set the TTL when you create the counter (`cache.set(key, 0, "1m")`, then `increment`). Use `cache.update` (see the `use-cache-update-merge` topic) for objects.
+Pass the TTL on **every increment** of an expiring counter:
+
+```ts
+await cache.increment("login.failures", 1, { ttl: "1m" });
+```
+
+A missing or expired key starts at the amount with that TTL (seconds or duration string); an existing deadline is preserved. An explicit TTL also adds expiry to a live permanent counter, repairing counters left by an earlier seed/increment race. Without `options.ttl`, a fresh key uses the driver's default TTL. Redis applies the count and expiry in one Lua call; Postgres uses one upsert. This closes the race where a separate `set(key, 0, { ttl, onConflict: "create" })` seed expires just before the increment recreates the key. Tagged calls forward the option; namespaces use their default TTL unless overridden per call. Decrements keep existing TTLs too. Use `cache.update` (see the `use-cache-update-merge` topic) for objects.
 
 ## Common shapes
 

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

@@ -30,11 +30,14 @@ const missingIds = ids.filter((_, index) => users[index] === null);
 ## 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
+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.

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

@@ -12,14 +12,14 @@ Dedicated accessor for ordered collections — queues, recent-N buffers, sliding
 ```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
+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.trim(0, 99); // keep only indices 0..99 inclusive
 await recent.clear();
 ```
 
@@ -31,8 +31,8 @@ The generic flows through every method. Pass the element type at the accessor ca
 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
+await queue.push({ type: "import", at: Date.now() }); // ✓
+await queue.push("not an event" as never); // ✗ at the caller
 ```
 
 ## Current performance characteristics
@@ -54,7 +54,7 @@ When a list becomes empty (e.g. after successive `pop()` / `shift()` / `trim(0,
 ```ts
 await recent.push("a");
 await recent.pop();
-await cache.get("recent-events");   // null, not []
+await cache.get("recent-events"); // null, not []
 ```
 
 ## Typical recipes
@@ -62,18 +62,18 @@ await cache.get("recent-events");   // null, not []
 ```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
+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
+const next = await queue.shift(); // FIFO
 
 // Stack
 const stack = cache.list<Frame>("stack");
 await stack.push(frame);
-const top = await stack.pop();        // LIFO
+const top = await stack.pop(); // LIFO
 ```
 
 ## What lists are NOT for