layercache 1.2.3 → 1.2.4

package/README.md

@@ -1,92 +1,99 @@
-# layercache
+<p align="center">
+  <img src="./logo.png" width="520" alt="layercache logo">
+</p>
+
+<h1 align="center">layercache</h1>
+
+<p align="center">
+  <strong>Production-ready multi-layer caching for Node.js</strong><br>
+  <em>Memory, Redis, persistence, invalidation, observability, and resilience in one API.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/layercache"><img src="https://img.shields.io/npm/v/layercache" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/layercache"><img src="https://img.shields.io/npm/dw/layercache" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/layercache" alt="license"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-first-blue" alt="TypeScript"></a>
+  <a href="https://github.com/flyingsquirrel0419/layercache"><img src="https://img.shields.io/badge/tests-180%20passing-brightgreen" alt="tests"></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#core-api">Core API</a> ·
+  <a href="#invalidation--freshness">Invalidation</a> ·
+  <a href="#integrations--tooling">Integrations</a> ·
+  <a href="#contributing">Contributing</a>
+</p>
 
-**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-180%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
+## At a glance
 
-```
+- **Fast read path** — combine memory L1, Redis L2, disk, or custom layers behind one API with automatic backfill.
+- **Stampede control** — prevent duplicate miss storms with in-process dedupe and optional distributed single-flight.
+- **Strong invalidation model** — support tags, batched tags, wildcards, prefixes, and generation-based cache rotation.
+- **Built for production failure modes** — serve stale safely, refresh ahead, degrade gracefully, trip circuit breakers, and throttle fetchers.
+- **Operational visibility included** — expose metrics, stats, health checks, OpenTelemetry spans, and an admin CLI.
+- **Fits real Node stacks** — integrate directly with Express, Fastify, Hono, GraphQL, tRPC, and NestJS.
+
+Most Node.js services hit the same wall:
+
+| Approach | Tradeoff |
+|---|---|
+| Memory-only cache | Fast, but every instance has a different view of data |
+| Redis-only cache | Shared, but every request pays a network round-trip |
+| Hand-rolled hybrid cache | Possible, but you rebuild stampede prevention, invalidation, TTL policy, and observability yourself |
+
+`layercache` gives you a single API for layered caching and handles the hard parts for you: read-through fetches, backfill, stale serving, distributed invalidation, rate limiting, persistence, and operational introspection.
+
+On a hit, `layercache` serves the fastest available layer and backfills anything above it. On a miss, the fetcher runs once, even under heavy concurrency.
+
+## Performance profile
+
+```text
 L1 hit  ~0.01 ms  ← served from memory, zero network
 L2 hit  ~0.5  ms  ← served from Redis, backfilled to memory
 miss    ~20   ms  ← fetcher runs once, all layers filled
 ```
 
----
+## Why teams use it
 
-## Why layercache?
+- **Predictable cache behavior** — layered reads, automatic backfill, negative caching, refresh-ahead, and stale serving.
+- **Reliable invalidation** — tags, batched tags, wildcards, prefixes, and generation-based rotation.
+- **Production safeguards** — rate limiting, circuit breakers, graceful degradation, compression limits, serializer hardening, and snapshot path validation.
+- **Operational visibility** — metrics, health checks, OpenTelemetry spans, stats endpoints, and an admin CLI.
+- **Works with your stack** — Express, Fastify, Hono, GraphQL, tRPC, NestJS, CLI, and custom cache layers.
 
-Most Node.js services end up with the same problem:
+## Feature map
 
-- **Memory-only** → fast, but not shared across servers
-- **Redis-only** → shared, but every read pays a network round-trip
-- **Hand-rolled layers** → works, but you rewrite stampede prevention, backfill logic, and tag invalidation in every project
+### Core caching
 
-layercache solves all three. You declare your layers once and call `get`. Everything else is handled.
+- Layered reads with automatic backfill
+- Stampede prevention and optional distributed single-flight
+- Bulk reads and writes with layer-level `getMany()` / `setMany()` fast paths
+- `wrap()`, namespaces, cache warming, `getOrThrow()`, and `inspect()`
 
-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.
+### Invalidation and freshness
 
-```ts
-const user = await cache.get('user:123', () => db.findUser(123))
-//                                         ↑ only called on a full miss
-```
+- Tag invalidation, batched tag invalidation, wildcard invalidation, and prefix invalidation
+- Generation-based invalidation with optional stale-generation cleanup
+- Sliding TTL, adaptive TTL, refresh-ahead, stale-while-revalidate, and stale-if-error
+- Per-layer TTL overrides, TTL policies, negative caching, and TTL jitter
 
-On a hit, the value is returned from the fastest layer that has it, and automatically backfilled into any faster layers that didn't. On a miss, the fetcher runs exactly once — even under 100 concurrent requests for the same key.
+### Operations and resilience
 
----
+- Graceful degradation, circuit breakers, scoped fetcher rate limiting, and write-behind
+- Persistence to memory snapshots or disk snapshots
+- Compression, serializer fallback chains, and MessagePack support
+- Health checks, per-layer metrics, latency tracking, and event hooks
 
-## Features
-
-- **Layered reads & automatic backfill** — hits in slower layers propagate up
-- **Cache stampede prevention** — mutex-based deduplication per key
-- **Tag-based invalidation** — `set('user:123:posts', posts, { tags: ['user:123'] })` then `invalidateByTag('user:123')`
-- **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, 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
-- **Stale strategies** — `staleWhileRevalidate` and `staleIfError` as opt-in read behavior
-- **TTL jitter** — spread expirations to avoid synchronized stampedes
-- **Sliding & adaptive TTL** — extend TTL on every read or ramp it up for hot keys
-- **Refresh-ahead** — trigger background refresh when TTL drops below a threshold
-- **Fetcher rate limiting** — cap concurrent fetchers or requests per interval
-- **Best-effort writes** — tolerate partial layer write failures when desired
-- **Write-behind mode** — write local layers immediately and flush slower remote layers asynchronously
-- **Bulk reads** — `mget` uses layer-level `getMany()` when available
-- **Bulk writes** — `mset` uses layer-level `setMany()` when available
-- **Distributed tag index** — `RedisTagIndex` keeps tag state consistent across multiple servers
-- **Optional distributed single-flight** — plug in a coordinator to dedupe misses across instances
-- **Cross-server L1 invalidation** — Redis pub/sub bus flushes stale memory on other instances when you write or delete
-- **`wrap()` decorator API** — turn any async function into a cached version with auto-generated keys
-- **Cache warming** — pre-populate layers with a prioritised list of entries at startup
-- **Namespaces** — scope a `CacheStack` to a key prefix for multi-tenant or module isolation
-- **Event hooks** — `EventEmitter`-based events for hits, misses, stale serves, errors, and more
-- **Graceful degradation** — skip a failing layer for a configurable retry window
-- **Circuit breaker** — per-key or global; opens after N failures, recovers after cooldown
-- **Compression** — transparent async gzip/brotli in `RedisLayer` (non-blocking) with a byte threshold
-- **Serializer fallback chains** — transparently read legacy payloads (for example JSON) and rewrite them with the primary serializer
-- **Metrics & stats** — per-layer hit/miss counters, **per-layer latency tracking**, circuit-breaker trips, degraded operations; HTTP stats handler
-- **Health checks** — `cache.healthCheck()` returns per-layer health and latency
-- **Persistence** — `exportState` / `importState` for in-process snapshots; `persistToFile` / `restoreFromFile` for disk
-- **Admin CLI** — `layercache stats | keys | inspect | invalidate` against any Redis URL
-- **Framework integrations** — Express middleware, Fastify plugin, Hono middleware, tRPC middleware, GraphQL resolver wrapper
-- **OpenTelemetry plugin** — instrument `get` / `set` / invalidation flows with spans
-- **MessagePack serializer** — drop-in replacement for lower Redis memory usage
-- **NestJS module** — `CacheStackModule.forRoot(...)` and `forRootAsync(...)` with `@InjectCacheStack()`
-- **`getOrThrow()`** — throws `CacheMissError` instead of returning `null`, for strict use cases
-- **`inspect()`** — debug a key: see which layers hold it, remaining TTLs, tags, and staleness state
-- **MemoryLayer cleanup hooks** — periodic TTL cleanup and `onEvict` callbacks
-- **Conditional caching** — `shouldCache` predicate to skip caching specific fetcher results
-- **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 ≥ 20
+### Integrations and tooling
 
----
+- Express, Fastify, Hono, GraphQL, tRPC, and NestJS integrations
+- Redis-backed distributed tag index and invalidation bus support
+- Admin CLI for stats, key inspection, and invalidation
+- Edge-safe entry point for Worker-style runtimes
 
 ## Installation
 
@@ -105,16 +112,11 @@ import { CacheStack, MemoryLayer, RedisLayer } from 'layercache'
 import Redis from 'ioredis'
 
 const cache = new CacheStack([
-  new MemoryLayer({ ttl: 60,   maxSize: 1_000 }),   // L1 — local memory
-  new RedisLayer({ client: new Redis(), ttl: 3600 }) // L2 — Redis
+  new MemoryLayer({ ttl: 60, maxSize: 1_000 }),
+  new RedisLayer({ client: new Redis(), ttl: 3600 })
 ])
 
-// Fetch pattern — cache miss runs the fetcher, hit skips it entirely
 const user = await cache.get<User>('user:123', () => db.findUser(123))
-
-// Manual set / delete
-await cache.set('user:123', user)
-await cache.delete('user:123')
 ```
 
 Memory-only setup (no Redis required):
