layercache 1.1.0 → 1.2.0

package/package.json

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

package/packages/nestjs/dist/index.cjs

@@ -77,7 +77,7 @@ var import_node_events = require("events");
 var import_node_fs = require("fs");
 
 // ../../src/CacheNamespace.ts
-var CacheNamespace = class {
+var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
     this.prefix = prefix;
@@ -90,6 +90,12 @@ var CacheNamespace = class {
   async getOrSet(key, fetcher, options) {
     return this.cache.getOrSet(this.qualify(key), fetcher, options);
   }
+  /**
+   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+   */
+  async getOrThrow(key, fetcher, options) {
+    return this.cache.getOrThrow(this.qualify(key), fetcher, options);
+  }
   async has(key) {
     return this.cache.has(this.qualify(key));
   }
@@ -130,6 +136,12 @@ var CacheNamespace = class {
   async invalidateByPattern(pattern) {
     await this.cache.invalidateByPattern(this.qualify(pattern));
   }
+  /**
+   * Returns detailed metadata about a single cache key within this namespace.
+   */
+  async inspect(key) {
+    return this.cache.inspect(this.qualify(key));
+  }
   wrap(keyPrefix, fetcher, options) {
     return this.cache.wrap(`${this.prefix}:${keyPrefix}`, fetcher, options);
   }
@@ -148,6 +160,18 @@ var CacheNamespace = class {
   getHitRate() {
     return this.cache.getHitRate();
   }
+  /**
+   * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
+   *
+   * ```ts
+   * const tenant = cache.namespace('tenant:abc')
+   * const posts = tenant.namespace('posts')
+   * // keys become: "tenant:abc:posts:mykey"
+   * ```
+   */
+  namespace(childPrefix) {
+    return new _CacheNamespace(this.cache, `${this.prefix}:${childPrefix}`);
+  }
   qualify(key) {
     return `${this.prefix}:${key}`;
   }
@@ -249,7 +273,12 @@ var CircuitBreakerManager = class {
 var MetricsCollector = class {
   data = this.empty();
   get snapshot() {
-    return { ...this.data };
+    return {
+      ...this.data,
+      hitsByLayer: { ...this.data.hitsByLayer },
+      missesByLayer: { ...this.data.missesByLayer },
+      latencyByLayer: Object.fromEntries(Object.entries(this.data.latencyByLayer).map(([k, v]) => [k, { ...v }]))
+    };
   }
   increment(field, amount = 1) {
     ;
@@ -258,6 +287,22 @@ var MetricsCollector = class {
   incrementLayer(map, layerName) {
     this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
   }
+  /**
+   * Records a read latency sample for the given layer.
+   * Maintains a rolling average and max using Welford's online algorithm.
+   */
+  recordLatency(layerName, durationMs) {
+    const existing = this.data.latencyByLayer[layerName];
+    if (!existing) {
+      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
+      return;
+    }
+    existing.count += 1;
+    existing.avgMs += (durationMs - existing.avgMs) / existing.count;
+    if (durationMs > existing.maxMs) {
+      existing.maxMs = durationMs;
+    }
+  }
   reset() {
     this.data = this.empty();
   }
@@ -292,6 +337,7 @@ var MetricsCollector = class {
       degradedOperations: 0,
       hitsByLayer: {},
       missesByLayer: {},
+      latencyByLayer: {},
       resetAt: Date.now()
     };
   }
@@ -529,11 +575,17 @@ var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Set();
+  maxKnownKeys;
+  constructor(options = {}) {
+    this.maxKnownKeys = options.maxKnownKeys;
+  }
   async touch(key) {
     this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
   }
   async track(key, tags) {
     this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
     if (tags.length === 0) {
       return;
     }
@@ -572,6 +624,9 @@ var TagIndex = class {
   async keysForTag(tag) {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
+  async tagsForKey(key) {
+    return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
+  }
   async matchPattern(pattern) {
     return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
   }
@@ -580,6 +635,21 @@ var TagIndex = class {
     this.keyToTags.clear();
     this.knownKeys.clear();
   }
+  pruneKnownKeysIfNeeded() {
+    if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
+      return;
+    }
+    const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
+    let removed = 0;
+    for (const key of this.knownKeys) {
+      if (removed >= toRemove) {
+        break;
+      }
+      this.knownKeys.delete(key);
+      this.keyToTags.delete(key);
+      removed += 1;
+    }
+  }
 };
 
 // ../../node_modules/async-mutex/index.mjs
@@ -782,6 +852,16 @@ var StampedeGuard = class {
   }
 };
 
+// ../../src/types.ts
+var CacheMissError = class extends Error {
+  key;
+  constructor(key) {
+    super(`Cache miss for key "${key}".`);
+    this.name = "CacheMissError";
+    this.key = key;
+  }
+};
+
 // ../../src/CacheStack.ts
 var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
@@ -908,6 +988,18 @@ var CacheStack = class extends import_node_events.EventEmitter {
   async getOrSet(key, fetcher, options) {
     return this.get(key, fetcher, options);
   }
+  /**
+   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+   * Useful when the value is expected to exist or the fetcher is expected to
+   * return non-null.
+   */
+  async getOrThrow(key, fetcher, options) {
+    const value = await this.get(key, fetcher, options);
+    if (value === null) {
+      throw new CacheMissError(key);
+    }
+    return value;
+  }
   /**
    * Returns true if the given key exists and is not expired in any layer.
    */
@@ -1181,6 +1273,46 @@ var CacheStack = class extends import_node_events.EventEmitter {
   getHitRate() {
     return this.metricsCollector.hitRate();
   }
+  /**
+   * Returns detailed metadata about a single cache key: which layers contain it,
+   * remaining fresh/stale/error TTLs, and associated tags.
+   * Returns `null` if the key does not exist in any layer.
+   */
+  async inspect(key) {
+    const normalizedKey = this.validateCacheKey(key);
+    await this.startup;
+    const foundInLayers = [];
+    let freshTtlSeconds = null;
+    let staleTtlSeconds = null;
+    let errorTtlSeconds = null;
+    let isStale = false;
+    for (const layer of this.layers) {
+      if (this.shouldSkipLayer(layer)) {
+        continue;
+      }
+      const stored = await this.readLayerEntry(layer, normalizedKey);
+      if (stored === null) {
+        continue;
+      }
+      const resolved = resolveStoredValue(stored);
+      if (resolved.state === "expired") {
+        continue;
+      }
+      foundInLayers.push(layer.name);
+      if (foundInLayers.length === 1 && resolved.envelope) {
+        const now = Date.now();
+        freshTtlSeconds = resolved.envelope.freshUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.freshUntil - now) / 1e3)) : null;
+        staleTtlSeconds = resolved.envelope.staleUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.staleUntil - now) / 1e3)) : null;
+        errorTtlSeconds = resolved.envelope.errorUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.errorUntil - now) / 1e3)) : null;
+        isStale = resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error";
+      }
+    }
+    if (foundInLayers.length === 0) {
+      return null;
+    }
+    const tags = await this.getTagsForKey(normalizedKey);
+    return { key: normalizedKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
+  }
   async exportState() {
     await this.startup;
     const exported = /* @__PURE__ */ new Map();
@@ -1317,6 +1449,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.storeEntry(key, "empty", null, options);
       return null;
     }
+    if (options?.shouldCache && !options.shouldCache(fetched)) {
+      return fetched;
+    }
     await this.storeEntry(key, "value", fetched, options);
     return fetched;
   }
