layercache 1.2.9 → 1.3.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BXWTKlI1.cjs';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-BXWTKlI1.cjs';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-CUHTP9Bc.cjs';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-CUHTP9Bc.cjs';
 import Redis from 'ioredis';
 import 'node:events';
 
@@ -63,6 +63,11 @@ declare class RedisTagIndex implements CacheTagIndex {
 }
 
 interface CacheStatsHandlerOptions {
+    /**
+     * @deprecated Exposing cache stats without authentication is a security risk.
+     * Provide an `authorize` callback instead. This option will be removed in a
+     * future release.
+     */
     allowPublicAccess?: boolean;
     authorize?: (request: unknown) => boolean | Promise<boolean>;
     unauthorizedStatusCode?: number;
@@ -91,6 +96,11 @@ interface FastifyLikeReply {
 interface FastifyLayercachePluginOptions {
     exposeStatsRoute?: boolean;
     statsPath?: string;
+    /**
+     * @deprecated Exposing cache stats without authentication is a security risk.
+     * Provide an `authorizeStatsRoute` callback instead. This option will be
+     * removed in a future release.
+     */
     allowPublicStatsRoute?: boolean;
     authorizeStatsRoute?: (request: unknown) => boolean | Promise<boolean>;
     unauthorizedStatusCode?: number;
@@ -203,6 +213,11 @@ interface RedisLayerOptions {
      * Prevents decompression bomb attacks. Defaults to 64 MiB.
      */
     decompressionMaxBytes?: number;
+    /**
+     * Per-command timeout in milliseconds for Redis round-trips.
+     * Slow commands reject so CacheStack can treat the layer as degraded.
+     */
+    commandTimeoutMs?: number;
     disconnectOnDispose?: boolean;
 }
 declare class RedisLayer implements CacheLayer {
@@ -217,6 +232,7 @@ declare class RedisLayer implements CacheLayer {
     private readonly compression?;
     private readonly compressionThreshold;
     private readonly decompressionMaxBytes;
+    private readonly commandTimeoutMs;
     private readonly disconnectOnDispose;
     constructor(options: RedisLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -240,6 +256,8 @@ declare class RedisLayer implements CacheLayer {
     forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     private scanKeys;
     private withPrefix;
+    private validateKey;
+    private displayKey;
     private deserializeOrDelete;
     private deleteCorruptedKey;
     private rewriteWithPrimarySerializer;
@@ -256,6 +274,8 @@ declare class RedisLayer implements CacheLayer {
      */
     private decodePayload;
     private decompressWithLimit;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
 interface DiskLayerOptions {
@@ -266,7 +286,8 @@ interface DiskLayerOptions {
     /**
      * Maximum number of cache files to store on disk. When exceeded, the oldest
      * entries (by file mtime) are evicted to keep the directory bounded.
-     * Defaults to unlimited.
+     * Defaults to 50 000. Set to `Infinity` to disable the limit (not recommended
+     * in production — unbounded growth will eventually exhaust disk space).
      */
     maxFiles?: number;
     /**
@@ -275,6 +296,19 @@ interface DiskLayerOptions {
      * Set to `false` to disable the limit.
      */
     maxEntryBytes?: number | false;
+    /**
+     * Encrypt cached data at rest using AES-256-GCM. Accepts a string or Buffer.
+     * The key material is hashed with SHA-256 to derive the actual cipher key.
+     * Encryption also provides authenticated integrity — a separate signingKey
+     * is unnecessary when encryption is enabled.
+     */
+    encryptionKey?: string | Buffer;
+    /**
+     * Sign cached data at rest using HMAC-SHA256 for integrity verification.
+     * Accepts a string or Buffer. Ignored when `encryptionKey` is also provided
+     * (AES-GCM already provides integrity).
+     */
+    signingKey?: string | Buffer;
 }
 /**
  * A file-system backed cache layer.
@@ -295,6 +329,7 @@ declare class DiskLayer implements CacheLayer {
     private readonly serializer;
     private readonly maxFiles;
     private readonly maxEntryBytes;
+    private readonly protection;
     private writeQueue;
     constructor(options: DiskLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -408,19 +443,41 @@ declare class MsgpackSerializer implements CacheSerializer {
 interface RedisSingleFlightCoordinatorOptions {
     client: Redis;
     prefix?: string;
+    commandTimeoutMs?: number;
 }
 declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinator {
     private readonly client;
     private readonly prefix;
+    private readonly commandTimeoutMs;
     constructor(options: RedisSingleFlightCoordinatorOptions);
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
     private startLeaseRenewal;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
+interface StampedeGuardOptions {
+    /**
+     * Maximum number of concurrent in-flight keys. When exceeded, new `execute`
+     * calls for keys that are not already in-flight will throw immediately.
+     * Defaults to 10 000.
+     */
+    maxInFlight?: number;
+    /**
+     * Maximum milliseconds to wait for a single in-flight task before rejecting
+     * with a timeout error. When a timeout fires the entry is released so
+     * subsequent callers can retry. Defaults to no timeout.
+     */
+    entryTimeoutMs?: number;
+}
 declare class StampedeGuard {
-    private readonly mutexes;
+    private readonly inFlight;
+    private readonly maxInFlight;
+    private readonly entryTimeoutMs;
+    constructor(options?: StampedeGuardOptions);
     execute<T>(key: string, task: () => Promise<T>): Promise<T>;
-    private getMutexEntry;
+    private withTimeout;
+    private releaseEntry;
 }
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BXWTKlI1.js';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-BXWTKlI1.js';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-CUHTP9Bc.js';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-CUHTP9Bc.js';
 import Redis from 'ioredis';
 import 'node:events';
 
@@ -63,6 +63,11 @@ declare class RedisTagIndex implements CacheTagIndex {
 }
 
 interface CacheStatsHandlerOptions {
+    /**
+     * @deprecated Exposing cache stats without authentication is a security risk.
+     * Provide an `authorize` callback instead. This option will be removed in a
+     * future release.
+     */
     allowPublicAccess?: boolean;
     authorize?: (request: unknown) => boolean | Promise<boolean>;
     unauthorizedStatusCode?: number;
@@ -91,6 +96,11 @@ interface FastifyLikeReply {
 interface FastifyLayercachePluginOptions {
     exposeStatsRoute?: boolean;
     statsPath?: string;
+    /**
+     * @deprecated Exposing cache stats without authentication is a security risk.
+     * Provide an `authorizeStatsRoute` callback instead. This option will be
+     * removed in a future release.
+     */
     allowPublicStatsRoute?: boolean;
     authorizeStatsRoute?: (request: unknown) => boolean | Promise<boolean>;
     unauthorizedStatusCode?: number;
@@ -203,6 +213,11 @@ interface RedisLayerOptions {
      * Prevents decompression bomb attacks. Defaults to 64 MiB.
      */
     decompressionMaxBytes?: number;
+    /**
+     * Per-command timeout in milliseconds for Redis round-trips.
+     * Slow commands reject so CacheStack can treat the layer as degraded.
+     */
+    commandTimeoutMs?: number;
     disconnectOnDispose?: boolean;
 }
 declare class RedisLayer implements CacheLayer {
@@ -217,6 +232,7 @@ declare class RedisLayer implements CacheLayer {
     private readonly compression?;
     private readonly compressionThreshold;
     private readonly decompressionMaxBytes;
+    private readonly commandTimeoutMs;
     private readonly disconnectOnDispose;
     constructor(options: RedisLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -240,6 +256,8 @@ declare class RedisLayer implements CacheLayer {
     forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     private scanKeys;
     private withPrefix;
+    private validateKey;
+    private displayKey;
     private deserializeOrDelete;
     private deleteCorruptedKey;
     private rewriteWithPrimarySerializer;
@@ -256,6 +274,8 @@ declare class RedisLayer implements CacheLayer {
      */
     private decodePayload;
     private decompressWithLimit;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
 interface DiskLayerOptions {
@@ -266,7 +286,8 @@ interface DiskLayerOptions {
     /**
      * Maximum number of cache files to store on disk. When exceeded, the oldest
      * entries (by file mtime) are evicted to keep the directory bounded.
-     * Defaults to unlimited.
+     * Defaults to 50 000. Set to `Infinity` to disable the limit (not recommended
+     * in production — unbounded growth will eventually exhaust disk space).
      */
     maxFiles?: number;
     /**
@@ -275,6 +296,19 @@ interface DiskLayerOptions {
      * Set to `false` to disable the limit.
      */
     maxEntryBytes?: number | false;
+    /**
+     * Encrypt cached data at rest using AES-256-GCM. Accepts a string or Buffer.
+     * The key material is hashed with SHA-256 to derive the actual cipher key.
+     * Encryption also provides authenticated integrity — a separate signingKey
+     * is unnecessary when encryption is enabled.
+     */
+    encryptionKey?: string | Buffer;
+    /**
+     * Sign cached data at rest using HMAC-SHA256 for integrity verification.
+     * Accepts a string or Buffer. Ignored when `encryptionKey` is also provided
+     * (AES-GCM already provides integrity).
+     */
+    signingKey?: string | Buffer;
 }
 /**
  * A file-system backed cache layer.
@@ -295,6 +329,7 @@ declare class DiskLayer implements CacheLayer {
     private readonly serializer;
     private readonly maxFiles;
     private readonly maxEntryBytes;
+    private readonly protection;
     private writeQueue;
     constructor(options: DiskLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -408,19 +443,41 @@ declare class MsgpackSerializer implements CacheSerializer {
 interface RedisSingleFlightCoordinatorOptions {
     client: Redis;
     prefix?: string;
+    commandTimeoutMs?: number;
 }
 declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinator {
     private readonly client;
     private readonly prefix;
+    private readonly commandTimeoutMs;
     constructor(options: RedisSingleFlightCoordinatorOptions);
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
     private startLeaseRenewal;
+    private normalizeCommandTimeoutMs;
+    private runCommand;
 }
 
+interface StampedeGuardOptions {
+    /**
+     * Maximum number of concurrent in-flight keys. When exceeded, new `execute`
+     * calls for keys that are not already in-flight will throw immediately.
+     * Defaults to 10 000.
+     */
+    maxInFlight?: number;
+    /**
+     * Maximum milliseconds to wait for a single in-flight task before rejecting
+     * with a timeout error. When a timeout fires the entry is released so
+     * subsequent callers can retry. Defaults to no timeout.
+     */
+    entryTimeoutMs?: number;
+}
 declare class StampedeGuard {
-    private readonly mutexes;
+    private readonly inFlight;
+    private readonly maxInFlight;
+    private readonly entryTimeoutMs;
+    constructor(options?: StampedeGuardOptions);
     execute<T>(key: string, task: () => Promise<T>): Promise<T>;
-    private getMutexEntry;
+    private withTimeout;
+    private releaseEntry;
 }
 
 /**