layercache 1.0.1 → 1.1.0

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

@@ -1,3 +1,4 @@
+import { EventEmitter } from 'node:events';
 import { DynamicModule } from '@nestjs/common';
 
 declare const CACHE_STACK: unique symbol;
@@ -5,6 +6,32 @@ declare const CACHE_STACK: unique symbol;
 interface LayerTtlMap {
     [layerName: string]: number | undefined;
 }
+interface CacheWriteOptions {
+    tags?: string[];
+    ttl?: number | LayerTtlMap;
+    negativeCache?: boolean;
+    negativeTtl?: number | LayerTtlMap;
+    staleWhileRevalidate?: number | LayerTtlMap;
+    staleIfError?: number | LayerTtlMap;
+    ttlJitter?: number | LayerTtlMap;
+    slidingTtl?: boolean;
+    refreshAhead?: number | LayerTtlMap;
+    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
+    circuitBreaker?: CacheCircuitBreakerOptions;
+}
+interface CacheGetOptions extends CacheWriteOptions {
+}
+interface CacheMGetEntry<T> {
+    key: string;
+    fetch?: () => Promise<T>;
+    options?: CacheGetOptions;
+}
+interface CacheMSetEntry<T> {
+    key: string;
+    value: T;
+    options?: CacheWriteOptions;
+}
+/** Interface that all cache backend implementations must satisfy. */
 interface CacheLayer {
     readonly name: string;
     readonly defaultTtl?: number;
@@ -17,9 +44,57 @@ 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;
+    fetches: number;
+    sets: number;
+    deletes: number;
+    backfills: number;
+    invalidations: number;
+    staleHits: number;
+    refreshes: number;
+    refreshErrors: number;
+    writeFailures: number;
+    singleFlightWaits: number;
+    negativeCacheHits: number;
+    circuitBreakerTrips: number;
+    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;
+    debug?(message: string, context?: Record<string, unknown>): void;
+    info?(message: string, context?: Record<string, unknown>): void;
+    warn?(message: string, context?: Record<string, unknown>): void;
+    error?(message: string, context?: Record<string, unknown>): void;
 }
 interface CacheTagIndex {
     touch(key: string): Promise<void>;
@@ -53,18 +128,286 @@ interface CacheStackOptions {
     stampedePrevention?: boolean;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
+    broadcastL1Invalidation?: boolean;
+    /**
+     * @deprecated Use `broadcastL1Invalidation` instead.
+     */
     publishSetInvalidation?: boolean;
     negativeCaching?: boolean;
     negativeTtl?: number | LayerTtlMap;
     staleWhileRevalidate?: number | LayerTtlMap;
     staleIfError?: number | LayerTtlMap;
     ttlJitter?: number | LayerTtlMap;
+    refreshAhead?: number | LayerTtlMap;
+    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
+    circuitBreaker?: CacheCircuitBreakerOptions;
+    gracefulDegradation?: boolean | CacheDegradationOptions;
     writePolicy?: 'strict' | 'best-effort';
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     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;
+    step?: number | LayerTtlMap;
+    maxTtl?: number | LayerTtlMap;
+}
+interface CacheCircuitBreakerOptions {
+    failureThreshold?: number;
+    cooldownMs?: number;
+}
+interface CacheDegradationOptions {
+    retryAfterMs?: number;
+}
+interface CacheWarmEntry<T = unknown> {
+    key: string;
+    fetcher: () => Promise<T>;
+    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;
+}
+interface CacheSnapshotEntry {
+    key: string;
+    value: unknown;
+    ttl?: number;
+}
+interface CacheStatsSnapshot {
+    metrics: CacheMetricsSnapshot;
+    layers: Array<{
+        name: string;
+        isLocal: boolean;
+        degradedUntil: number | null;
+    }>;
+    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>;
+    invalidateByTag(tag: string): Promise<void>;
+    invalidateByPattern(pattern: string): Promise<void>;
+    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 metricsCollector;
+    private readonly instanceId;
+    private readonly startup;
+    private unsubscribeInvalidation?;
+    private readonly logger;
+    private readonly tagIndex;
+    private readonly backgroundRefreshes;
+    private readonly layerDegradedUntil;
+    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>;
+    restoreFromFile(filePath: string): Promise<void>;
+    disconnect(): Promise<void>;
+    private initialize;
+    private fetchWithGuards;
+    private waitForFreshValue;
+    private fetchAndPopulate;
+    private storeEntry;
+    private readFromLayers;
+    private readLayerEntry;
+    private backfill;
+    private writeAcrossLayers;
+    private executeLayerOperations;
+    private resolveFreshTtl;
+    private resolveLayerSeconds;
+    private shouldNegativeCache;
+    private scheduleBackgroundRefresh;
+    private resolveSingleFlightOptions;
+    private deleteKeys;
+    private publishInvalidation;
+    private handleInvalidationMessage;
+    private formatError;
+    private sleep;
+    private shouldBroadcastL1Invalidation;
+    private deleteKeysFromLayers;
+    private validateConfiguration;
+    private validateWriteOptions;
+    private validateLayerNumberOption;
+    private validatePositiveNumber;
+    private validateNonNegativeNumber;
+    private validateCacheKey;
+    private serializeOptions;
+    private validateAdaptiveTtlOptions;
+    private validateCircuitBreakerOptions;
+    private applyFreshReadPolicies;
+    private shouldSkipLayer;
+    private handleLayerFailure;
+    private isGracefulDegradationEnabled;
+    private recordCircuitFailure;
+    private isNegativeStoredValue;
+    private emitError;
+    private serializeKeyPart;
+    private isCacheSnapshotEntries;
+    private normalizeForSerialization;
+}
+
+interface CacheableOptions<TArgs extends unknown[]> extends CacheWrapOptions<TArgs> {
+    cache: (instance: unknown) => CacheStack;
+    prefix?: string;
 }
+declare function Cacheable<TArgs extends unknown[] = unknown[]>(options: CacheableOptions<TArgs>): MethodDecorator;
 
 interface CacheStackModuleOptions {
     layers: CacheLayer[];
@@ -75,4 +418,4 @@ declare class CacheStackModule {
     static forRoot(options: CacheStackModuleOptions): DynamicModule;
 }
 
-export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, InjectCacheStack };
+export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, Cacheable, InjectCacheStack };