@@ -1339,7 +1474,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
     for (let index = 0; index < this.layers.length; index += 1) {
       const layer = this.layers[index];
       if (!layer) continue;
+      const readStart = performance.now();
       const stored = await this.readLayerEntry(layer, key);
+      const readDuration = performance.now() - readStart;
+      this.metricsCollector.recordLatency(layer.name, readDuration);
       if (stored === null) {
         this.metricsCollector.incrementLayer("missesByLayer", layer.name);
         continue;
@@ -1541,6 +1679,12 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
     }
   }
+  async getTagsForKey(key) {
+    if (this.tagIndex.tagsForKey) {
+      return this.tagIndex.tagsForKey(key);
+    }
+    return [];
+  }
   formatError(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1771,6 +1915,22 @@ var CacheStackModule = class {
       exports: [provider]
     };
   }
+  static forRootAsync(options) {
+    const provider = {
+      provide: CACHE_STACK,
+      inject: options.inject ?? [],
+      useFactory: async (...args) => {
+        const resolved = await options.useFactory(...args);
+        return new CacheStack(resolved.layers, resolved.bridgeOptions);
+      }
+    };
+    return {
+      global: true,
+      module: CacheStackModule,
+      providers: [provider],
+      exports: [provider]
+    };
+  }
 };
 CacheStackModule = __decorateClass([
   (0, import_common.Global)(),

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

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import { DynamicModule } from '@nestjs/common';
+import { DynamicModule, Type } from '@nestjs/common';
 
 declare const CACHE_STACK: unique symbol;
 
@@ -18,6 +18,15 @@ interface CacheWriteOptions {
     refreshAhead?: number | LayerTtlMap;
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
+    /**
+     * Optional predicate called with the fetcher's return value before caching.
+     * Return `false` to skip storing the value in the cache (but still return it
+     * to the caller). Useful for not caching failed API responses or empty results.
+     *
+     * @example
+     * cache.get('key', fetchData, { shouldCache: (v) => v.status === 200 })
+     */
+    shouldCache?: (value: unknown) => boolean;
 }
 interface CacheGetOptions extends CacheWriteOptions {
 }
@@ -61,6 +70,15 @@ interface CacheLayer {
      */
     size?(): Promise<number>;
 }
+/** Per-layer latency statistics (rolling window of sampled read durations). */
+interface CacheLayerLatency {
+    /** Average read latency in milliseconds. */
+    avgMs: number;
+    /** Maximum observed read latency in milliseconds. */
+    maxMs: number;
+    /** Number of samples used to compute the statistics. */
+    count: number;
+}
 /** Snapshot of cumulative cache counters. */
 interface CacheMetricsSnapshot {
     hits: number;
@@ -80,6 +98,8 @@ interface CacheMetricsSnapshot {
     degradedOperations: number;
     hitsByLayer: Record<string, number>;
     missesByLayer: Record<string, number>;
+    /** Per-layer read latency statistics (sampled from successful reads). */
+    latencyByLayer: Record<string, CacheLayerLatency>;
     /** Timestamp (ms since epoch) when metrics were last reset. */
     resetAt: number;
 }
@@ -101,6 +121,8 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    /** Returns the tags associated with a specific key, or an empty array. */
+    tagsForKey?(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
 }
@@ -203,6 +225,22 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+/** Detailed inspection result for a single cache key. */
+interface CacheInspectResult {
+    key: string;
+    /** Layers in which the key is currently stored (not expired). */
+    foundInLayers: string[];
+    /** Remaining fresh TTL in seconds, or null if no expiry or not an envelope. */
+    freshTtlSeconds: number | null;
+    /** Remaining stale-while-revalidate window in seconds, or null. */
+    staleTtlSeconds: number | null;
+    /** Remaining stale-if-error window in seconds, or null. */
+    errorTtlSeconds: number | null;
+    /** Whether the key is currently serving stale-while-revalidate. */
+    isStale: boolean;
+    /** Tags associated with this key (from the TagIndex). */
+    tags: string[];
+}
 /** All events emitted by CacheStack and their payload shapes. */
 interface CacheStackEvents {
     /** Fired on every cache hit. */
@@ -258,6 +296,10 @@ declare class CacheNamespace {
     constructor(cache: CacheStack, prefix: string);
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
     getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+     */
+    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
     has(key: string): Promise<boolean>;
     ttl(key: string): Promise<number | null>;
     set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
@@ -268,10 +310,24 @@ declare class CacheNamespace {
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    /**
+     * Returns detailed metadata about a single cache key within this namespace.
+     */
+    inspect(key: string): Promise<CacheInspectResult | null>;
     wrap<TArgs extends unknown[], TResult>(keyPrefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
     warm(entries: CacheWarmEntry[], options?: CacheWarmOptions): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getHitRate(): CacheHitRateSnapshot;
+    /**
+     * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
+     *
+     * ```ts
+     * const tenant = cache.namespace('tenant:abc')
+     * const posts = tenant.namespace('posts')
+     * // keys become: "tenant:abc:posts:mykey"
+     * ```
+     */
+    namespace(childPrefix: string): CacheNamespace;
     qualify(key: string): string;
 }
 
@@ -311,6 +367,12 @@ declare class CacheStack extends EventEmitter {
      * Fetches and caches the value if not already present.
      */
     getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<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
+     * return non-null.
+     */
+    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
     /**
      * Returns true if the given key exists and is not expired in any layer.
      */
@@ -355,6 +417,12 @@ declare class CacheStack extends EventEmitter {
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    /**
+     * Returns detailed metadata about a single cache key: which layers contain it,
+     * remaining fresh/stale/error TTLs, and associated tags.
+     * Returns `null` if the key does not exist in any layer.
+     */
+    inspect(key: string): Promise<CacheInspectResult | null>;
     exportState(): Promise<CacheSnapshotEntry[]>;
     importState(entries: CacheSnapshotEntry[]): Promise<void>;
     persistToFile(filePath: string): Promise<void>;
@@ -378,6 +446,7 @@ declare class CacheStack extends EventEmitter {
     private deleteKeys;
     private publishInvalidation;
     private handleInvalidationMessage;
+    private getTagsForKey;
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
@@ -413,9 +482,31 @@ interface CacheStackModuleOptions {
     layers: CacheLayer[];
     bridgeOptions?: CacheStackOptions;
 }
+interface CacheStackModuleAsyncOptions {
+    /**
+     * Tokens to inject into the `useFactory` function.
+     */
+    inject?: Array<Type | string | symbol>;
+    /**
+     * Async factory function that returns `CacheStackModuleOptions`.
+     * Useful when the Redis client or other dependencies must be resolved
+     * from the NestJS DI container first.
+     *
+     * ```ts
+     * CacheStackModule.forRootAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config: ConfigService) => ({
+     *     layers: [new MemoryLayer(), new RedisLayer({ client: createRedis(config) })],
+     *   })
+     * })
+     * ```
+     */
+    useFactory: (...args: unknown[]) => CacheStackModuleOptions | Promise<CacheStackModuleOptions>;
+}
 declare const InjectCacheStack: () => ParameterDecorator & PropertyDecorator;
 declare class CacheStackModule {
     static forRoot(options: CacheStackModuleOptions): DynamicModule;
+    static forRootAsync(options: CacheStackModuleAsyncOptions): DynamicModule;
 }
 
 export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, Cacheable, InjectCacheStack };

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

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import { DynamicModule } from '@nestjs/common';
+import { DynamicModule, Type } from '@nestjs/common';
 
 declare const CACHE_STACK: unique symbol;
 
@@ -18,6 +18,15 @@ interface CacheWriteOptions {
     refreshAhead?: number | LayerTtlMap;
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
+    /**
+     * Optional predicate called with the fetcher's return value before caching.
+     * Return `false` to skip storing the value in the cache (but still return it
+     * to the caller). Useful for not caching failed API responses or empty results.
+     *
+     * @example
+     * cache.get('key', fetchData, { shouldCache: (v) => v.status === 200 })
+     */
+    shouldCache?: (value: unknown) => boolean;
 }
 interface CacheGetOptions extends CacheWriteOptions {
 }
@@ -61,6 +70,15 @@ interface CacheLayer {
      */
     size?(): Promise<number>;
 }
+/** Per-layer latency statistics (rolling window of sampled read durations). */
+interface CacheLayerLatency {
+    /** Average read latency in milliseconds. */
+    avgMs: number;
+    /** Maximum observed read latency in milliseconds. */
+    maxMs: number;
+    /** Number of samples used to compute the statistics. */
+    count: number;
+}
 /** Snapshot of cumulative cache counters. */
 interface CacheMetricsSnapshot {
     hits: number;
@@ -80,6 +98,8 @@ interface CacheMetricsSnapshot {
     degradedOperations: number;
     hitsByLayer: Record<string, number>;
     missesByLayer: Record<string, number>;
+    /** Per-layer read latency statistics (sampled from successful reads). */
+    latencyByLayer: Record<string, CacheLayerLatency>;
     /** Timestamp (ms since epoch) when metrics were last reset. */
     resetAt: number;
 }
@@ -101,6 +121,8 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    /** Returns the tags associated with a specific key, or an empty array. */
+    tagsForKey?(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
 }
@@ -203,6 +225,22 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+/** Detailed inspection result for a single cache key. */
+interface CacheInspectResult {
+    key: string;
+    /** Layers in which the key is currently stored (not expired). */
+    foundInLayers: string[];
+    /** Remaining fresh TTL in seconds, or null if no expiry or not an envelope. */
+    freshTtlSeconds: number | null;
+    /** Remaining stale-while-revalidate window in seconds, or null. */
+    staleTtlSeconds: number | null;
+    /** Remaining stale-if-error window in seconds, or null. */
+    errorTtlSeconds: number | null;
+    /** Whether the key is currently serving stale-while-revalidate. */
+    isStale: boolean;
+    /** Tags associated with this key (from the TagIndex). */
+    tags: string[];
+}
 /** All events emitted by CacheStack and their payload shapes. */
 interface CacheStackEvents {
     /** Fired on every cache hit. */
@@ -258,6 +296,10 @@ declare class CacheNamespace {
     constructor(cache: CacheStack, prefix: string);
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
     getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+     */
+    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
     has(key: string): Promise<boolean>;
     ttl(key: string): Promise<number | null>;
     set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
@@ -268,10 +310,24 @@ declare class CacheNamespace {
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    /**
+     * Returns detailed metadata about a single cache key within this namespace.
+     */
+    inspect(key: string): Promise<CacheInspectResult | null>;
     wrap<TArgs extends unknown[], TResult>(keyPrefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
     warm(entries: CacheWarmEntry[], options?: CacheWarmOptions): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getHitRate(): CacheHitRateSnapshot;
+    /**
+     * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
+     *
+     * ```ts
+     * const tenant = cache.namespace('tenant:abc')
+     * const posts = tenant.namespace('posts')
+     * // keys become: "tenant:abc:posts:mykey"
+     * ```
+     */
+    namespace(childPrefix: string): CacheNamespace;
     qualify(key: string): string;
 }
 
@@ -311,6 +367,12 @@ declare class CacheStack extends EventEmitter {
      * Fetches and caches the value if not already present.
      */
     getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<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
+     * return non-null.
+     */
+    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
     /**
      * Returns true if the given key exists and is not expired in any layer.
      */
@@ -355,6 +417,12 @@ declare class CacheStack extends EventEmitter {
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    /**
+     * Returns detailed metadata about a single cache key: which layers contain it,
+     * remaining fresh/stale/error TTLs, and associated tags.
+     * Returns `null` if the key does not exist in any layer.
+     */
+    inspect(key: string): Promise<CacheInspectResult | null>;
     exportState(): Promise<CacheSnapshotEntry[]>;
     importState(entries: CacheSnapshotEntry[]): Promise<void>;
     persistToFile(filePath: string): Promise<void>;
@@ -378,6 +446,7 @@ declare class CacheStack extends EventEmitter {
     private deleteKeys;
     private publishInvalidation;
     private handleInvalidationMessage;
+    private getTagsForKey;
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
@@ -413,9 +482,31 @@ interface CacheStackModuleOptions {
     layers: CacheLayer[];
     bridgeOptions?: CacheStackOptions;
 }
+interface CacheStackModuleAsyncOptions {
+    /**
+     * Tokens to inject into the `useFactory` function.
+     */
+    inject?: Array<Type | string | symbol>;
+    /**
+     * Async factory function that returns `CacheStackModuleOptions`.
+     * Useful when the Redis client or other dependencies must be resolved
+     * from the NestJS DI container first.
+     *
+     * ```ts
+     * CacheStackModule.forRootAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config: ConfigService) => ({
+     *     layers: [new MemoryLayer(), new RedisLayer({ client: createRedis(config) })],
+     *   })
+     * })
+     * ```
+     */
+    useFactory: (...args: unknown[]) => CacheStackModuleOptions | Promise<CacheStackModuleOptions>;
+}
 declare const InjectCacheStack: () => ParameterDecorator & PropertyDecorator;
 declare class CacheStackModule {
     static forRoot(options: CacheStackModuleOptions): DynamicModule;
+    static forRootAsync(options: CacheStackModuleAsyncOptions): DynamicModule;
 }
 
 export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, Cacheable, InjectCacheStack };