layercache 1.0.0 → 1.0.2

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

@@ -1,20 +1,73 @@
+import { EventEmitter } from 'node:events';
 import { DynamicModule } from '@nestjs/common';
 
 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 CacheLayer {
     readonly name: string;
     readonly defaultTtl?: number;
     readonly isLocal?: boolean;
     get<T>(key: string): Promise<T | null>;
+    getEntry?<T = unknown>(key: string): Promise<T | null>;
+    getMany?<T>(keys: string[]): Promise<Array<T | null>>;
     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[]>;
 }
+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>;
+}
 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>;
@@ -34,14 +87,186 @@ interface InvalidationBus {
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void> | void>;
     publish(message: InvalidationMessage): Promise<void>;
 }
+interface CacheSingleFlightExecutionOptions {
+    leaseMs: number;
+    waitTimeoutMs: number;
+    pollIntervalMs: number;
+}
+interface CacheSingleFlightCoordinator {
+    execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
+}
 interface CacheStackOptions {
     logger?: CacheLogger | boolean;
     metrics?: boolean;
     stampedePrevention?: boolean;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
+    broadcastL1Invalidation?: boolean;
     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;
+}
+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;
+}
+interface CacheWarmOptions {
+    concurrency?: number;
+    continueOnError?: 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;
+}
+
+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>;
+    set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
+    delete(key: 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;
+    qualify(key: string): string;
+}
+
+declare class CacheStack extends EventEmitter {
+    private readonly layers;
+    private readonly options;
+    private readonly stampedeGuard;
+    private readonly metrics;
+    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 isDisconnecting;
+    private disconnectPromise?;
+    constructor(layers: CacheLayer[], options?: CacheStackOptions);
+    get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): 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>;
+    wrap<TArgs extends unknown[], TResult>(prefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
+    namespace(prefix: string): CacheNamespace;
+    invalidateByTag(tag: string): Promise<void>;
+    invalidateByPattern(pattern: string): Promise<void>;
+    getMetrics(): CacheMetricsSnapshot;
+    getStats(): CacheStatsSnapshot;
+    resetMetrics(): void;
+    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 readLayerNumber;
+    private applyJitter;
+    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 applyAdaptiveTtl;
+    private recordAccess;
+    private incrementMetricMap;
+    private shouldSkipLayer;
+    private handleLayerFailure;
+    private isGracefulDegradationEnabled;
+    private assertCircuitClosed;
+    private recordCircuitFailure;
+    private resetCircuitBreaker;
+    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[];
@@ -52,4 +277,4 @@ declare class CacheStackModule {
     static forRoot(options: CacheStackModuleOptions): DynamicModule;
 }
 
-export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, InjectCacheStack };
+export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, Cacheable, InjectCacheStack };

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

@@ -1,20 +1,73 @@
+import { EventEmitter } from 'node:events';
 import { DynamicModule } from '@nestjs/common';
 
 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 CacheLayer {
     readonly name: string;
     readonly defaultTtl?: number;
     readonly isLocal?: boolean;
     get<T>(key: string): Promise<T | null>;
+    getEntry?<T = unknown>(key: string): Promise<T | null>;
+    getMany?<T>(keys: string[]): Promise<Array<T | null>>;
     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[]>;
 }
+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>;
+}
 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>;
@@ -34,14 +87,186 @@ interface InvalidationBus {
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void> | void>;
     publish(message: InvalidationMessage): Promise<void>;
 }
+interface CacheSingleFlightExecutionOptions {
+    leaseMs: number;
+    waitTimeoutMs: number;
+    pollIntervalMs: number;
+}
+interface CacheSingleFlightCoordinator {
+    execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
+}
 interface CacheStackOptions {
     logger?: CacheLogger | boolean;
     metrics?: boolean;
     stampedePrevention?: boolean;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
+    broadcastL1Invalidation?: boolean;
     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;
+}
+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;
+}
+interface CacheWarmOptions {
+    concurrency?: number;
+    continueOnError?: 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;
+}
+
+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>;
+    set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
+    delete(key: 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;
+    qualify(key: string): string;
+}
+
+declare class CacheStack extends EventEmitter {
+    private readonly layers;
+    private readonly options;
+    private readonly stampedeGuard;
+    private readonly metrics;
+    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 isDisconnecting;
+    private disconnectPromise?;
+    constructor(layers: CacheLayer[], options?: CacheStackOptions);
+    get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): 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>;
+    wrap<TArgs extends unknown[], TResult>(prefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
+    namespace(prefix: string): CacheNamespace;
+    invalidateByTag(tag: string): Promise<void>;
+    invalidateByPattern(pattern: string): Promise<void>;
+    getMetrics(): CacheMetricsSnapshot;
+    getStats(): CacheStatsSnapshot;
+    resetMetrics(): void;
+    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 readLayerNumber;
+    private applyJitter;
+    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 applyAdaptiveTtl;
+    private recordAccess;
+    private incrementMetricMap;
+    private shouldSkipLayer;
+    private handleLayerFailure;
+    private isGracefulDegradationEnabled;
+    private assertCircuitClosed;
+    private recordCircuitFailure;
+    private resetCircuitBreaker;
+    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[];
@@ -52,4 +277,4 @@ declare class CacheStackModule {
     static forRoot(options: CacheStackModuleOptions): DynamicModule;
 }
 
-export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, InjectCacheStack };
+export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, Cacheable, InjectCacheStack };