layercache 1.2.1 → 1.2.3

package/README.md

@@ -1,12 +1,12 @@
 # layercache
 
-**Multi-layer caching for Node.js — memory → Redis → your DB, unified in one API.**
+**Production-ready multi-layer caching for Node.js — memory, Redis, persistence, invalidation, and resilience in one API.**
 
 [![npm version](https://img.shields.io/npm/v/layercache)](https://www.npmjs.com/package/layercache)
 [![npm downloads](https://img.shields.io/npm/dw/layercache)](https://www.npmjs.com/package/layercache)
 [![license](https://img.shields.io/npm/l/layercache)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-blue)](https://www.typescriptlang.org/)
-[![test coverage](https://img.shields.io/badge/tests-158%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
+[![test coverage](https://img.shields.io/badge/tests-180%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
 
 ```
 L1 hit  ~0.01 ms  ← served from memory, zero network
@@ -26,6 +26,8 @@ Most Node.js services end up with the same problem:
 
 layercache solves all three. You declare your layers once and call `get`. Everything else is handled.
 
+It is designed for production services that need predictable cache behavior under load: stampede prevention, cross-instance invalidation, layered TTL control, operational metrics, and safer persistence defaults.
+
 ```ts
 const user = await cache.get('user:123', () => db.findUser(123))
 //                                         ↑ only called on a full miss
@@ -43,7 +45,7 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Batch tag invalidation** — `invalidateByTags(['tenant:a', 'users'], 'all')` for OR/AND invalidation in one call
 - **Pattern invalidation** — `invalidateByPattern('user:*')`
 - **Prefix invalidation** — efficient `invalidateByPrefix('user:123:')` for hierarchical keys
-- **Generation-based invalidation** — `generation` prefixes keys with `vN:` and `bumpGeneration()` rotates the namespace instantly
+- **Generation-based invalidation** — `generation` prefixes keys with `vN:` and `bumpGeneration()` rotates the namespace instantly, with optional stale-generation cleanup
 - **Per-layer TTL overrides** — different TTLs for memory vs. Redis in one call
 - **TTL policies** — align TTLs to time boundaries (`until-midnight`, `next-hour`, `{ alignTo }`, or a function)
 - **Negative caching** — cache known misses for a short TTL to protect the database
@@ -82,7 +84,7 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Nested namespaces** — `namespace('a').namespace('b')` for composable key prefixes with namespace-scoped metrics
 - **Custom layers** — implement the 5-method `CacheLayer` interface to plug in Memcached, DynamoDB, or anything else
 - **Edge-safe entry point** — `layercache/edge` exports the non-Node helpers for Worker-style runtimes
-- **ESM + CJS** — works with both module systems, Node.js ≥ 18
+- **ESM + CJS** — works with both module systems, Node.js ≥ 20
 
 ---
 
@@ -171,7 +173,7 @@ await cache.set('user:123', user, {
 
 ### `cache.invalidateByTag(tag): Promise<void>`
 
-Deletes every key that was stored with this tag across all layers.
+Deletes every key that was stored with this tag across all layers. In multi-instance deployments, this is only complete when every instance shares the same tag index implementation (for example `RedisTagIndex`).
 
 ```ts
 await cache.set('user:123',       user,  { tags: ['user:123'] })
@@ -191,12 +193,14 @@ await cache.invalidateByTags(['users', 'posts'], 'any')    // keys tagged with e
 
 ### `cache.invalidateByPattern(pattern): Promise<void>`
 
-Glob-style deletion against the tracked key set.
+Glob-style deletion against the tracked key set, plus any layer that can enumerate real keys (for example `MemoryLayer`, `RedisLayer`, or `DiskLayer`).
 
 ```ts
 await cache.invalidateByPattern('user:*') // deletes user:1, user:2, …
 ```
 
+For multi-instance deployments, prefer a shared `RedisTagIndex`. Without it, pattern invalidation still scans real layer keys when available, but that fallback only helps on layers that implement `keys()`, and tag tracking itself remains process-local.
+
 ### `cache.invalidateByPrefix(prefix): Promise<void>`
 
 Prefer this over glob invalidation when your keys are hierarchical.
@@ -278,6 +282,17 @@ await cache.set('user:123', user)
 cache.bumpGeneration() // now reads use v2:user:123
 ```
 
+If you also want old generation keys cleaned up automatically instead of waiting for TTL expiry:
+
+```ts
+const cache = new CacheStack([...], {
+  generation: 1,
+  generationCleanup: { batchSize: 500 }
+})
+```
+
+`bumpGeneration()` only rotates future reads and writes by default. Enable `generationCleanup` when you want previous generations to be pruned automatically instead of aging out by TTL.
+
 ### OpenTelemetry note
 
 `createOpenTelemetryPlugin()` currently wraps a `CacheStack` instance's methods directly. Use one OpenTelemetry plugin per cache instance; if you need to compose multiple wrappers, install them in a fixed order and uninstall them in reverse order.
@@ -452,13 +467,14 @@ const cache = new CacheStack(
   {
     singleFlightCoordinator: coordinator,
     singleFlightLeaseMs: 30_000,
+    singleFlightRenewIntervalMs: 10_000,
     singleFlightTimeoutMs: 5_000,
     singleFlightPollMs: 50
   }
 )
 ```
 
-When another instance already owns the miss, the current process waits for the value to appear in the shared layer instead of running the fetcher again.
+When another instance already owns the miss, the current process waits for the value to appear in the shared layer instead of running the fetcher again. `RedisSingleFlightCoordinator` also renews its Redis lease while the worker is still running, so long fetches are less likely to expire their lock mid-flight. Keep `singleFlightLeaseMs` comfortably above your expected fetch latency, and use `singleFlightRenewIntervalMs` if you need tighter control over renewal cadence.
 
 ### Cross-server L1 invalidation
 
@@ -479,10 +495,10 @@ const cache = new CacheStack(
 await cache.disconnect() // unsubscribes cleanly on shutdown
 ```
 
-By default, every `set` also broadcasts an invalidation so other servers evict stale memory immediately. To suppress broadcasts on writes (high write-volume services):
+By default, write-triggered L1 invalidation is **off** even when an invalidation bus is configured. This avoids surprising Redis Pub/Sub traffic in write-heavy services. Enable it explicitly when you want every write to evict peer memory caches immediately:
 
 ```ts
-new CacheStack([...], { invalidationBus: bus, publishSetInvalidation: false })
+new CacheStack([...], { invalidationBus: bus, broadcastL1Invalidation: true })
 ```
 
 ### Distributed tag invalidation
@@ -494,7 +510,8 @@ import { RedisTagIndex } from 'layercache'
 
 const sharedTagIndex = new RedisTagIndex({
   client: redis,
-  prefix: 'myapp:tag-index' // namespaced so it doesn't collide with other data
+  prefix: 'myapp:tag-index', // namespaced so it doesn't collide with other data
+  knownKeysShards: 8
 })
 
 // Every CacheStack instance should use the same Redis-backed tag index config
@@ -506,6 +523,8 @@ const cache = new CacheStack(
 
 Now `invalidateByTag('user:123')` on any server deletes every tagged key, regardless of which server originally wrote it.
 
+The same recommendation applies to `invalidateByPattern()` and `invalidateByPrefix()` in distributed deployments: a shared tag index gives the most complete view of known keys, while layer key scans act as a fallback only when the shared layer exposes `keys()`.
+
 ### Safe Redis clearing
 
 `RedisLayer.clear()` is intentionally conservative. Without a `prefix`, it throws instead of deleting the whole Redis database.
@@ -528,6 +547,38 @@ new RedisLayer({
 })
 ```
 
+For production Redis, also set an explicit `prefix`, enforce Redis authentication/network isolation, and configure Redis `maxmemory` / eviction policy so cache growth cannot starve unrelated workloads.
+
+### DiskLayer safety
+
+`DiskLayer` is best used with an application-controlled directory and an explicit `maxFiles` bound.
+
+```ts
+import { resolve } from 'node:path'
+
+const disk = new DiskLayer({
+  directory: resolve('./var/cache/layercache'),
+  maxFiles: 10_000
+})
+```
+
+The library hashes cache keys before turning them into filenames, validates the configured directory, uses atomic temp-file writes, and removes malformed on-disk entries. You should still keep the directory outside any user-controlled path and set filesystem permissions so only your app can read or write it.
+
+### Scoped fetcher rate limiting
+
+Rate limits are global by default, but you can scope them per cache key or per fetcher function when different backends should not throttle each other.
+
+```ts
+await cache.get('user:123', fetchUser, {
+  fetcherRateLimit: {
+    maxConcurrent: 1,
+    scope: 'key'
+  }
+})
+```
+
+Use `scope: 'fetcher'` to share a bucket across calls using the same fetcher function reference, or `bucketKey: 'billing-api'` for a custom named bucket.
+
 ---
 
 ## Per-layer TTL overrides
@@ -586,6 +637,8 @@ await cache.get('leaderboard', fetchLeaderboard, {
 })
 ```
 
+Background refreshes time out after 30 seconds by default so a hung upstream fetch cannot block future refresh attempts forever. Override that with `backgroundRefreshTimeoutMs`.
+
 ---
 
 ## Graceful degradation & circuit breaker
@@ -682,6 +735,8 @@ await cache.persistToFile('./cache-snapshot.json')
 await cache.restoreFromFile('./cache-snapshot.json')
 ```
 
+For safety, file snapshots are restricted to `process.cwd()` by default. Set `snapshotBaseDir` to an explicit directory for application-controlled snapshot storage, or `false` if you intentionally want to disable that restriction.
+
 ---
 
 ## Event hooks
@@ -983,7 +1038,7 @@ new CacheStack([...], {
 
 ## Requirements
 
-- Node.js ≥ 18
+- Node.js ≥ 20
 - TypeScript ≥ 5.0 (optional — fully typed, ships `.d.ts`)
 - ioredis ≥ 5 (optional peer dependency — only needed for `RedisLayer` / `RedisTagIndex`)
 

package/dist/{chunk-ZMDB5KOK.js → chunk-7V7XAB74.js}

@@ -1,6 +1,29 @@
 // src/internal/StoredValue.ts
 function isStoredValueEnvelope(value) {
-  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value;
+  if (v.__layercache !== 1) {
+    return false;
+  }
+  if (v.kind !== "value" && v.kind !== "empty") {
+    return false;
+  }
+  if (v.freshUntil !== null && typeof v.freshUntil !== "number") {
+    return false;
+  }
+  if (v.staleUntil !== null && typeof v.staleUntil !== "number") {
+    return false;
+  }
+  if (v.errorUntil !== null && typeof v.errorUntil !== "number") {
+    return false;
+  }
+  const maxTimestamp = Date.now() + 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (typeof v.freshUntil === "number" && v.freshUntil > maxTimestamp) {
+    return false;
+  }
+  return true;
 }
 function createStoredValueEnvelope(options) {
   const now = options.now ?? Date.now();

package/dist/{chunk-46UH7LNM.js → chunk-KOYGHLVP.js}

@@ -1,7 +1,6 @@
 import {
-  PatternMatcher,
   unwrapStoredValue
-} from "./chunk-ZMDB5KOK.js";
+} from "./chunk-7V7XAB74.js";
 
 // src/layers/MemoryLayer.ts
 var MemoryLayer = class {
@@ -49,16 +48,10 @@ var MemoryLayer = class {
     return entry.value;
   }
   async getMany(keys) {
-    const values = [];
-    for (const key of keys) {
-      values.push(await this.getEntry(key));
-    }
-    return values;
+    return Promise.all(keys.map((key) => this.getEntry(key)));
   }
   async setMany(entries) {
-    for (const entry of entries) {
-      await this.set(entry.key, entry.value, entry.ttl);
-    }
+    await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
@@ -197,15 +190,17 @@ var TagIndex = class {
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Set();
   maxKnownKeys;
+  nextNodeId = 1;
+  root = this.createTrieNode();
   constructor(options = {}) {
-    this.maxKnownKeys = options.maxKnownKeys;
+    this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
   }
   async touch(key) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
   }
   async track(key, tags) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
     if (tags.length === 0) {
       return;
@@ -231,18 +226,104 @@ var TagIndex = class {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
   async keysForPrefix(prefix) {
-    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
+    const node = this.findNode(prefix);
+    if (!node) {
+      return [];
+    }
+    const matches = [];
+    this.collectFromNode(node, prefix, matches);
+    return matches;
   }
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
   async matchPattern(pattern) {
-    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+    const matches = /* @__PURE__ */ new Set();
+    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set());
+    return [...matches];
   }
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
     this.knownKeys.clear();
+    this.root.children.clear();
+    this.root.terminal = false;
+    this.nextNodeId = this.root.id + 1;
+  }
+  createTrieNode() {
+    return {
+      id: this.nextNodeId++,
+      terminal: false,
+      children: /* @__PURE__ */ new Map()
+    };
+  }
+  insertKnownKey(key) {
+    if (this.knownKeys.has(key)) {
+      return;
+    }
+    this.knownKeys.add(key);
+    let node = this.root;
+    for (const character of key) {
+      let child = node.children.get(character);
+      if (!child) {
+        child = this.createTrieNode();
+        node.children.set(character, child);
+      }
+      node = child;
+    }
+    node.terminal = true;
+  }
+  findNode(prefix) {
+    let node = this.root;
+    for (const character of prefix) {
+      node = node.children.get(character);
+      if (!node) {
+        return void 0;
+      }
+    }
+    return node;
+  }
+  collectFromNode(node, prefix, matches) {
+    if (node.terminal) {
+      matches.push(prefix);
+    }
+    for (const [character, child] of node.children) {
+      this.collectFromNode(child, `${prefix}${character}`, matches);
+    }
+  }
+  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited) {
+    const stateKey = `${node.id}:${patternIndex}`;
+    if (visited.has(stateKey)) {
+      return;
+    }
+    visited.add(stateKey);
+    if (patternIndex === pattern.length) {
+      if (node.terminal) {
+        matches.add(prefix);
+      }
+      return;
+    }
+    const patternChar = pattern[patternIndex];
+    if (patternChar === void 0) {
+      return;
+    }
+    if (patternChar === "*") {
+      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited);
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited);
+      }
+      return;
+    }
+    if (patternChar === "?") {
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex + 1, matches, visited);
+      }
+      return;
+    }
+    const child = node.children.get(patternChar);
+    if (child) {
+      this.collectPatternMatches(child, `${prefix}${patternChar}`, pattern, patternIndex + 1, matches, visited);
+    }
   }
   pruneKnownKeysIfNeeded() {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
@@ -259,7 +340,7 @@ var TagIndex = class {
     }
   }
   removeKey(key) {
-    this.knownKeys.delete(key);
+    this.removeKnownKey(key);
     const tags = this.keyToTags.get(key);
     if (!tags) {
       return;
@@ -276,6 +357,34 @@ var TagIndex = class {
     }
     this.keyToTags.delete(key);
   }
+  removeKnownKey(key) {
+    if (!this.knownKeys.delete(key)) {
+      return;
+    }
+    const path = [];
+    let node = this.root;
+    for (const character of key) {
+      const child = node.children.get(character);
+      if (!child) {
+        return;
+      }
+      path.push([node, character]);
+      node = child;
+    }
+    node.terminal = false;
+    for (let index = path.length - 1; index >= 0; index -= 1) {
+      const entry = path[index];
+      if (!entry) {
+        continue;
+      }
+      const [parent, character] = entry;
+      const child = parent.children.get(character);
+      if (!child || child.terminal || child.children.size > 0) {
+        break;
+      }
+      parent.children.delete(character);
+    }
+  }
 };
 
 // src/integrations/hono.ts
@@ -287,7 +396,8 @@ function createHonoCacheMiddleware(cache, options = {}) {
       await next();
       return;
     }
-    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${context.req.path ?? context.req.url ?? "/"}`;
+    const rawPath = context.req.path ?? context.req.url ?? "/";
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeUrl(rawPath)}`;
     const cached = await cache.get(key, void 0, options);
     if (cached !== null) {
       context.header?.("x-cache", "HIT");
@@ -298,12 +408,26 @@ function createHonoCacheMiddleware(cache, options = {}) {
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {
       context.header?.("x-cache", "MISS");
-      void cache.set(key, body, options);
+      cache.set(key, body, options).catch((err) => {
+        cache.emit("error", {
+          operation: "set",
+          error: err instanceof Error ? err.message : String(err)
+        });
+      });
       return originalJson(body, status);
     };
     await next();
   };
 }
+function normalizeUrl(url) {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    parsed.searchParams.sort();
+    return decodeURIComponent(parsed.pathname) + parsed.search;
+  } catch {
+    return url;
+  }
+}
 
 export {
   MemoryLayer,

package/dist/{chunk-GF47Y3XR.js → chunk-QHWG7QS5.js}

@@ -1,25 +1,27 @@
 import {
   PatternMatcher
-} from "./chunk-ZMDB5KOK.js";
+} from "./chunk-7V7XAB74.js";
 
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
+  knownKeysShards;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
+    this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
   async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
+    await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.sadd(this.knownKeysKey(), key);
+    pipeline.sadd(this.knownKeysKeyFor(key), key);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
@@ -36,7 +38,7 @@ var RedisTagIndex = class {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.srem(this.knownKeysKeyFor(key), key);
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -48,12 +50,14 @@ var RedisTagIndex = class {
   }
   async keysForPrefix(prefix) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(this.knownKeysKey(), cursor, "COUNT", this.scanCount);
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => key.startsWith(prefix)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => key.startsWith(prefix)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async tagsForKey(key) {
@@ -61,19 +65,21 @@ var RedisTagIndex = class {
   }
   async matchPattern(pattern) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(
-        this.knownKeysKey(),
-        cursor,
-        "MATCH",
-        pattern,
-        "COUNT",
-        this.scanCount
-      );
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          knownKeysKey,
+          cursor,
+          "MATCH",
+          pattern,
+          "COUNT",
+          this.scanCount
+        );
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async clear() {
@@ -94,8 +100,17 @@ var RedisTagIndex = class {
     } while (cursor !== "0");
     return matches;
   }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
+  knownKeysKeyFor(key) {
+    if (this.knownKeysShards === 1) {
+      return `${this.prefix}:keys`;
+    }
+    return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
+  }
+  knownKeysKeys() {
+    if (this.knownKeysShards === 1) {
+      return [`${this.prefix}:keys`];
+    }
+    return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
@@ -104,6 +119,22 @@ var RedisTagIndex = class {
     return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
   }
 };
+function normalizeKnownKeysShards(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
+  }
+  return value;
+}
+function simpleHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 31 + value.charCodeAt(index) >>> 0;
+  }
+  return hash;
+}
 
 export {
   RedisTagIndex