@@ -171,6 +173,8 @@ await cache.set('user:123', user, {
 })
 ```
 
+## Invalidation & freshness
+
 ### `cache.invalidateByTag(tag): Promise<void>`
 
 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`).
@@ -763,9 +767,11 @@ cache.on('error', ({ event, context }) => logger.error(event, context))
 
 ---
 
-## Framework integrations
+## Integrations & tooling
 
-### Express
+### Framework integrations
+
+#### Express
 
 ```ts
 import { CacheStack, MemoryLayer, createExpressCacheMiddleware } from 'layercache'
@@ -785,7 +791,7 @@ app.get('/api/user/:id', createExpressCacheMiddleware(cache, {
 }), handler)
 ```
 
-### tRPC
+#### tRPC
 
 ```ts
 import { createTrpcCacheMiddleware } from 'layercache/integrations/trpc'
@@ -795,7 +801,7 @@ const cacheMiddleware = createTrpcCacheMiddleware(cache, 'trpc', { ttl: 60 })
 export const cachedProcedure = t.procedure.use(cacheMiddleware)
 ```
 
-### GraphQL
+#### GraphQL
 
 ```ts
 import { cacheGraphqlResolver } from 'layercache/integrations/graphql'
@@ -812,7 +818,7 @@ const resolvers = {
 
 ---
 
-## Admin CLI
+### Admin CLI
 
 Inspect and manage a Redis-backed cache without writing code.
 
@@ -1046,15 +1052,20 @@ new CacheStack([...], {
 
 ## Contributing
 
+Contributions are welcome, whether that means bug fixes, documentation improvements, performance work, new adapters, or issue reports.
+
 ```bash
 git clone https://github.com/flyingsquirrel0419/layercache
 cd layercache
 npm install
