layercache 1.2.1 → 1.2.3

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

@@ -156,6 +156,7 @@ interface CacheSingleFlightExecutionOptions {
     leaseMs: number;
     waitTimeoutMs: number;
     pollIntervalMs: number;
+    renewIntervalMs?: number;
 }
 interface CacheSingleFlightCoordinator {
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
@@ -167,6 +168,7 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;
+    generationCleanup?: boolean | CacheGenerationCleanupOptions;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -185,10 +187,13 @@ interface CacheStackOptions {
     writeStrategy?: 'write-through' | 'write-behind';
     writeBehind?: CacheWriteBehindOptions;
     fetcherRateLimit?: CacheRateLimitOptions;
+    backgroundRefreshTimeoutMs?: number;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
+    snapshotBaseDir?: string | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -201,6 +206,9 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+interface CacheGenerationCleanupOptions {
+    batchSize?: number;
+}
 type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
     alignTo: number;
 } | ((context: CacheTtlPolicyContext) => number | undefined);
@@ -219,6 +227,8 @@ interface CacheRateLimitOptions {
     maxConcurrent?: number;
     intervalMs?: number;
     maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
 }
 interface CacheWriteBehindOptions {
     flushIntervalMs?: number;
@@ -401,6 +411,7 @@ declare class CacheStack extends EventEmitter {
     private readonly logger;
     private readonly tagIndex;
     private readonly fetchRateLimiter;
+    private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
@@ -409,6 +420,7 @@ declare class CacheStack extends EventEmitter {
     private readonly writeBehindQueue;
     private writeBehindTimer?;
     private writeBehindFlushPromise?;
+    private generationCleanupPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -419,6 +431,7 @@ declare class CacheStack extends EventEmitter {
      * and no `fetcher` is provided.
      */
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    private getPrepared;
     /**
      * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
      * Fetches and caches the value if not already present.
@@ -477,6 +490,11 @@ declare class CacheStack extends EventEmitter {
      */
     getHitRate(): CacheHitRateSnapshot;
     healthCheck(): Promise<CacheHealthCheckResult[]>;
+    /**
+     * Rotates the active generation prefix used for all future cache keys.
+     * Previous-generation keys remain in the underlying layers until they expire,
+     * unless `generationCleanup` is enabled to prune them in the background.
+     */
     bumpGeneration(nextGeneration?: number): number;
     /**
      * Returns detailed metadata about a single cache key: which layers contain it,
@@ -504,6 +522,7 @@ declare class CacheStack extends EventEmitter {
     private resolveLayerSeconds;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
+    private runBackgroundRefresh;
     private resolveSingleFlightOptions;
     private deleteKeys;
     private publishInvalidation;
@@ -511,7 +530,14 @@ declare class CacheStack extends EventEmitter {
     private getTagsForKey;
     private formatError;
     private sleep;
+    private withTimeout;
     private shouldBroadcastL1Invalidation;
+    private collectKeysWithPrefix;
+    private collectKeysMatchingPattern;
+    private shouldCleanupGenerations;
+    private generationCleanupBatchSize;
+    private scheduleGenerationCleanup;
+    private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
     private enqueueWriteBehind;
@@ -527,6 +553,7 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
     private validateTtlPolicy;
@@ -538,12 +565,15 @@ declare class CacheStack extends EventEmitter {
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
+    private reportRecoverableLayerFailure;
     private isGracefulDegradationEnabled;
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
     private serializeKeyPart;
     private isCacheSnapshotEntries;
+    private sanitizeSnapshotValue;
+    private validateSnapshotFilePath;
     private normalizeForSerialization;
 }
 

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

@@ -156,6 +156,7 @@ interface CacheSingleFlightExecutionOptions {
     leaseMs: number;
     waitTimeoutMs: number;
     pollIntervalMs: number;
+    renewIntervalMs?: number;
 }
 interface CacheSingleFlightCoordinator {
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
@@ -167,6 +168,7 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     generation?: number;
+    generationCleanup?: boolean | CacheGenerationCleanupOptions;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -185,10 +187,13 @@ interface CacheStackOptions {
     writeStrategy?: 'write-through' | 'write-behind';
     writeBehind?: CacheWriteBehindOptions;
     fetcherRateLimit?: CacheRateLimitOptions;
+    backgroundRefreshTimeoutMs?: number;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
+    snapshotBaseDir?: string | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -201,6 +206,9 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+interface CacheGenerationCleanupOptions {
+    batchSize?: number;
+}
 type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
     alignTo: number;
 } | ((context: CacheTtlPolicyContext) => number | undefined);
@@ -219,6 +227,8 @@ interface CacheRateLimitOptions {
     maxConcurrent?: number;
     intervalMs?: number;
     maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
 }
 interface CacheWriteBehindOptions {
     flushIntervalMs?: number;
@@ -401,6 +411,7 @@ declare class CacheStack extends EventEmitter {
     private readonly logger;
     private readonly tagIndex;
     private readonly fetchRateLimiter;
+    private readonly snapshotSerializer;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
@@ -409,6 +420,7 @@ declare class CacheStack extends EventEmitter {
     private readonly writeBehindQueue;
     private writeBehindTimer?;
     private writeBehindFlushPromise?;
+    private generationCleanupPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -419,6 +431,7 @@ declare class CacheStack extends EventEmitter {
      * and no `fetcher` is provided.
      */
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    private getPrepared;
     /**
      * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
      * Fetches and caches the value if not already present.
@@ -477,6 +490,11 @@ declare class CacheStack extends EventEmitter {
      */
     getHitRate(): CacheHitRateSnapshot;
     healthCheck(): Promise<CacheHealthCheckResult[]>;
+    /**
+     * Rotates the active generation prefix used for all future cache keys.
+     * Previous-generation keys remain in the underlying layers until they expire,
+     * unless `generationCleanup` is enabled to prune them in the background.
+     */
     bumpGeneration(nextGeneration?: number): number;
     /**
      * Returns detailed metadata about a single cache key: which layers contain it,
@@ -504,6 +522,7 @@ declare class CacheStack extends EventEmitter {
     private resolveLayerSeconds;
     private shouldNegativeCache;
     private scheduleBackgroundRefresh;
+    private runBackgroundRefresh;
     private resolveSingleFlightOptions;
     private deleteKeys;
     private publishInvalidation;
@@ -511,7 +530,14 @@ declare class CacheStack extends EventEmitter {
     private getTagsForKey;
     private formatError;
     private sleep;
+    private withTimeout;
     private shouldBroadcastL1Invalidation;
+    private collectKeysWithPrefix;
+    private collectKeysMatchingPattern;
+    private shouldCleanupGenerations;
+    private generationCleanupBatchSize;
+    private scheduleGenerationCleanup;
+    private cleanupGeneration;
     private initializeWriteBehind;
     private shouldWriteBehind;
     private enqueueWriteBehind;
@@ -527,6 +553,7 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
     private validateTtlPolicy;
@@ -538,12 +565,15 @@ declare class CacheStack extends EventEmitter {
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
+    private reportRecoverableLayerFailure;
     private isGracefulDegradationEnabled;
     private recordCircuitFailure;
     private isNegativeStoredValue;
     private emitError;
     private serializeKeyPart;
     private isCacheSnapshotEntries;
+    private sanitizeSnapshotValue;
+    private validateSnapshotFilePath;
     private normalizeForSerialization;
 }