layercache 1.2.2 → 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-164%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
-- **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 ≥ 18
+### 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,9 +173,11 @@ 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.
+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'] })
@@ -193,12 +197,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.
@@ -280,6 +286,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.
@@ -482,10 +499,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
@@ -510,6 +527,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.
@@ -622,6 +641,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
@@ -718,6 +739,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
@@ -744,9 +767,11 @@ cache.on('error', ({ event, context }) => logger.error(event, context))
 
 ---
 
-## Framework integrations
+## Integrations & tooling
+
+### Framework integrations
 
-### Express
+#### Express
 
 ```ts
 import { CacheStack, MemoryLayer, createExpressCacheMiddleware } from 'layercache'
@@ -766,7 +791,7 @@ app.get('/api/user/:id', createExpressCacheMiddleware(cache, {
 }), handler)
 ```
 
-### tRPC
+#### tRPC
 
 ```ts
 import { createTrpcCacheMiddleware } from 'layercache/integrations/trpc'
@@ -776,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'
@@ -793,7 +818,7 @@ const resolvers = {
 
 ---
 
-## Admin CLI
+### Admin CLI
 
 Inspect and manage a Redis-backed cache without writing code.
 
@@ -1019,7 +1044,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`)
 
@@ -1027,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/{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-IXCMHVHP.js → chunk-QHWG7QS5.js}

@@ -1,6 +1,6 @@
 import {
   PatternMatcher
-} from "./chunk-ZMDB5KOK.js";
+} from "./chunk-7V7XAB74.js";
 
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {