layercache 1.0.2 → 1.2.0

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 {
 }
@@ -31,6 +40,7 @@ interface CacheMSetEntry<T> {
     value: T;
     options?: CacheWriteOptions;
 }
+/** Interface that all cache backend implementations must satisfy. */
 interface CacheLayer {
     readonly name: string;
     readonly defaultTtl?: number;
@@ -43,7 +53,33 @@ interface CacheLayer {
     clear(): Promise<void>;
     deleteMany?(keys: string[]): Promise<void>;
     keys?(): Promise<string[]>;
+    /**
+     * Returns true if the key exists and has not expired.
+     * Implementations may omit this; CacheStack will fall back to `get()`.
+     */
+    has?(key: string): Promise<boolean>;
+    /**
+     * Returns the remaining TTL in seconds for the key, or null if the key
+     * does not exist, has no TTL, or has already expired.
+     * Implementations may omit this.
+     */
+    ttl?(key: string): Promise<number | null>;
+    /**
+     * Returns the number of entries currently held by this layer.
+     * Implementations may omit this.
+     */
+    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;
     misses: number;
@@ -62,6 +98,17 @@ 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;
+}
+/** Computed hit-rate statistics derived from CacheMetricsSnapshot. */
+interface CacheHitRateSnapshot {
+    /** Overall hit rate across all layers (0–1). */
+    overall: number;
+    /** Per-layer hit rates (0–1 each). */
+    byLayer: Record<string, number>;
 }
 interface CacheLogger {
     debug?(message: string, context?: Record<string, unknown>): void;
@@ -74,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>;
 }
@@ -102,6 +151,9 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     broadcastL1Invalidation?: boolean;
+    /**
+     * @deprecated Use `broadcastL1Invalidation` instead.
+     */
     publishSetInvalidation?: boolean;
     negativeCaching?: boolean;
     negativeTtl?: number | LayerTtlMap;
@@ -117,6 +169,12 @@ interface CacheStackOptions {
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    /**
+     * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
+     * before the oldest entries are pruned. Prevents unbounded memory growth.
+     * Defaults to 100 000.
+     */
+    maxProfileEntries?: number;
 }
 interface CacheAdaptiveTtlOptions {
     hotAfter?: number;
@@ -136,9 +194,19 @@ interface CacheWarmEntry<T = unknown> {
     options?: CacheGetOptions;
     priority?: number;
 }
+/** Options controlling the cache warm-up process. */
 interface CacheWarmOptions {
     concurrency?: number;
     continueOnError?: boolean;
+    /** Called after each entry is processed (success or failure). */
+    onProgress?: (progress: CacheWarmProgress) => void;
+}
+/** Progress information delivered to `CacheWarmOptions.onProgress`. */
+interface CacheWarmProgress {
+    completed: number;
+    total: number;
+    key: string;
+    success: boolean;
 }
 interface CacheWrapOptions<TArgs extends unknown[] = unknown[]> extends CacheGetOptions {
     keyResolver?: (...args: TArgs) => string;
@@ -157,56 +225,204 @@ 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. */
+    hit: {
+        key: string;
+        layer: string;
+        state: 'fresh' | 'stale-while-revalidate' | 'stale-if-error';
+    };
+    /** Fired on every cache miss before the fetcher runs. */
+    miss: {
+        key: string;
+        mode: string;
+    };
+    /** Fired after a value is stored in the cache. */
+    set: {
+        key: string;
+        kind: string;
+        tags?: string[];
+    };
+    /** Fired after one or more keys are deleted. */
+    delete: {
+        keys: string[];
+    };
+    /** Fired when a value is backfilled into a faster layer. */
+    backfill: {
+        key: string;
+        layer: string;
+    };
+    /** Fired when a stale value is returned to the caller. */
+    'stale-serve': {
+        key: string;
+        state: string;
+        layer: string;
+    };
+    /** Fired when a duplicate request is deduplicated in stampede prevention. */
+    'stampede-dedupe': {
+        key: string;
+    };
+    /** Fired after a key is successfully warmed. */
+    warm: {
+        key: string;
+    };
+    /** Fired when an error occurs (layer failure, circuit breaker, etc.). */
+    error: {
+        operation: string;
+        [key: string]: unknown;
+    };
+}
 
 declare class CacheNamespace {
     private readonly cache;
     private readonly prefix;
     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>;
     delete(key: string): Promise<void>;
+    mdelete(keys: string[]): Promise<void>;
     clear(): Promise<void>;
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     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;
 }
 
+/** Typed overloads for EventEmitter so callers get autocomplete on event names. */
+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;
+    emit<K extends keyof CacheStackEvents>(event: K, data: CacheStackEvents[K]): boolean;
+}
 declare class CacheStack extends EventEmitter {
     private readonly layers;
     private readonly options;
     private readonly stampedeGuard;
-    private readonly metrics;
+    private readonly metricsCollector;
     private readonly instanceId;
     private readonly startup;
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
     private readonly backgroundRefreshes;
-    private readonly accessProfiles;
     private readonly layerDegradedUntil;
-    private readonly circuitBreakers;
+    private readonly ttlResolver;
+    private readonly circuitBreakerManager;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
+    /**
+     * Read-through cache get.
+     * Returns the cached value if present and fresh, or invokes `fetcher` on a miss
+     * and stores the result across all layers. Returns `null` if the key is not found
+     * and no `fetcher` is provided.
+     */
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
+     * 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.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Returns the remaining TTL in seconds for the key in the fastest layer
+     * that has it, or null if the key is not found / has no TTL.
+     */
+    ttl(key: string): Promise<number | null>;
+    /**
+     * Stores a value in all cache layers. Overwrites any existing value.
+     */
     set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
+    /**
+     * Deletes the key from all layers and publishes an invalidation message.
+     */
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
+    /**
+     * Deletes multiple keys at once. More efficient than calling `delete()` in a loop.
+     */
+    mdelete(keys: string[]): Promise<void>;
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     warm(entries: CacheWarmEntry[], options?: CacheWarmOptions): Promise<void>;
+    /**
+     * Returns a cached version of `fetcher`. The cache key is derived from
+     * `prefix` plus the serialized arguments unless a `keyResolver` is provided.
+     */
     wrap<TArgs extends unknown[], TResult>(prefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
+    /**
+     * Creates a `CacheNamespace` that automatically prefixes all keys with
+     * `prefix:`. Useful for multi-tenant or module-level isolation.
+     */
     namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
+    /**
+     * 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>;
@@ -224,14 +440,13 @@ declare class CacheStack extends EventEmitter {
     private executeLayerOperations;
     private resolveFreshTtl;
     private resolveLayerSeconds;
-    private readLayerNumber;
-    private applyJitter;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
     private resolveSingleFlightOptions;
     private deleteKeys;
     private publishInvalidation;
     private handleInvalidationMessage;
+    private getTagsForKey;
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
@@ -246,15 +461,10 @@ declare class CacheStack extends EventEmitter {
     private validateAdaptiveTtlOptions;
     private validateCircuitBreakerOptions;
     private applyFreshReadPolicies;
-    private applyAdaptiveTtl;
-    private recordAccess;
-    private incrementMetricMap;
     private shouldSkipLayer;
     private handleLayerFailure;
     private isGracefulDegradationEnabled;
-    private assertCircuitClosed;
     private recordCircuitFailure;
-    private resetCircuitBreaker;
     private isNegativeStoredValue;
     private emitError;
     private serializeKeyPart;
@@ -272,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 };