layercache 1.1.0 → 1.2.1

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;
 
@@ -9,6 +9,7 @@ interface LayerTtlMap {
 interface CacheWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
+    ttlPolicy?: CacheTtlPolicy;
     negativeCache?: boolean;
     negativeTtl?: number | LayerTtlMap;
     staleWhileRevalidate?: number | LayerTtlMap;
@@ -18,6 +19,16 @@ interface CacheWriteOptions {
     refreshAhead?: number | LayerTtlMap;
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
+    /**
+     * 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 {
 }
@@ -38,12 +49,20 @@ interface CacheLayer {
     readonly isLocal?: boolean;
     get<T>(key: string): Promise<T | null>;
     getEntry?<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Bulk read fast-path. Implementations should return raw stored entries using
+     * the same semantics as `getEntry()` so CacheStack can resolve envelopes,
+     * stale windows, and negative-cache markers consistently.
+     */
     getMany?<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany?(entries: CacheLayerSetManyEntry[]): Promise<void>;
     set(key: string, value: unknown, ttl?: number): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
     deleteMany?(keys: string[]): Promise<void>;
     keys?(): Promise<string[]>;
+    ping?(): Promise<boolean>;
+    dispose?(): Promise<void>;
     /**
      * Returns true if the key exists and has not expired.
      * Implementations may omit this; CacheStack will fall back to `get()`.
@@ -61,6 +80,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 +108,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,9 +131,17 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    keysForPrefix?(prefix: 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>;
 }
+interface CacheLayerSetManyEntry {
+    key: string;
+    value: unknown;
+    ttl?: number;
+}
 interface InvalidationMessage {
     scope: 'key' | 'keys' | 'clear';
     sourceId: string;
@@ -128,6 +166,7 @@ interface CacheStackOptions {
     stampedePrevention?: boolean;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
+    generation?: number;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -143,6 +182,9 @@ interface CacheStackOptions {
     circuitBreaker?: CacheCircuitBreakerOptions;
     gracefulDegradation?: boolean | CacheDegradationOptions;
     writePolicy?: 'strict' | 'best-effort';
+    writeStrategy?: 'write-through' | 'write-behind';
+    writeBehind?: CacheWriteBehindOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
@@ -159,6 +201,13 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
+    alignTo: number;
+} | ((context: CacheTtlPolicyContext) => number | undefined);
+interface CacheTtlPolicyContext {
+    key: string;
+    value: unknown;
+}
 interface CacheCircuitBreakerOptions {
     failureThreshold?: number;
     cooldownMs?: number;
@@ -166,6 +215,16 @@ interface CacheCircuitBreakerOptions {
 interface CacheDegradationOptions {
     retryAfterMs?: number;
 }
+interface CacheRateLimitOptions {
+    maxConcurrent?: number;
+    intervalMs?: number;
+    maxPerInterval?: number;
+}
+interface CacheWriteBehindOptions {
+    flushIntervalMs?: number;
+    batchSize?: number;
+    maxQueueSize?: number;
+}
 interface CacheWarmEntry<T = unknown> {
     key: string;
     fetcher: () => Promise<T>;
@@ -203,6 +262,28 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+interface CacheHealthCheckResult {
+    layer: string;
+    healthy: boolean;
+    latencyMs: number;
+    error?: string;
+}
+/** 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. */
@@ -255,9 +336,15 @@ interface CacheStackEvents {
 declare class CacheNamespace {
     private readonly cache;
     private readonly prefix;
+    private static readonly metricsMutexes;
+    private metrics;
     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>;
@@ -267,12 +354,30 @@ declare class CacheNamespace {
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: 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;
+    private trackMetrics;
+    private getMetricsMutex;
 }
 
 /** Typed overloads for EventEmitter so callers get autocomplete on event names. */
@@ -280,6 +385,9 @@ interface CacheStack {
     on<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
     once<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
     off<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
+    removeAllListeners<K extends keyof CacheStackEvents>(event?: K): this;
+    listeners<K extends keyof CacheStackEvents>(event: K): Array<(data: CacheStackEvents[K]) => void>;
+    listenerCount<K extends keyof CacheStackEvents>(event: K): number;
     emit<K extends keyof CacheStackEvents>(event: K, data: CacheStackEvents[K]): boolean;
 }
 declare class CacheStack extends EventEmitter {
@@ -292,10 +400,15 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly fetchRateLimiter;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private currentGeneration?;
+    private readonly writeBehindQueue;
+    private writeBehindTimer?;
+    private writeBehindFlushPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -311,6 +424,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.
      */
@@ -347,7 +466,9 @@ declare class CacheStack extends EventEmitter {
      */
     namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
@@ -355,6 +476,14 @@ declare class CacheStack extends EventEmitter {
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    healthCheck(): Promise<CacheHealthCheckResult[]>;
+    bumpGeneration(nextGeneration?: number): number;
+    /**
+     * 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>;
@@ -365,6 +494,7 @@ declare class CacheStack extends EventEmitter {
     private waitForFreshValue;
     private fetchAndPopulate;
     private storeEntry;
+    private writeBatch;
     private readFromLayers;
     private readLayerEntry;
     private backfill;
@@ -378,9 +508,20 @@ declare class CacheStack extends EventEmitter {
     private deleteKeys;
     private publishInvalidation;
     private handleInvalidationMessage;
+    private getTagsForKey;
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
+    private initializeWriteBehind;
+    private shouldWriteBehind;
+    private enqueueWriteBehind;
+    private flushWriteBehindQueue;
+    private buildLayerSetEntry;
+    private intersectKeys;
+    private qualifyKey;
+    private qualifyPattern;
+    private stripQualifiedKey;
+    private generationPrefix;
     private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
@@ -388,6 +529,9 @@ declare class CacheStack extends EventEmitter {
     private validatePositiveNumber;
     private validateNonNegativeNumber;
     private validateCacheKey;
+    private validateTtlPolicy;
+    private assertActive;
+    private awaitStartup;
     private serializeOptions;
     private validateAdaptiveTtlOptions;
     private validateCircuitBreakerOptions;
@@ -413,9 +557,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;
 
@@ -9,6 +9,7 @@ interface LayerTtlMap {
 interface CacheWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
+    ttlPolicy?: CacheTtlPolicy;
     negativeCache?: boolean;
     negativeTtl?: number | LayerTtlMap;
     staleWhileRevalidate?: number | LayerTtlMap;
@@ -18,6 +19,16 @@ interface CacheWriteOptions {
     refreshAhead?: number | LayerTtlMap;
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
+    /**
+     * 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 {
 }
@@ -38,12 +49,20 @@ interface CacheLayer {
     readonly isLocal?: boolean;
     get<T>(key: string): Promise<T | null>;
     getEntry?<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Bulk read fast-path. Implementations should return raw stored entries using
+     * the same semantics as `getEntry()` so CacheStack can resolve envelopes,
+     * stale windows, and negative-cache markers consistently.
+     */
     getMany?<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany?(entries: CacheLayerSetManyEntry[]): Promise<void>;
     set(key: string, value: unknown, ttl?: number): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
     deleteMany?(keys: string[]): Promise<void>;
     keys?(): Promise<string[]>;
+    ping?(): Promise<boolean>;
+    dispose?(): Promise<void>;
     /**
      * Returns true if the key exists and has not expired.
      * Implementations may omit this; CacheStack will fall back to `get()`.
@@ -61,6 +80,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 +108,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,9 +131,17 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    keysForPrefix?(prefix: 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>;
 }
+interface CacheLayerSetManyEntry {
+    key: string;
+    value: unknown;
+    ttl?: number;
+}
 interface InvalidationMessage {
     scope: 'key' | 'keys' | 'clear';
     sourceId: string;
@@ -128,6 +166,7 @@ interface CacheStackOptions {
     stampedePrevention?: boolean;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
+    generation?: number;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -143,6 +182,9 @@ interface CacheStackOptions {
     circuitBreaker?: CacheCircuitBreakerOptions;
     gracefulDegradation?: boolean | CacheDegradationOptions;
     writePolicy?: 'strict' | 'best-effort';
+    writeStrategy?: 'write-through' | 'write-behind';
+    writeBehind?: CacheWriteBehindOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
@@ -159,6 +201,13 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
+    alignTo: number;
+} | ((context: CacheTtlPolicyContext) => number | undefined);
+interface CacheTtlPolicyContext {
+    key: string;
+    value: unknown;
+}
 interface CacheCircuitBreakerOptions {
     failureThreshold?: number;
     cooldownMs?: number;
@@ -166,6 +215,16 @@ interface CacheCircuitBreakerOptions {
 interface CacheDegradationOptions {
     retryAfterMs?: number;
 }
+interface CacheRateLimitOptions {
+    maxConcurrent?: number;
+    intervalMs?: number;
+    maxPerInterval?: number;
+}
+interface CacheWriteBehindOptions {
+    flushIntervalMs?: number;
+    batchSize?: number;
+    maxQueueSize?: number;
+}
 interface CacheWarmEntry<T = unknown> {
     key: string;
     fetcher: () => Promise<T>;
@@ -203,6 +262,28 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+interface CacheHealthCheckResult {
+    layer: string;
+    healthy: boolean;
+    latencyMs: number;
+    error?: string;
+}
+/** 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. */
@@ -255,9 +336,15 @@ interface CacheStackEvents {
 declare class CacheNamespace {
     private readonly cache;
     private readonly prefix;
+    private static readonly metricsMutexes;
+    private metrics;
     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>;
@@ -267,12 +354,30 @@ declare class CacheNamespace {
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: 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;
+    private trackMetrics;
+    private getMetricsMutex;
 }
 
 /** Typed overloads for EventEmitter so callers get autocomplete on event names. */
@@ -280,6 +385,9 @@ interface CacheStack {
     on<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
     once<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
     off<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
+    removeAllListeners<K extends keyof CacheStackEvents>(event?: K): this;
+    listeners<K extends keyof CacheStackEvents>(event: K): Array<(data: CacheStackEvents[K]) => void>;
+    listenerCount<K extends keyof CacheStackEvents>(event: K): number;
     emit<K extends keyof CacheStackEvents>(event: K, data: CacheStackEvents[K]): boolean;
 }
 declare class CacheStack extends EventEmitter {
@@ -292,10 +400,15 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly fetchRateLimiter;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private currentGeneration?;
+    private readonly writeBehindQueue;
+    private writeBehindTimer?;
+    private writeBehindFlushPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -311,6 +424,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.
      */
@@ -347,7 +466,9 @@ declare class CacheStack extends EventEmitter {
      */
     namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
@@ -355,6 +476,14 @@ declare class CacheStack extends EventEmitter {
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    healthCheck(): Promise<CacheHealthCheckResult[]>;
+    bumpGeneration(nextGeneration?: number): number;
+    /**
+     * 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>;
@@ -365,6 +494,7 @@ declare class CacheStack extends EventEmitter {
     private waitForFreshValue;
     private fetchAndPopulate;
     private storeEntry;
+    private writeBatch;
     private readFromLayers;
     private readLayerEntry;
     private backfill;
@@ -378,9 +508,20 @@ declare class CacheStack extends EventEmitter {
     private deleteKeys;
     private publishInvalidation;
     private handleInvalidationMessage;
+    private getTagsForKey;
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
+    private initializeWriteBehind;
+    private shouldWriteBehind;
+    private enqueueWriteBehind;
+    private flushWriteBehindQueue;
+    private buildLayerSetEntry;
+    private intersectKeys;
+    private qualifyKey;
+    private qualifyPattern;
+    private stripQualifiedKey;
+    private generationPrefix;
     private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
@@ -388,6 +529,9 @@ declare class CacheStack extends EventEmitter {
     private validatePositiveNumber;
     private validateNonNegativeNumber;
     private validateCacheKey;
+    private validateTtlPolicy;
+    private assertActive;
+    private awaitStartup;
     private serializeOptions;
     private validateAdaptiveTtlOptions;
     private validateCircuitBreakerOptions;
@@ -413,9 +557,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 };