layercache 1.0.2 → 1.1.0

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

@@ -31,6 +31,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 +44,24 @@ 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>;
 }
+/** Snapshot of cumulative cache counters. */
 interface CacheMetricsSnapshot {
     hits: number;
     misses: number;
@@ -62,6 +80,15 @@ interface CacheMetricsSnapshot {
     degradedOperations: number;
     hitsByLayer: Record<string, number>;
     missesByLayer: Record<string, number>;
+    /** 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;
@@ -102,6 +129,9 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     broadcastL1Invalidation?: boolean;
+    /**
+     * @deprecated Use `broadcastL1Invalidation` instead.
+     */
     publishSetInvalidation?: boolean;
     negativeCaching?: boolean;
     negativeTtl?: number | LayerTtlMap;
@@ -117,6 +147,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 +172,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,14 +203,66 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+/** 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>;
+    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>;
@@ -173,40 +271,90 @@ declare class CacheNamespace {
     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;
     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>;
+    /**
+     * 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;
     exportState(): Promise<CacheSnapshotEntry[]>;
     importState(entries: CacheSnapshotEntry[]): Promise<void>;
     persistToFile(filePath: string): Promise<void>;
@@ -224,8 +372,6 @@ declare class CacheStack extends EventEmitter {
     private executeLayerOperations;
     private resolveFreshTtl;
     private resolveLayerSeconds;
-    private readLayerNumber;
-    private applyJitter;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
     private resolveSingleFlightOptions;
@@ -246,15 +392,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;

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

@@ -31,6 +31,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 +44,24 @@ 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>;
 }
+/** Snapshot of cumulative cache counters. */
 interface CacheMetricsSnapshot {
     hits: number;
     misses: number;
@@ -62,6 +80,15 @@ interface CacheMetricsSnapshot {
     degradedOperations: number;
     hitsByLayer: Record<string, number>;
     missesByLayer: Record<string, number>;
+    /** 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;
@@ -102,6 +129,9 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     broadcastL1Invalidation?: boolean;
+    /**
+     * @deprecated Use `broadcastL1Invalidation` instead.
+     */
     publishSetInvalidation?: boolean;
     negativeCaching?: boolean;
     negativeTtl?: number | LayerTtlMap;
@@ -117,6 +147,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 +172,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,14 +203,66 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+/** 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>;
+    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>;
@@ -173,40 +271,90 @@ declare class CacheNamespace {
     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;
     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>;
+    /**
+     * 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;
     exportState(): Promise<CacheSnapshotEntry[]>;
     importState(entries: CacheSnapshotEntry[]): Promise<void>;
     persistToFile(filePath: string): Promise<void>;
@@ -224,8 +372,6 @@ declare class CacheStack extends EventEmitter {
     private executeLayerOperations;
     private resolveFreshTtl;
     private resolveLayerSeconds;
-    private readLayerNumber;
-    private applyJitter;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
     private resolveSingleFlightOptions;
@@ -246,15 +392,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;