layercache 1.2.0 → 1.2.2

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

@@ -9,6 +9,7 @@ interface LayerTtlMap {
 interface CacheWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
+    ttlPolicy?: CacheTtlPolicy;
     negativeCache?: boolean;
     negativeTtl?: number | LayerTtlMap;
     staleWhileRevalidate?: number | LayerTtlMap;
@@ -18,6 +19,7 @@ interface CacheWriteOptions {
     refreshAhead?: number | LayerTtlMap;
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
     /**
      * 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
@@ -47,12 +49,20 @@ interface CacheLayer {
     readonly isLocal?: boolean;
     get<T>(key: string): Promise<T | null>;
     getEntry?<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Bulk read fast-path. Implementations should return raw stored entries using
+     * the same semantics as `getEntry()` so CacheStack can resolve envelopes,
+     * stale windows, and negative-cache markers consistently.
+     */
     getMany?<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany?(entries: CacheLayerSetManyEntry[]): Promise<void>;
     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[]>;
+    ping?(): Promise<boolean>;
+    dispose?(): Promise<void>;
     /**
      * Returns true if the key exists and has not expired.
      * Implementations may omit this; CacheStack will fall back to `get()`.
@@ -121,11 +131,17 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    keysForPrefix?(prefix: 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>;
 }
+interface CacheLayerSetManyEntry {
+    key: string;
+    value: unknown;
+    ttl?: number;
+}
 interface InvalidationMessage {
     scope: 'key' | 'keys' | 'clear';
     sourceId: string;
@@ -140,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>;
@@ -150,6 +167,7 @@ interface CacheStackOptions {
     stampedePrevention?: boolean;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
+    generation?: number;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -165,10 +183,14 @@ interface CacheStackOptions {
     circuitBreaker?: CacheCircuitBreakerOptions;
     gracefulDegradation?: boolean | CacheDegradationOptions;
     writePolicy?: 'strict' | 'best-effort';
+    writeStrategy?: 'write-through' | 'write-behind';
+    writeBehind?: CacheWriteBehindOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -181,6 +203,13 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
+    alignTo: number;
+} | ((context: CacheTtlPolicyContext) => number | undefined);
+interface CacheTtlPolicyContext {
+    key: string;
+    value: unknown;
+}
 interface CacheCircuitBreakerOptions {
     failureThreshold?: number;
     cooldownMs?: number;
@@ -188,6 +217,18 @@ interface CacheCircuitBreakerOptions {
 interface CacheDegradationOptions {
     retryAfterMs?: number;
 }
+interface CacheRateLimitOptions {
+    maxConcurrent?: number;
+    intervalMs?: number;
+    maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
+}
+interface CacheWriteBehindOptions {
+    flushIntervalMs?: number;
+    batchSize?: number;
+    maxQueueSize?: number;
+}
 interface CacheWarmEntry<T = unknown> {
     key: string;
     fetcher: () => Promise<T>;
@@ -225,6 +266,12 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+interface CacheHealthCheckResult {
+    layer: string;
+    healthy: boolean;
+    latencyMs: number;
+    error?: string;
+}
 /** Detailed inspection result for a single cache key. */
 interface CacheInspectResult {
     key: string;
@@ -293,6 +340,8 @@ interface CacheStackEvents {
 declare class CacheNamespace {
     private readonly cache;
     private readonly prefix;
+    private static readonly metricsMutexes;
+    private metrics;
     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>;
@@ -309,7 +358,9 @@ declare class CacheNamespace {
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
     /**
      * Returns detailed metadata about a single cache key within this namespace.
      */
@@ -329,6 +380,8 @@ declare class CacheNamespace {
      */
     namespace(childPrefix: string): CacheNamespace;
     qualify(key: string): string;
+    private trackMetrics;
+    private getMetricsMutex;
 }
 
 /** Typed overloads for EventEmitter so callers get autocomplete on event names. */
@@ -336,6 +389,9 @@ 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;
+    removeAllListeners<K extends keyof CacheStackEvents>(event?: K): this;
+    listeners<K extends keyof CacheStackEvents>(event: K): Array<(data: CacheStackEvents[K]) => void>;
+    listenerCount<K extends keyof CacheStackEvents>(event: K): number;
     emit<K extends keyof CacheStackEvents>(event: K, data: CacheStackEvents[K]): boolean;
 }
 declare class CacheStack extends EventEmitter {
@@ -348,10 +404,15 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly fetchRateLimiter;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private currentGeneration?;
+    private readonly writeBehindQueue;
+    private writeBehindTimer?;
+    private writeBehindFlushPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -409,7 +470,9 @@ declare class CacheStack extends EventEmitter {
      */
     namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
@@ -417,6 +480,8 @@ declare class CacheStack extends EventEmitter {
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    healthCheck(): Promise<CacheHealthCheckResult[]>;
+    bumpGeneration(nextGeneration?: number): number;
     /**
      * Returns detailed metadata about a single cache key: which layers contain it,
      * remaining fresh/stale/error TTLs, and associated tags.
@@ -433,6 +498,7 @@ declare class CacheStack extends EventEmitter {
     private waitForFreshValue;
     private fetchAndPopulate;
     private storeEntry;
+    private writeBatch;
     private readFromLayers;
     private readLayerEntry;
     private backfill;
@@ -450,13 +516,27 @@ declare class CacheStack extends EventEmitter {
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
+    private initializeWriteBehind;
+    private shouldWriteBehind;
+    private enqueueWriteBehind;
+    private flushWriteBehindQueue;
+    private buildLayerSetEntry;
+    private intersectKeys;
+    private qualifyKey;
+    private qualifyPattern;
+    private stripQualifiedKey;
+    private generationPrefix;
     private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
+    private validateTtlPolicy;
+    private assertActive;
+    private awaitStartup;
     private serializeOptions;
     private validateAdaptiveTtlOptions;
     private validateCircuitBreakerOptions;

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

@@ -9,6 +9,7 @@ interface LayerTtlMap {
 interface CacheWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
+    ttlPolicy?: CacheTtlPolicy;
     negativeCache?: boolean;
     negativeTtl?: number | LayerTtlMap;
     staleWhileRevalidate?: number | LayerTtlMap;
@@ -18,6 +19,7 @@ interface CacheWriteOptions {
     refreshAhead?: number | LayerTtlMap;
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
     /**
      * 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
@@ -47,12 +49,20 @@ interface CacheLayer {
     readonly isLocal?: boolean;
     get<T>(key: string): Promise<T | null>;
     getEntry?<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Bulk read fast-path. Implementations should return raw stored entries using
+     * the same semantics as `getEntry()` so CacheStack can resolve envelopes,
+     * stale windows, and negative-cache markers consistently.
+     */
     getMany?<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany?(entries: CacheLayerSetManyEntry[]): Promise<void>;
     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[]>;
+    ping?(): Promise<boolean>;
+    dispose?(): Promise<void>;
     /**
      * Returns true if the key exists and has not expired.
      * Implementations may omit this; CacheStack will fall back to `get()`.
@@ -121,11 +131,17 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    keysForPrefix?(prefix: 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>;
 }
+interface CacheLayerSetManyEntry {
+    key: string;
+    value: unknown;
+    ttl?: number;
+}
 interface InvalidationMessage {
     scope: 'key' | 'keys' | 'clear';
     sourceId: string;
@@ -140,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>;
@@ -150,6 +167,7 @@ interface CacheStackOptions {
     stampedePrevention?: boolean;
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
+    generation?: number;
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
@@ -165,10 +183,14 @@ interface CacheStackOptions {
     circuitBreaker?: CacheCircuitBreakerOptions;
     gracefulDegradation?: boolean | CacheDegradationOptions;
     writePolicy?: 'strict' | 'best-effort';
+    writeStrategy?: 'write-through' | 'write-behind';
+    writeBehind?: CacheWriteBehindOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -181,6 +203,13 @@ interface CacheAdaptiveTtlOptions {
     step?: number | LayerTtlMap;
     maxTtl?: number | LayerTtlMap;
 }
+type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
+    alignTo: number;
+} | ((context: CacheTtlPolicyContext) => number | undefined);
+interface CacheTtlPolicyContext {
+    key: string;
+    value: unknown;
+}
 interface CacheCircuitBreakerOptions {
     failureThreshold?: number;
     cooldownMs?: number;
@@ -188,6 +217,18 @@ interface CacheCircuitBreakerOptions {
 interface CacheDegradationOptions {
     retryAfterMs?: number;
 }
+interface CacheRateLimitOptions {
+    maxConcurrent?: number;
+    intervalMs?: number;
+    maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
+}
+interface CacheWriteBehindOptions {
+    flushIntervalMs?: number;
+    batchSize?: number;
+    maxQueueSize?: number;
+}
 interface CacheWarmEntry<T = unknown> {
     key: string;
     fetcher: () => Promise<T>;
@@ -225,6 +266,12 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+interface CacheHealthCheckResult {
+    layer: string;
+    healthy: boolean;
+    latencyMs: number;
+    error?: string;
+}
 /** Detailed inspection result for a single cache key. */
 interface CacheInspectResult {
     key: string;
@@ -293,6 +340,8 @@ interface CacheStackEvents {
 declare class CacheNamespace {
     private readonly cache;
     private readonly prefix;
+    private static readonly metricsMutexes;
+    private metrics;
     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>;
@@ -309,7 +358,9 @@ declare class CacheNamespace {
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
     /**
      * Returns detailed metadata about a single cache key within this namespace.
      */
@@ -329,6 +380,8 @@ declare class CacheNamespace {
      */
     namespace(childPrefix: string): CacheNamespace;
     qualify(key: string): string;
+    private trackMetrics;
+    private getMetricsMutex;
 }
 
 /** Typed overloads for EventEmitter so callers get autocomplete on event names. */
@@ -336,6 +389,9 @@ 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;
+    removeAllListeners<K extends keyof CacheStackEvents>(event?: K): this;
+    listeners<K extends keyof CacheStackEvents>(event: K): Array<(data: CacheStackEvents[K]) => void>;
+    listenerCount<K extends keyof CacheStackEvents>(event: K): number;
     emit<K extends keyof CacheStackEvents>(event: K, data: CacheStackEvents[K]): boolean;
 }
 declare class CacheStack extends EventEmitter {
@@ -348,10 +404,15 @@ declare class CacheStack extends EventEmitter {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly fetchRateLimiter;
     private readonly backgroundRefreshes;
     private readonly layerDegradedUntil;
     private readonly ttlResolver;
     private readonly circuitBreakerManager;
+    private currentGeneration?;
+    private readonly writeBehindQueue;
+    private writeBehindTimer?;
+    private writeBehindFlushPromise?;
     private isDisconnecting;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
@@ -409,7 +470,9 @@ declare class CacheStack extends EventEmitter {
      */
     namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
@@ -417,6 +480,8 @@ declare class CacheStack extends EventEmitter {
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    healthCheck(): Promise<CacheHealthCheckResult[]>;
+    bumpGeneration(nextGeneration?: number): number;
     /**
      * Returns detailed metadata about a single cache key: which layers contain it,
      * remaining fresh/stale/error TTLs, and associated tags.
@@ -433,6 +498,7 @@ declare class CacheStack extends EventEmitter {
     private waitForFreshValue;
     private fetchAndPopulate;
     private storeEntry;
+    private writeBatch;
     private readFromLayers;
     private readLayerEntry;
     private backfill;
@@ -450,13 +516,27 @@ declare class CacheStack extends EventEmitter {
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
+    private initializeWriteBehind;
+    private shouldWriteBehind;
+    private enqueueWriteBehind;
+    private flushWriteBehindQueue;
+    private buildLayerSetEntry;
+    private intersectKeys;
+    private qualifyKey;
+    private qualifyPattern;
+    private stripQualifiedKey;
+    private generationPrefix;
     private deleteKeysFromLayers;
     private validateConfiguration;
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
+    private validateTtlPolicy;
+    private assertActive;
+    private awaitStartup;
     private serializeOptions;
     private validateAdaptiveTtlOptions;
     private validateCircuitBreakerOptions;