layercache 3.0.0 → 3.1.0

package/README.md

@@ -19,8 +19,8 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-green" alt="license"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-first-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
   <img src="https://img.shields.io/badge/Node.js-%E2%89%A5_20-339933?logo=nodedotjs&logoColor=white" alt="Node.js >= 20">
-  <img src="https://img.shields.io/badge/tests-549_passing-brightgreen" alt="tests">
-  <a href="https://coveralls.io/github/flyingsquirrel0419/layercache?branch=main"><img src="https://coveralls.io/repos/github/flyingsquirrel0419/layercache/badge.svg?branch=main&t=20260410" alt="Coveralls"></a>
+  <img src="https://img.shields.io/badge/tests-598_passing-brightgreen" alt="tests">
+  <a href="https://coveralls.io/github/flyingsquirrel0419/layercache?branch=main"><img src="https://coveralls.io/repos/github/flyingsquirrel0419/layercache/badge.svg?branch=main&t=20260517" alt="Coveralls"></a>
 </p>
 
 <p align="center">
@@ -262,6 +262,8 @@ const cache = new CacheStack([
 | **Namespaces** | Scoped cache views with hierarchical prefix support |
 | **Cache warming** | Pre-populate layers at startup with priority-based loading |
 | **Negative caching** | Cache misses (e.g., "user not found") for short TTLs |
+| **Stored null values** | `cacheNullValues` keeps intentional `null` values distinct from misses |
+| **Entry introspection** | `getEntry()` reports value, kind, state, key, and source layer |
 
 ### Invalidation & Freshness
 
@@ -285,9 +287,11 @@ const cache = new CacheStack([
 |---|---|
 | **Graceful degradation** | Skip failed layers temporarily, keep cache available |
 | **Circuit breaker** | Stop hammering broken upstreams after repeated failures |
-| **Fetcher rate limiting** | Scoped to global, per-key, or per-fetcher with custom buckets |
+| **Shared circuit breaker scopes** | Group failures by backend dependency with `scope: 'shared'` and `breakerKey` |
+| **Fetcher rate limiting** | Scoped to global, per-key, or per-fetcher; `queueOverflow: 'reject'` rejects saturated queues and `'bypass'` runs overflow work directly |
 | **Write policies** | `strict` (fail if any layer fails) or `best-effort` |
 | **Write-behind** | Batch writes with configurable flush interval |
+| **Bounded disk writes** | `DiskLayer.maxWriteQueueDepth` prevents unbounded serialized write buildup |
 | **Compression** | gzip / brotli in RedisLayer with configurable threshold |
 | **MessagePack** | Pluggable serializers (JSON default, MessagePack alternative) |
 | **Persistence** | Export/import snapshots to memory or disk |

package/dist/{chunk-NBMG7DHT.js → chunk-L6L7QXYF.js}

@@ -41,9 +41,12 @@ function validateRateLimitOptions(name, options) {
   validatePositiveNumber(`${name}.maxConcurrent`, options.maxConcurrent);
   validatePositiveNumber(`${name}.intervalMs`, options.intervalMs);
   validatePositiveNumber(`${name}.maxPerInterval`, options.maxPerInterval);
-  if (options.scope && !["global", "key", "fetcher"].includes(options.scope)) {
+  if (options.scope !== void 0 && !["global", "key", "fetcher"].includes(options.scope)) {
     throw new Error(`${name}.scope must be one of "global", "key", or "fetcher".`);
   }
+  if (options.queueOverflow !== void 0 && !["reject", "bypass"].includes(options.queueOverflow)) {
+    throw new Error(`${name}.queueOverflow must be one of "reject" or "bypass".`);
+  }
   if (options.bucketKey !== void 0 && options.bucketKey.length === 0) {
     throw new Error(`${name}.bucketKey must not be empty.`);
   }
@@ -124,6 +127,12 @@ function validateCircuitBreakerOptions(options) {
   }
   validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
   validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
+  if (options.scope !== void 0 && !["key", "shared"].includes(options.scope)) {
+    throw new Error('circuitBreaker.scope must be one of "key" or "shared".');
+  }
+  if (options.breakerKey !== void 0 && options.breakerKey.length === 0) {
+    throw new Error("circuitBreaker.breakerKey must not be empty.");
+  }
 }
 function validateContextEntryOptions(name, options) {
   if (!options) {

package/dist/{chunk-5CIBABDH.js → chunk-XMUT66SH.js}

@@ -1,4 +1,5 @@
 import {
+  PatternMatcher,
   unwrapStoredValue
 } from "./chunk-KJDFYE5T.js";
 
@@ -245,30 +246,34 @@ var MemoryLayer = class {
 };
 
 // src/invalidation/TagIndex.ts
-var MAX_PATTERN_RECURSION_DEPTH = 500;
+var DEFAULT_TOUCH_REFRESH_INTERVAL_MS = 1e3;
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Map();
   maxKnownKeys;
+  touchRefreshIntervalMs;
   nextNodeId = 1;
   root = this.createTrieNode();
   constructor(options = {}) {
     this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
+    this.touchRefreshIntervalMs = options.touchRefreshIntervalMs ?? DEFAULT_TOUCH_REFRESH_INTERVAL_MS;
   }
   /**
    * Records a key as known without changing tag assignments.
    */
   async touch(key) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
+    if (this.insertKnownKey(key)) {
+      this.pruneKnownKeysIfNeeded();
+    }
   }
   /**
    * Replaces the tags associated with a key and records the key as known.
    */
   async track(key, tags) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
+    if (this.insertKnownKey(key)) {
+      this.pruneKnownKeysIfNeeded();
+    }
     if (tags.length === 0) {
       return;
     }
@@ -338,9 +343,14 @@ var TagIndex = class {
    * Returns known keys matching a wildcard pattern.
    */
   async matchPattern(pattern) {
-    const matches = /* @__PURE__ */ new Set();
-    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set(), 0);
-    return [...matches];
+    const literalPrefix = this.literalPrefix(pattern);
+    const node = this.findNode(literalPrefix);
+    if (!node) {
+      return [];
+    }
+    const candidates = [];
+    this.collectFromNode(node, literalPrefix, candidates);
+    return candidates.filter((key) => PatternMatcher.matches(pattern, key));
   }
   /**
    * Visits known keys matching a wildcard pattern.
@@ -370,13 +380,18 @@ var TagIndex = class {
     };
   }
   insertKnownKey(key) {
-    const isNew = !this.knownKeys.has(key);
+    const previousTouch = this.knownKeys.get(key);
+    const isNew = previousTouch === void 0;
+    const now = Date.now();
+    if (!isNew && now - previousTouch < this.touchRefreshIntervalMs) {
+      return false;
+    }
     if (!isNew) {
       this.knownKeys.delete(key);
     }
-    this.knownKeys.set(key, Date.now());
+    this.knownKeys.set(key, now);
     if (!isNew) {
-      return;
+      return true;
     }
     let node = this.root;
     for (const character of key) {
@@ -388,6 +403,7 @@ var TagIndex = class {
       node = child;
     }
     node.terminal = true;
+    return true;
   }
   findNode(prefix) {
     let node = this.root;
@@ -400,74 +416,41 @@ var TagIndex = class {
     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);
+    const stack = [{ node, prefix }];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (!current) {
+        continue;
+      }
+      if (current.node.terminal) {
+        matches.push(current.prefix);
+      }
+      const children = [...current.node.children].reverse();
+      for (const [character, child] of children) {
+        stack.push({ node: child, prefix: `${current.prefix}${character}` });
+      }
     }
   }
   async visitFromNode(node, prefix, visitor) {
-    if (node.terminal) {
-      await visitor(prefix);
-    }
-    for (const [character, child] of node.children) {
-      await this.visitFromNode(child, `${prefix}${character}`, visitor);
-    }
-  }
-  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited, depth) {
-    if (depth > MAX_PATTERN_RECURSION_DEPTH) {
-      return;
-    }
-    const stateKey = `${node.id}:${patternIndex}`;
-    if (visited.has(stateKey)) {
-      return;
-    }
-    visited.add(stateKey);
-    if (patternIndex === pattern.length) {
-      if (node.terminal) {
-        matches.add(prefix);
+    const stack = [{ node, prefix }];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (!current) {
+        continue;
       }
-      return;
-    }
-    const patternChar = pattern[patternIndex];
-    if (patternChar === void 0) {
-      return;
-    }
-    if (patternChar === "*") {
-      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited, depth + 1);
-      for (const [character, child2] of node.children) {
-        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited, depth + 1);
+      if (current.node.terminal) {
+        await visitor(current.prefix);
       }
-      return;
-    }
-    if (patternChar === "?") {
-      for (const [character, child2] of node.children) {
-        this.collectPatternMatches(
-          child2,
-          `${prefix}${character}`,
-          pattern,
-          patternIndex + 1,
-          matches,
-          visited,
-          depth + 1
-        );
+      const children = [...current.node.children].reverse();
+      for (const [character, child] of children) {
+        stack.push({ node: child, prefix: `${current.prefix}${character}` });
       }
-      return;
-    }
-    const child = node.children.get(patternChar);
-    if (child) {
-      this.collectPatternMatches(
-        child,
-        `${prefix}${patternChar}`,
-        pattern,
-        patternIndex + 1,
-        matches,
-        visited,
-        depth + 1
-      );
     }
   }
+  literalPrefix(pattern) {
+    const wildcardIndex = pattern.search(/[*?]/);
+    return wildcardIndex === -1 ? pattern : pattern.slice(0, wildcardIndex);
+  }
   pruneKnownKeysIfNeeded() {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
       return;

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   validateCacheKey,
   validatePattern,
   validateTag
-} from "./chunk-NBMG7DHT.js";
+} from "./chunk-L6L7QXYF.js";
 import {
   isStoredValueEnvelope,
   resolveStoredValue

package/dist/{edge-BDyuPmIq.d.cts → edge-LBUuZAdr.d.cts}

@@ -47,6 +47,8 @@ interface CacheContextOptionsContext {
 interface CacheWriteOptions extends CacheEntryWriteOptions {
     /** Cache `null` fetcher results using `negativeTtl` instead of treating them as misses. */
     negativeCache?: boolean;
+    /** Cache `null` fetcher results as regular values instead of negative/empty entries. */
+    cacheNullValues?: boolean;
     /** Extend a key's TTL on fresh reads. */
     slidingTtl?: boolean;
     /** Refresh in the background when the remaining TTL is at or below this threshold in milliseconds. */
@@ -71,6 +73,7 @@ interface CacheWriteOptions extends CacheEntryWriteOptions {
      *
      * Returned values override any static entry options already present on the
      * same object. Fetch controls like `shouldCache`, `negativeCache`,
+     * `cacheNullValues`,
      * `refreshAhead`, or `circuitBreaker` are not affected.
      *
      * @example
@@ -340,6 +343,8 @@ interface CacheStackOptions {
     publishSetInvalidation?: boolean;
     /** Cache null fetcher results as negative entries. */
     negativeCaching?: boolean;
+    /** Cache null fetcher results as regular values instead of negative/empty entries. */
+    cacheNullValues?: boolean;
     /** Default negative-cache TTL in milliseconds. */
     negativeTtl?: number | LayerTtlMap;
     /** Default stale-while-revalidate window in milliseconds. */
@@ -422,6 +427,13 @@ interface CacheCircuitBreakerOptions {
     failureThreshold?: number;
     /** Milliseconds before an open circuit allows another attempt. */
     cooldownMs?: number;
+    /**
+     * Failure scope. `key` preserves the historical per-cache-key behavior.
+     * `shared` uses one breaker for all fetches using these options.
+     */
+    scope?: 'key' | 'shared';
+    /** Custom breaker id for grouping related fetches, such as one backend dependency. */
+    breakerKey?: string;
 }
 /** Graceful degradation settings for temporarily unhealthy layers. */
 interface CacheDegradationOptions {
@@ -440,6 +452,11 @@ interface CacheRateLimitOptions {
     scope?: 'global' | 'key' | 'fetcher';
     /** Custom bucket id used to group otherwise unrelated fetches. */
     bucketKey?: string;
+    /**
+     * Behavior when a bucket queue reaches its internal safety limit.
+     * Defaults to `reject` so overflow is explicit instead of bypassing limits.
+     */
+    queueOverflow?: 'reject' | 'bypass';
 }
 /** Queue controls for write-behind mode. */
 interface CacheWriteBehindOptions {
@@ -539,6 +556,19 @@ interface CacheInspectResult {
     /** Tags associated with this key (from the TagIndex). */
     tags: string[];
 }
+/** Cached entry result that can distinguish a stored `null` from a miss. */
+interface CacheEntryResult<T = unknown> {
+    /** User-facing cache key. */
+    key: string;
+    /** Unwrapped cached value. May be `null` when `kind` is `value` or `empty`. */
+    value: T | null;
+    /** Whether this entry stores a normal value or a negative-cache empty marker. */
+    kind: 'value' | 'empty';
+    /** Fresh/stale state currently available for this entry. */
+    state: 'fresh' | 'stale-while-revalidate' | 'stale-if-error';
+    /** First layer that supplied the entry. */
+    layer: string;
+}
 /** All events emitted by CacheStack and their payload shapes. */
 interface CacheStackEvents {
     /** Fired on every cache hit. */
@@ -746,12 +776,18 @@ interface TagIndexOptions {
      * Defaults to 100,000.
      */
     maxKnownKeys?: number;
+    /**
+     * Minimum age before an existing key touch refreshes LRU order.
+     * Defaults to 1000ms to avoid delete/set churn on cache-hit hot paths.
+     */
+    touchRefreshIntervalMs?: number;
 }
 declare class TagIndex implements CacheTagIndex {
     private readonly tagToKeys;
     private readonly keyToTags;
     private readonly knownKeys;
     private readonly maxKnownKeys;
+    private readonly touchRefreshIntervalMs;
     private nextNodeId;
     private readonly root;
     constructor(options?: TagIndexOptions);
@@ -804,7 +840,7 @@ declare class TagIndex implements CacheTagIndex {
     private findNode;
     private collectFromNode;
     private visitFromNode;
-    private collectPatternMatches;
+    private literalPrefix;
     private pruneKnownKeysIfNeeded;
     private removeKey;
     private removeKnownKey;
@@ -834,6 +870,11 @@ declare class CacheNamespace {
      * Alias for `get(key, fetcher, options)` that makes the get-or-set behavior explicit.
      */
     getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Returns a namespaced cache entry, or `null` on miss.
+     * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+     */
+    getEntry<T>(key: string): Promise<CacheEntryResult<T> | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      */
@@ -1024,6 +1065,11 @@ declare class CacheStack extends EventEmitter {
      * Fetches and caches the value if not already present.
      */
     getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Returns a discriminated cache entry, or `null` on miss.
+     * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+     */
+    getEntry<T>(key: string): Promise<CacheEntryResult<T> | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      * Useful when the value is expected to exist or the fetcher is expected to
@@ -1139,6 +1185,14 @@ declare class CacheStack extends EventEmitter {
      * Returns cumulative cache metrics since startup or the last `resetMetrics()`.
      */
     getMetrics(): CacheMetricsSnapshot;
+    /**
+     * Runs an operation while collecting only the metrics emitted by its async context.
+     * Used by namespaces so metrics tracking does not serialize the operation itself.
+     */
+    captureMetrics<T>(operation: () => Promise<T>): Promise<{
+        result: T;
+        metrics: CacheMetricsSnapshot;
+    }>;
     /**
      * Returns metrics plus layer degradation state and active background refresh count.
      */
@@ -1269,4 +1323,4 @@ interface HonoCacheMiddlewareOptions extends CacheGetOptions {
  */
 declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<unknown>;
 
-export { CacheNamespace as A, type CacheRateLimitOptions as B, type CacheLogger as C, type CacheSnapshotEntry as D, type CacheStackEvents as E, type CacheStackOptions as F, type CacheStatsSnapshot as G, type CacheTtlPolicy as H, type InvalidationBus as I, type CacheTtlPolicyContext as J, type CacheWarmEntry as K, type CacheWarmOptions as L, type CacheWarmProgress as M, type CacheWriteBehindOptions as N, type CacheWriteOptions as O, type EvictionPolicy as P, type LayerTtlMap as Q, MemoryLayer as R, type MemoryLayerOptions as S, type MemoryLayerSnapshotEntry as T, PatternMatcher as U, TagIndex as V, createHonoCacheMiddleware as W, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheContextOptionsContext as m, type CacheDegradationOptions as n, type CacheEntryWriteKind as o, type CacheEntryWriteOptions as p, type CacheFetcher as q, type CacheFetcherContext as r, type CacheHealthCheckResult as s, type CacheHitRateSnapshot as t, type CacheInspectResult as u, type CacheLayerLatency as v, type CacheMGetEntry as w, type CacheMSetEntry as x, type CacheMetricsSnapshot as y, CacheMissError as z };
+export { CacheMissError as A, CacheNamespace as B, type CacheLogger as C, type CacheRateLimitOptions as D, type CacheSnapshotEntry as E, type CacheStackEvents as F, type CacheStackOptions as G, type CacheStatsSnapshot as H, type InvalidationBus as I, type CacheTtlPolicy as J, type CacheTtlPolicyContext as K, type CacheWarmEntry as L, type CacheWarmOptions as M, type CacheWarmProgress as N, type CacheWriteBehindOptions as O, type CacheWriteOptions as P, type EvictionPolicy as Q, type LayerTtlMap as R, MemoryLayer as S, type MemoryLayerOptions as T, type MemoryLayerSnapshotEntry as U, PatternMatcher as V, TagIndex as W, createHonoCacheMiddleware as X, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheContextOptionsContext as m, type CacheDegradationOptions as n, type CacheEntryResult as o, type CacheEntryWriteKind as p, type CacheEntryWriteOptions as q, type CacheFetcher as r, type CacheFetcherContext as s, type CacheHealthCheckResult as t, type CacheHitRateSnapshot as u, type CacheInspectResult as v, type CacheLayerLatency as w, type CacheMGetEntry as x, type CacheMSetEntry as y, type CacheMetricsSnapshot as z };

package/dist/{edge-BDyuPmIq.d.ts → edge-LBUuZAdr.d.ts}

@@ -47,6 +47,8 @@ interface CacheContextOptionsContext {
 interface CacheWriteOptions extends CacheEntryWriteOptions {
     /** Cache `null` fetcher results using `negativeTtl` instead of treating them as misses. */
     negativeCache?: boolean;
+    /** Cache `null` fetcher results as regular values instead of negative/empty entries. */
+    cacheNullValues?: boolean;
     /** Extend a key's TTL on fresh reads. */
     slidingTtl?: boolean;
     /** Refresh in the background when the remaining TTL is at or below this threshold in milliseconds. */
@@ -71,6 +73,7 @@ interface CacheWriteOptions extends CacheEntryWriteOptions {
      *
      * Returned values override any static entry options already present on the
      * same object. Fetch controls like `shouldCache`, `negativeCache`,
+     * `cacheNullValues`,
      * `refreshAhead`, or `circuitBreaker` are not affected.
      *
      * @example
@@ -340,6 +343,8 @@ interface CacheStackOptions {
     publishSetInvalidation?: boolean;
     /** Cache null fetcher results as negative entries. */
     negativeCaching?: boolean;
+    /** Cache null fetcher results as regular values instead of negative/empty entries. */
+    cacheNullValues?: boolean;
     /** Default negative-cache TTL in milliseconds. */
     negativeTtl?: number | LayerTtlMap;
     /** Default stale-while-revalidate window in milliseconds. */
@@ -422,6 +427,13 @@ interface CacheCircuitBreakerOptions {
     failureThreshold?: number;
     /** Milliseconds before an open circuit allows another attempt. */
     cooldownMs?: number;
+    /**
+     * Failure scope. `key` preserves the historical per-cache-key behavior.
+     * `shared` uses one breaker for all fetches using these options.
+     */
+    scope?: 'key' | 'shared';
+    /** Custom breaker id for grouping related fetches, such as one backend dependency. */
+    breakerKey?: string;
 }
 /** Graceful degradation settings for temporarily unhealthy layers. */
 interface CacheDegradationOptions {
@@ -440,6 +452,11 @@ interface CacheRateLimitOptions {
     scope?: 'global' | 'key' | 'fetcher';
     /** Custom bucket id used to group otherwise unrelated fetches. */
     bucketKey?: string;
+    /**
+     * Behavior when a bucket queue reaches its internal safety limit.
+     * Defaults to `reject` so overflow is explicit instead of bypassing limits.
+     */
+    queueOverflow?: 'reject' | 'bypass';
 }
 /** Queue controls for write-behind mode. */
 interface CacheWriteBehindOptions {
@@ -539,6 +556,19 @@ interface CacheInspectResult {
     /** Tags associated with this key (from the TagIndex). */
     tags: string[];
 }
+/** Cached entry result that can distinguish a stored `null` from a miss. */
+interface CacheEntryResult<T = unknown> {
+    /** User-facing cache key. */
+    key: string;
+    /** Unwrapped cached value. May be `null` when `kind` is `value` or `empty`. */
+    value: T | null;
+    /** Whether this entry stores a normal value or a negative-cache empty marker. */
+    kind: 'value' | 'empty';
+    /** Fresh/stale state currently available for this entry. */
+    state: 'fresh' | 'stale-while-revalidate' | 'stale-if-error';
+    /** First layer that supplied the entry. */
+    layer: string;
+}
 /** All events emitted by CacheStack and their payload shapes. */
 interface CacheStackEvents {
     /** Fired on every cache hit. */
@@ -746,12 +776,18 @@ interface TagIndexOptions {
      * Defaults to 100,000.
      */
     maxKnownKeys?: number;
+    /**
+     * Minimum age before an existing key touch refreshes LRU order.
+     * Defaults to 1000ms to avoid delete/set churn on cache-hit hot paths.
+     */
+    touchRefreshIntervalMs?: number;
 }
 declare class TagIndex implements CacheTagIndex {
     private readonly tagToKeys;
     private readonly keyToTags;
     private readonly knownKeys;
     private readonly maxKnownKeys;
+    private readonly touchRefreshIntervalMs;
     private nextNodeId;
     private readonly root;
     constructor(options?: TagIndexOptions);
@@ -804,7 +840,7 @@ declare class TagIndex implements CacheTagIndex {
     private findNode;
     private collectFromNode;
     private visitFromNode;
-    private collectPatternMatches;
+    private literalPrefix;
     private pruneKnownKeysIfNeeded;
     private removeKey;
     private removeKnownKey;
@@ -834,6 +870,11 @@ declare class CacheNamespace {
      * Alias for `get(key, fetcher, options)` that makes the get-or-set behavior explicit.
      */
     getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Returns a namespaced cache entry, or `null` on miss.
+     * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+     */
+    getEntry<T>(key: string): Promise<CacheEntryResult<T> | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      */
@@ -1024,6 +1065,11 @@ declare class CacheStack extends EventEmitter {
      * Fetches and caches the value if not already present.
      */
     getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Returns a discriminated cache entry, or `null` on miss.
+     * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+     */
+    getEntry<T>(key: string): Promise<CacheEntryResult<T> | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      * Useful when the value is expected to exist or the fetcher is expected to
@@ -1139,6 +1185,14 @@ declare class CacheStack extends EventEmitter {
      * Returns cumulative cache metrics since startup or the last `resetMetrics()`.
      */
     getMetrics(): CacheMetricsSnapshot;
+    /**
+     * Runs an operation while collecting only the metrics emitted by its async context.
+     * Used by namespaces so metrics tracking does not serialize the operation itself.
+     */
+    captureMetrics<T>(operation: () => Promise<T>): Promise<{
+        result: T;
+        metrics: CacheMetricsSnapshot;
+    }>;
     /**
      * Returns metrics plus layer degradation state and active background refresh count.
      */
@@ -1269,4 +1323,4 @@ interface HonoCacheMiddlewareOptions extends CacheGetOptions {
  */
 declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<unknown>;
 
-export { CacheNamespace as A, type CacheRateLimitOptions as B, type CacheLogger as C, type CacheSnapshotEntry as D, type CacheStackEvents as E, type CacheStackOptions as F, type CacheStatsSnapshot as G, type CacheTtlPolicy as H, type InvalidationBus as I, type CacheTtlPolicyContext as J, type CacheWarmEntry as K, type CacheWarmOptions as L, type CacheWarmProgress as M, type CacheWriteBehindOptions as N, type CacheWriteOptions as O, type EvictionPolicy as P, type LayerTtlMap as Q, MemoryLayer as R, type MemoryLayerOptions as S, type MemoryLayerSnapshotEntry as T, PatternMatcher as U, TagIndex as V, createHonoCacheMiddleware as W, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheContextOptionsContext as m, type CacheDegradationOptions as n, type CacheEntryWriteKind as o, type CacheEntryWriteOptions as p, type CacheFetcher as q, type CacheFetcherContext as r, type CacheHealthCheckResult as s, type CacheHitRateSnapshot as t, type CacheInspectResult as u, type CacheLayerLatency as v, type CacheMGetEntry as w, type CacheMSetEntry as x, type CacheMetricsSnapshot as y, CacheMissError as z };
+export { CacheMissError as A, CacheNamespace as B, type CacheLogger as C, type CacheRateLimitOptions as D, type CacheSnapshotEntry as E, type CacheStackEvents as F, type CacheStackOptions as G, type CacheStatsSnapshot as H, type InvalidationBus as I, type CacheTtlPolicy as J, type CacheTtlPolicyContext as K, type CacheWarmEntry as L, type CacheWarmOptions as M, type CacheWarmProgress as N, type CacheWriteBehindOptions as O, type CacheWriteOptions as P, type EvictionPolicy as Q, type LayerTtlMap as R, MemoryLayer as S, type MemoryLayerOptions as T, type MemoryLayerSnapshotEntry as U, PatternMatcher as V, TagIndex as W, createHonoCacheMiddleware as X, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheContextOptionsContext as m, type CacheDegradationOptions as n, type CacheEntryResult as o, type CacheEntryWriteKind as p, type CacheEntryWriteOptions as q, type CacheFetcher as r, type CacheFetcherContext as s, type CacheHealthCheckResult as t, type CacheHitRateSnapshot as u, type CacheInspectResult as v, type CacheLayerLatency as w, type CacheMGetEntry as x, type CacheMSetEntry as y, type CacheMetricsSnapshot as z };