+npm run lint
 npm test          # vitest
 npm run build:all # esm + cjs + nestjs package
 ```
 
-PRs and issues welcome.
+- Read the [contribution guide](./CONTRIBUTING.md) before opening a PR.
+- Participation in the project is covered by the [Code of Conduct](./CODE_OF_CONDUCT.md).
+- If you are filing an issue, include reproduction steps, expected behavior, and runtime details when relevant.
 
 ---
 

package/dist/{edge-B_rUqDy6.d.cts → edge-Dw97n89L.d.cts}

@@ -518,6 +518,7 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly keyDiscovery;
     private readonly fetchRateLimiter;
     private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
@@ -640,8 +641,6 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
-    private collectKeysWithPrefix;
-    private collectKeysMatchingPattern;
     private shouldCleanupGenerations;
     private generationCleanupBatchSize;
     private scheduleGenerationCleanup;

package/dist/{edge-B_rUqDy6.d.ts → edge-Dw97n89L.d.ts}

@@ -518,6 +518,7 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly keyDiscovery;
     private readonly fetchRateLimiter;
     private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
@@ -640,8 +641,6 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
-    private collectKeysWithPrefix;
-    private collectKeysMatchingPattern;
     private shouldCleanupGenerations;
     private generationCleanupBatchSize;
     private scheduleGenerationCleanup;

package/dist/edge.d.cts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-B_rUqDy6.cjs';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-Dw97n89L.cjs';
 import 'node:events';

package/dist/edge.d.ts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-B_rUqDy6.js';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-Dw97n89L.js';
 import 'node:events';

package/dist/index.cjs

@@ -306,6 +306,107 @@ function addMap(base, delta) {
   return result;
 }
 
+// src/invalidation/PatternMatcher.ts
+var PatternMatcher = class _PatternMatcher {
+  /**
+   * Tests whether a glob-style pattern matches a value.
+   * Supports `*` (any sequence of characters) and `?` (any single character).
+   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
+   * quadratic memory usage on long patterns/keys.
+   */
+  static matches(pattern, value) {
+    return _PatternMatcher.matchLinear(pattern, value);
+  }
+  /**
+   * Linear-time glob matching with O(1) extra memory.
+   */
+  static matchLinear(pattern, value) {
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let backtrackValueIndex = 0;
+    while (valueIndex < value.length) {
+      const patternChar = pattern[patternIndex];
+      const valueChar = value[valueIndex];
+      if (patternChar === "*" && patternIndex < pattern.length) {
+        starIndex = patternIndex;
+        patternIndex += 1;
+        backtrackValueIndex = valueIndex;
+        continue;
+      }
+      if (patternChar === "?" || patternChar === valueChar) {
+        patternIndex += 1;
+        valueIndex += 1;
+        continue;
+      }
+      if (starIndex !== -1) {
+        patternIndex = starIndex + 1;
+        backtrackValueIndex += 1;
+        valueIndex = backtrackValueIndex;
+        continue;
+      }
+      return false;
+    }
+    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
+      patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
+  }
+};
+
+// src/internal/CacheKeyDiscovery.ts
+var CacheKeyDiscovery = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async collectKeysWithPrefix(prefix) {
+    const { tagIndex } = this.options;
+    const matches = new Set(
+      tagIndex.keysForPrefix ? await tagIndex.keysForPrefix(prefix) : await tagIndex.matchPattern(`${prefix}*`)
+    );
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (key.startsWith(prefix)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-prefix-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+  async collectKeysMatchingPattern(pattern) {
+    const matches = new Set(await this.options.tagIndex.matchPattern(pattern));
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (PatternMatcher.matches(pattern, key)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-pattern-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+};
+
 // src/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
   breakers = /* @__PURE__ */ new Map();
@@ -905,54 +1006,6 @@ var TtlResolver = class {
   }
 };
 
-// src/invalidation/PatternMatcher.ts
-var PatternMatcher = class _PatternMatcher {
-  /**
-   * Tests whether a glob-style pattern matches a value.
-   * Supports `*` (any sequence of characters) and `?` (any single character).
-   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
-   * quadratic memory usage on long patterns/keys.
-   */
-  static matches(pattern, value) {
-    return _PatternMatcher.matchLinear(pattern, value);
-  }
-  /**
-   * Linear-time glob matching with O(1) extra memory.
-   */
-  static matchLinear(pattern, value) {
-    let patternIndex = 0;
-    let valueIndex = 0;
-    let starIndex = -1;
-    let backtrackValueIndex = 0;
-    while (valueIndex < value.length) {
-      const patternChar = pattern[patternIndex];
-      const valueChar = value[valueIndex];
-      if (patternChar === "*" && patternIndex < pattern.length) {
-        starIndex = patternIndex;
-        patternIndex += 1;
-        backtrackValueIndex = valueIndex;
-        continue;
-      }
-      if (patternChar === "?" || patternChar === valueChar) {
-        patternIndex += 1;
-        valueIndex += 1;
-        continue;
-      }
-      if (starIndex !== -1) {
-        patternIndex = starIndex + 1;
-        backtrackValueIndex += 1;
-        valueIndex = backtrackValueIndex;
-        continue;
-      }
-      return false;
-    }
-    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
-      patternIndex += 1;
-    }
-    return patternIndex === pattern.length;
-  }
-};
-
 // src/invalidation/TagIndex.ts
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
@@ -1282,6 +1335,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
+    this.keyDiscovery = new CacheKeyDiscovery({
+      layers: this.layers,
+      tagIndex: this.tagIndex,
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => {
+        await this.handleLayerFailure(layer, operation, error);
+      }
+    });
     if (!options.tagIndex && layers.some((layer) => layer.isLocal === false)) {
       this.logger.warn?.(
         "Using the default in-memory TagIndex with a shared cache layer only tracks keys seen by this process. Use RedisTagIndex for cross-instance tag invalidation."
@@ -1309,6 +1370,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  keyDiscovery;
   fetchRateLimiter = new FetchRateLimiter();
   snapshotSerializer = new JsonSerializer();
   backgroundRefreshes = /* @__PURE__ */ new Map();
@@ -1659,14 +1721,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async invalidateByPattern(pattern) {
     await this.awaitStartup("invalidateByPattern");
-    const keys = await this.collectKeysMatchingPattern(this.qualifyPattern(pattern));
+    const keys = await this.keyDiscovery.collectKeysMatchingPattern(this.qualifyPattern(pattern));
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
   async invalidateByPrefix(prefix) {
     await this.awaitStartup("invalidateByPrefix");
     const qualifiedPrefix = this.qualifyKey(this.validateCacheKey(prefix));
-    const keys = await this.collectKeysWithPrefix(qualifiedPrefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -2279,50 +2341,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
   }
-  async collectKeysWithPrefix(prefix) {
-    const matches = new Set(
-      this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(prefix) : await this.tagIndex.matchPattern(`${prefix}*`)
-    );
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (key.startsWith(prefix)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-prefix-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
-  async collectKeysMatchingPattern(pattern) {
-    const matches = new Set(await this.tagIndex.matchPattern(pattern));
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (PatternMatcher.matches(pattern, key)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-pattern-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
   shouldCleanupGenerations() {
     return Boolean(this.options.generationCleanup);
   }
@@ -2345,7 +2363,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async cleanupGeneration(generation) {
     const prefix = `v${generation}:`;
-    const keys = await this.collectKeysWithPrefix(prefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(prefix);
     if (keys.length === 0) {
       return;
     }

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-B_rUqDy6.cjs';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-B_rUqDy6.cjs';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-Dw97n89L.cjs';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-Dw97n89L.cjs';
 import Redis from 'ioredis';
 import 'node:events';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-B_rUqDy6.js';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-B_rUqDy6.js';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-Dw97n89L.js';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-Dw97n89L.js';
 import Redis from 'ioredis';
 import 'node:events';
 

package/dist/index.js

@@ -266,6 +266,59 @@ function addMap(base, delta) {
   return result;
 }
 
+// src/internal/CacheKeyDiscovery.ts
+var CacheKeyDiscovery = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async collectKeysWithPrefix(prefix) {
+    const { tagIndex } = this.options;
+    const matches = new Set(
+      tagIndex.keysForPrefix ? await tagIndex.keysForPrefix(prefix) : await tagIndex.matchPattern(`${prefix}*`)
+    );
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (key.startsWith(prefix)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-prefix-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+  async collectKeysMatchingPattern(pattern) {
+    const matches = new Set(await this.options.tagIndex.matchPattern(pattern));
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (PatternMatcher.matches(pattern, key)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-pattern-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+};
+
 // src/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
   breakers = /* @__PURE__ */ new Map();
@@ -867,6 +920,14 @@ var CacheStack = class extends EventEmitter {
     const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
+    this.keyDiscovery = new CacheKeyDiscovery({
+      layers: this.layers,
+      tagIndex: this.tagIndex,
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => {
+        await this.handleLayerFailure(layer, operation, error);
+      }
+    });
     if (!options.tagIndex && layers.some((layer) => layer.isLocal === false)) {
       this.logger.warn?.(
         "Using the default in-memory TagIndex with a shared cache layer only tracks keys seen by this process. Use RedisTagIndex for cross-instance tag invalidation."
@@ -894,6 +955,7 @@ var CacheStack = class extends EventEmitter {
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  keyDiscovery;
   fetchRateLimiter = new FetchRateLimiter();
   snapshotSerializer = new JsonSerializer();
   backgroundRefreshes = /* @__PURE__ */ new Map();
@@ -1244,14 +1306,14 @@ var CacheStack = class extends EventEmitter {
   }
   async invalidateByPattern(pattern) {
     await this.awaitStartup("invalidateByPattern");
-    const keys = await this.collectKeysMatchingPattern(this.qualifyPattern(pattern));
+    const keys = await this.keyDiscovery.collectKeysMatchingPattern(this.qualifyPattern(pattern));
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
   async invalidateByPrefix(prefix) {
     await this.awaitStartup("invalidateByPrefix");
     const qualifiedPrefix = this.qualifyKey(this.validateCacheKey(prefix));
-    const keys = await this.collectKeysWithPrefix(qualifiedPrefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -1864,50 +1926,6 @@ var CacheStack = class extends EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
   }
-  async collectKeysWithPrefix(prefix) {
-    const matches = new Set(
-      this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(prefix) : await this.tagIndex.matchPattern(`${prefix}*`)
-    );
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (key.startsWith(prefix)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-prefix-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
-  async collectKeysMatchingPattern(pattern) {
-    const matches = new Set(await this.tagIndex.matchPattern(pattern));
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (PatternMatcher.matches(pattern, key)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-pattern-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
   shouldCleanupGenerations() {
     return Boolean(this.options.generationCleanup);
   }
@@ -1930,7 +1948,7 @@ var CacheStack = class extends EventEmitter {
   }
   async cleanupGeneration(generation) {
     const prefix = `v${generation}:`;
-    const keys = await this.collectKeysWithPrefix(prefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(prefix);
     if (keys.length === 0) {
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Hardened multi-layer caching for Node.js with memory, Redis, stampede prevention, and operational invalidation helpers.",
   "license": "MIT",
   "repository": {

package/packages/nestjs/dist/index.cjs

@@ -504,6 +504,107 @@ function addMap(base, delta) {
   return result;
 }
 
+// ../../src/invalidation/PatternMatcher.ts
+var PatternMatcher = class _PatternMatcher {
+  /**
+   * Tests whether a glob-style pattern matches a value.
+   * Supports `*` (any sequence of characters) and `?` (any single character).
+   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
+   * quadratic memory usage on long patterns/keys.
+   */
+  static matches(pattern, value) {
+    return _PatternMatcher.matchLinear(pattern, value);
+  }
+  /**
+   * Linear-time glob matching with O(1) extra memory.
+   */
+  static matchLinear(pattern, value) {
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let backtrackValueIndex = 0;
+    while (valueIndex < value.length) {
+      const patternChar = pattern[patternIndex];
+      const valueChar = value[valueIndex];
+      if (patternChar === "*" && patternIndex < pattern.length) {
+        starIndex = patternIndex;
+        patternIndex += 1;
+        backtrackValueIndex = valueIndex;
+        continue;
+      }
+      if (patternChar === "?" || patternChar === valueChar) {
+        patternIndex += 1;
+        valueIndex += 1;
+        continue;
+      }
+      if (starIndex !== -1) {
+        patternIndex = starIndex + 1;
+        backtrackValueIndex += 1;
+        valueIndex = backtrackValueIndex;
+        continue;
+      }
+      return false;
+    }
+    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
+      patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
+  }
+};
+
+// ../../src/internal/CacheKeyDiscovery.ts
+var CacheKeyDiscovery = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async collectKeysWithPrefix(prefix) {
+    const { tagIndex } = this.options;
+    const matches = new Set(
+      tagIndex.keysForPrefix ? await tagIndex.keysForPrefix(prefix) : await tagIndex.matchPattern(`${prefix}*`)
+    );
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (key.startsWith(prefix)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-prefix-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+  async collectKeysMatchingPattern(pattern) {
+    const matches = new Set(await this.options.tagIndex.matchPattern(pattern));
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (PatternMatcher.matches(pattern, key)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-pattern-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+};
+
 // ../../src/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
   breakers = /* @__PURE__ */ new Map();
@@ -1103,54 +1204,6 @@ var TtlResolver = class {
   }
 };
 
-// ../../src/invalidation/PatternMatcher.ts
-var PatternMatcher = class _PatternMatcher {
-  /**
-   * Tests whether a glob-style pattern matches a value.
-   * Supports `*` (any sequence of characters) and `?` (any single character).
-   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
-   * quadratic memory usage on long patterns/keys.
-   */
-  static matches(pattern, value) {
-    return _PatternMatcher.matchLinear(pattern, value);
-  }
-  /**
-   * Linear-time glob matching with O(1) extra memory.
-   */
-  static matchLinear(pattern, value) {
-    let patternIndex = 0;
-    let valueIndex = 0;
-    let starIndex = -1;
-    let backtrackValueIndex = 0;
-    while (valueIndex < value.length) {
-      const patternChar = pattern[patternIndex];
-      const valueChar = value[valueIndex];
-      if (patternChar === "*" && patternIndex < pattern.length) {
-        starIndex = patternIndex;
-        patternIndex += 1;
-        backtrackValueIndex = valueIndex;
-        continue;
-      }
-      if (patternChar === "?" || patternChar === valueChar) {
-        patternIndex += 1;
-        valueIndex += 1;
-        continue;
-      }
-      if (starIndex !== -1) {
-        patternIndex = starIndex + 1;
-        backtrackValueIndex += 1;
-        valueIndex = backtrackValueIndex;
-        continue;
-      }
-      return false;
-    }
-    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
-      patternIndex += 1;
-    }
-    return patternIndex === pattern.length;
-  }
-};
-
 // ../../src/invalidation/TagIndex.ts
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
@@ -1479,6 +1532,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
+    this.keyDiscovery = new CacheKeyDiscovery({
+      layers: this.layers,
+      tagIndex: this.tagIndex,
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => {
+        await this.handleLayerFailure(layer, operation, error);
+      }
+    });
     if (!options.tagIndex && layers.some((layer) => layer.isLocal === false)) {
       this.logger.warn?.(
         "Using the default in-memory TagIndex with a shared cache layer only tracks keys seen by this process. Use RedisTagIndex for cross-instance tag invalidation."
@@ -1506,6 +1567,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  keyDiscovery;
   fetchRateLimiter = new FetchRateLimiter();
   snapshotSerializer = new JsonSerializer();
   backgroundRefreshes = /* @__PURE__ */ new Map();
@@ -1856,14 +1918,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async invalidateByPattern(pattern) {
     await this.awaitStartup("invalidateByPattern");
-    const keys = await this.collectKeysMatchingPattern(this.qualifyPattern(pattern));
+    const keys = await this.keyDiscovery.collectKeysMatchingPattern(this.qualifyPattern(pattern));
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
   async invalidateByPrefix(prefix) {
     await this.awaitStartup("invalidateByPrefix");
     const qualifiedPrefix = this.qualifyKey(this.validateCacheKey(prefix));
-    const keys = await this.collectKeysWithPrefix(qualifiedPrefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -2476,50 +2538,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
   }
-  async collectKeysWithPrefix(prefix) {
-    const matches = new Set(
-      this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(prefix) : await this.tagIndex.matchPattern(`${prefix}*`)
-    );
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (key.startsWith(prefix)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-prefix-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
-  async collectKeysMatchingPattern(pattern) {
-    const matches = new Set(await this.tagIndex.matchPattern(pattern));
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (PatternMatcher.matches(pattern, key)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-pattern-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
   shouldCleanupGenerations() {
     return Boolean(this.options.generationCleanup);
   }
@@ -2542,7 +2560,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async cleanupGeneration(generation) {
     const prefix = `v${generation}:`;
-    const keys = await this.collectKeysWithPrefix(prefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(prefix);
     if (keys.length === 0) {
       return;
     }

package/packages/nestjs/dist/index.d.cts

@@ -410,6 +410,7 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly keyDiscovery;
     private readonly fetchRateLimiter;
     private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
@@ -532,8 +533,6 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
-    private collectKeysWithPrefix;
-    private collectKeysMatchingPattern;
     private shouldCleanupGenerations;
     private generationCleanupBatchSize;
     private scheduleGenerationCleanup;

package/packages/nestjs/dist/index.d.ts

@@ -410,6 +410,7 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly keyDiscovery;
     private readonly fetchRateLimiter;
     private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
@@ -532,8 +533,6 @@ declare class CacheStack extends EventEmitter {
     private sleep;
     private withTimeout;
     private shouldBroadcastL1Invalidation;
-    private collectKeysWithPrefix;
-    private collectKeysMatchingPattern;
     private shouldCleanupGenerations;
     private generationCleanupBatchSize;
     private scheduleGenerationCleanup;

package/packages/nestjs/dist/index.js

@@ -468,6 +468,107 @@ function addMap(base, delta) {
   return result;
 }
 
+// ../../src/invalidation/PatternMatcher.ts
+var PatternMatcher = class _PatternMatcher {
+  /**
+   * Tests whether a glob-style pattern matches a value.
+   * Supports `*` (any sequence of characters) and `?` (any single character).
+   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
+   * quadratic memory usage on long patterns/keys.
+   */
+  static matches(pattern, value) {
+    return _PatternMatcher.matchLinear(pattern, value);
+  }
+  /**
+   * Linear-time glob matching with O(1) extra memory.
+   */
+  static matchLinear(pattern, value) {
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let backtrackValueIndex = 0;
+    while (valueIndex < value.length) {
+      const patternChar = pattern[patternIndex];
+      const valueChar = value[valueIndex];
+      if (patternChar === "*" && patternIndex < pattern.length) {
+        starIndex = patternIndex;
+        patternIndex += 1;
+        backtrackValueIndex = valueIndex;
+        continue;
+      }
+      if (patternChar === "?" || patternChar === valueChar) {
+        patternIndex += 1;
+        valueIndex += 1;
+        continue;
+      }
+      if (starIndex !== -1) {
+        patternIndex = starIndex + 1;
+        backtrackValueIndex += 1;
+        valueIndex = backtrackValueIndex;
+        continue;
+      }
+      return false;
+    }
+    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
+      patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
+  }
+};
+
+// ../../src/internal/CacheKeyDiscovery.ts
+var CacheKeyDiscovery = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async collectKeysWithPrefix(prefix) {
+    const { tagIndex } = this.options;
+    const matches = new Set(
+      tagIndex.keysForPrefix ? await tagIndex.keysForPrefix(prefix) : await tagIndex.matchPattern(`${prefix}*`)
+    );
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (key.startsWith(prefix)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-prefix-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+  async collectKeysMatchingPattern(pattern) {
+    const matches = new Set(await this.options.tagIndex.matchPattern(pattern));
+    await Promise.all(
+      this.options.layers.map(async (layer) => {
+        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (PatternMatcher.matches(pattern, key)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "invalidate-pattern-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+};
+
 // ../../src/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
   breakers = /* @__PURE__ */ new Map();
@@ -1067,54 +1168,6 @@ var TtlResolver = class {
   }
 };
 
-// ../../src/invalidation/PatternMatcher.ts
-var PatternMatcher = class _PatternMatcher {
-  /**
-   * Tests whether a glob-style pattern matches a value.
-   * Supports `*` (any sequence of characters) and `?` (any single character).
-   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
-   * quadratic memory usage on long patterns/keys.
-   */
-  static matches(pattern, value) {
-    return _PatternMatcher.matchLinear(pattern, value);
-  }
-  /**
-   * Linear-time glob matching with O(1) extra memory.
-   */
-  static matchLinear(pattern, value) {
-    let patternIndex = 0;
-    let valueIndex = 0;
-    let starIndex = -1;
-    let backtrackValueIndex = 0;
-    while (valueIndex < value.length) {
-      const patternChar = pattern[patternIndex];
-      const valueChar = value[valueIndex];
-      if (patternChar === "*" && patternIndex < pattern.length) {
-        starIndex = patternIndex;
-        patternIndex += 1;
-        backtrackValueIndex = valueIndex;
-        continue;
-      }
-      if (patternChar === "?" || patternChar === valueChar) {
-        patternIndex += 1;
-        valueIndex += 1;
-        continue;
-      }
-      if (starIndex !== -1) {
-        patternIndex = starIndex + 1;
-        backtrackValueIndex += 1;
-        valueIndex = backtrackValueIndex;
-        continue;
-      }
-      return false;
-    }
-    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
-      patternIndex += 1;
-    }
-    return patternIndex === pattern.length;
-  }
-};
-
 // ../../src/invalidation/TagIndex.ts
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
@@ -1443,6 +1496,14 @@ var CacheStack = class extends EventEmitter {
     const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
+    this.keyDiscovery = new CacheKeyDiscovery({
+      layers: this.layers,
+      tagIndex: this.tagIndex,
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => {
+        await this.handleLayerFailure(layer, operation, error);
+      }
+    });
     if (!options.tagIndex && layers.some((layer) => layer.isLocal === false)) {
       this.logger.warn?.(
         "Using the default in-memory TagIndex with a shared cache layer only tracks keys seen by this process. Use RedisTagIndex for cross-instance tag invalidation."
@@ -1470,6 +1531,7 @@ var CacheStack = class extends EventEmitter {
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  keyDiscovery;
   fetchRateLimiter = new FetchRateLimiter();
   snapshotSerializer = new JsonSerializer();
   backgroundRefreshes = /* @__PURE__ */ new Map();
@@ -1820,14 +1882,14 @@ var CacheStack = class extends EventEmitter {
   }
   async invalidateByPattern(pattern) {
     await this.awaitStartup("invalidateByPattern");
-    const keys = await this.collectKeysMatchingPattern(this.qualifyPattern(pattern));
+    const keys = await this.keyDiscovery.collectKeysMatchingPattern(this.qualifyPattern(pattern));
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
   async invalidateByPrefix(prefix) {
     await this.awaitStartup("invalidateByPrefix");
     const qualifiedPrefix = this.qualifyKey(this.validateCacheKey(prefix));
-    const keys = await this.collectKeysWithPrefix(qualifiedPrefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -2440,50 +2502,6 @@ var CacheStack = class extends EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
   }
-  async collectKeysWithPrefix(prefix) {
-    const matches = new Set(
-      this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(prefix) : await this.tagIndex.matchPattern(`${prefix}*`)
-    );
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (key.startsWith(prefix)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-prefix-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
-  async collectKeysMatchingPattern(pattern) {
-    const matches = new Set(await this.tagIndex.matchPattern(pattern));
-    await Promise.all(
-      this.layers.map(async (layer) => {
-        if (!layer.keys || this.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          const keys = await layer.keys();
-          for (const key of keys) {
-            if (PatternMatcher.matches(pattern, key)) {
-              matches.add(key);
-            }
-          }
-        } catch (error) {
-          await this.handleLayerFailure(layer, "invalidate-pattern-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
   shouldCleanupGenerations() {
     return Boolean(this.options.generationCleanup);
   }
@@ -2506,7 +2524,7 @@ var CacheStack = class extends EventEmitter {
   }
   async cleanupGeneration(generation) {
     const prefix = `v${generation}:`;
-    const keys = await this.collectKeysWithPrefix(prefix);
+    const keys = await this.keyDiscovery.collectKeysWithPrefix(prefix);
     if (keys.length === 0) {
       return;
     }