layercache 2.1.0 → 3.1.0

package/dist/index.d.cts

@@ -1,8 +1,32 @@
-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-BCU8D-Yd.cjs';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BCU8D-Yd.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-LBUuZAdr.cjs';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryResult, p as CacheEntryWriteKind, q as CacheEntryWriteOptions, r as CacheFetcher, s as CacheFetcherContext, t as CacheHealthCheckResult, u as CacheHitRateSnapshot, v as CacheInspectResult, w as CacheLayerLatency, x as CacheMGetEntry, y as CacheMSetEntry, z as CacheMetricsSnapshot, A as CacheMissError, B as CacheNamespace, D as CacheRateLimitOptions, E as CacheSnapshotEntry, F as CacheStackEvents, G as CacheStackOptions, H as CacheStatsSnapshot, J as CacheTtlPolicy, K as CacheTtlPolicyContext, L as CacheWarmEntry, M as CacheWarmOptions, N as CacheWarmProgress, O as CacheWriteBehindOptions, P as CacheWriteOptions, Q as EvictionPolicy, R as LayerTtlMap, S as MemoryLayer, T as MemoryLayerOptions, U as MemoryLayerSnapshotEntry, V as PatternMatcher, W as TagIndex, X as createHonoCacheMiddleware } from './edge-LBUuZAdr.cjs';
 import Redis from 'ioredis';
 import 'node:events';
 
+interface RedisGenerationClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: 'NX'): Promise<unknown>;
+    incr(key: string): Promise<number>;
+}
+interface RedisGenerationStoreOptions {
+    /** Redis client used to persist and atomically bump the generation. */
+    client: RedisGenerationClient;
+    /** Redis key storing the active generation. Defaults to `layercache:generation`. */
+    key?: string;
+}
+declare class RedisGenerationStore {
+    private readonly client;
+    private readonly key;
+    constructor(options: RedisGenerationStoreOptions);
+    get(): Promise<number | undefined>;
+    getOrInitialize(initialGeneration?: number): Promise<number>;
+    set(generation: number): Promise<void>;
+    bump(): Promise<number>;
+    private parseGeneration;
+    private assertGeneration;
+    private isGeneration;
+}
+
 interface RedisInvalidationBusOptions {
     /** Redis client used to publish invalidation messages. */
     publisher: Redis;
@@ -10,6 +34,11 @@ interface RedisInvalidationBusOptions {
     subscriber?: Redis;
     /** Pub/sub channel name. Defaults to `layercache:invalidation`. */
     channel?: string;
+    /**
+     * Optional shared secret used to sign and verify invalidation messages.
+     * When configured, unsigned or invalidly signed messages are rejected.
+     */
+    signingSecret?: string | Buffer;
     /** Optional logger for invalid payloads or subscriber errors. */
     logger?: CacheLogger;
 }
@@ -25,6 +54,7 @@ declare class RedisInvalidationBus implements InvalidationBus {
     private readonly publisher;
     private readonly subscriber;
     private readonly logger?;
+    private readonly signingKey?;
     private readonly handlers;
     private sharedListener?;
     private subscribePromise;
@@ -39,6 +69,9 @@ declare class RedisInvalidationBus implements InvalidationBus {
     publish(message: InvalidationMessage): Promise<void>;
     private dispatchToHandlers;
     private isInvalidationMessage;
+    private signMessage;
+    private verifySignedEnvelope;
+    private createSignature;
     private reportError;
 }
 
@@ -51,12 +84,19 @@ interface RedisTagIndexOptions {
     scanCount?: number;
     /** Number of shards for known-key sets. Defaults to 16. */
     knownKeysShards?: number;
+    /** Optional logger for legacy index warnings. */
+    logger?: CacheLogger;
+}
+interface RedisTagIndexMigrationResult {
+    migratedKeys: number;
 }
 declare class RedisTagIndex implements CacheTagIndex {
     private readonly client;
     private readonly prefix;
     private readonly scanCount;
     private readonly knownKeysShards;
+    private readonly logger?;
+    private warnedLegacyKnownKeys;
     constructor(options: RedisTagIndexOptions);
     /**
      * Records a key as known without changing tag assignments.
@@ -102,9 +142,13 @@ declare class RedisTagIndex implements CacheTagIndex {
      * Clears all Redis tag-index state under this prefix.
      */
     clear(): Promise<void>;
+    migrateLegacyKnownKeys(): Promise<RedisTagIndexMigrationResult>;
     private scanIndexKeys;
     private knownKeysKeyFor;
+    private knownKeysKeysForRead;
     private knownKeysKeys;
+    private legacyKnownKeysKey;
+    private warnLegacyKnownKeys;
     private keyTagsKey;
     private tagKeysKey;
 }
@@ -436,6 +480,11 @@ interface DiskLayerOptions {
      * Set to `false` to disable the limit.
      */
     maxEntryBytes?: number | false;
+    /**
+     * Maximum pending write operations allowed in the serialized write queue.
+     * Defaults to 10,000. Set to `false` to disable the guard.
+     */
+    maxWriteQueueDepth?: 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.
@@ -469,8 +518,10 @@ declare class DiskLayer implements CacheLayer {
     private readonly serializer;
     private readonly maxFiles;
     private readonly maxEntryBytes;
+    private readonly maxWriteQueueDepth;
     private readonly protection;
     private writeQueue;
+    private writeQueueDepth;
     /**
      * Creates a disk-backed cache layer.
      */
@@ -540,6 +591,7 @@ declare class DiskLayer implements CacheLayer {
     private resolveDirectory;
     private normalizeMaxFiles;
     private normalizeMaxEntryBytes;
+    private normalizeMaxWriteQueueDepth;
     private readEntryFile;
     private readHandleWithLimit;
     private scanEntries;
@@ -746,4 +798,4 @@ declare function createPrometheusMetricsExporter(stacks: CacheStack | Array<{
     name: string;
 }>): () => string;
 
-export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };
+export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisGenerationStore, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };

package/dist/index.d.ts

@@ -1,8 +1,32 @@
-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-BCU8D-Yd.js';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BCU8D-Yd.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-LBUuZAdr.js';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryResult, p as CacheEntryWriteKind, q as CacheEntryWriteOptions, r as CacheFetcher, s as CacheFetcherContext, t as CacheHealthCheckResult, u as CacheHitRateSnapshot, v as CacheInspectResult, w as CacheLayerLatency, x as CacheMGetEntry, y as CacheMSetEntry, z as CacheMetricsSnapshot, A as CacheMissError, B as CacheNamespace, D as CacheRateLimitOptions, E as CacheSnapshotEntry, F as CacheStackEvents, G as CacheStackOptions, H as CacheStatsSnapshot, J as CacheTtlPolicy, K as CacheTtlPolicyContext, L as CacheWarmEntry, M as CacheWarmOptions, N as CacheWarmProgress, O as CacheWriteBehindOptions, P as CacheWriteOptions, Q as EvictionPolicy, R as LayerTtlMap, S as MemoryLayer, T as MemoryLayerOptions, U as MemoryLayerSnapshotEntry, V as PatternMatcher, W as TagIndex, X as createHonoCacheMiddleware } from './edge-LBUuZAdr.js';
 import Redis from 'ioredis';
 import 'node:events';
 
+interface RedisGenerationClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: 'NX'): Promise<unknown>;
+    incr(key: string): Promise<number>;
+}
+interface RedisGenerationStoreOptions {
+    /** Redis client used to persist and atomically bump the generation. */
+    client: RedisGenerationClient;
+    /** Redis key storing the active generation. Defaults to `layercache:generation`. */
+    key?: string;
+}
+declare class RedisGenerationStore {
+    private readonly client;
+    private readonly key;
+    constructor(options: RedisGenerationStoreOptions);
+    get(): Promise<number | undefined>;
+    getOrInitialize(initialGeneration?: number): Promise<number>;
+    set(generation: number): Promise<void>;
+    bump(): Promise<number>;
+    private parseGeneration;
+    private assertGeneration;
+    private isGeneration;
+}
+
 interface RedisInvalidationBusOptions {
     /** Redis client used to publish invalidation messages. */
     publisher: Redis;
@@ -10,6 +34,11 @@ interface RedisInvalidationBusOptions {
     subscriber?: Redis;
     /** Pub/sub channel name. Defaults to `layercache:invalidation`. */
     channel?: string;
+    /**
+     * Optional shared secret used to sign and verify invalidation messages.
+     * When configured, unsigned or invalidly signed messages are rejected.
+     */
+    signingSecret?: string | Buffer;
     /** Optional logger for invalid payloads or subscriber errors. */
     logger?: CacheLogger;
 }
@@ -25,6 +54,7 @@ declare class RedisInvalidationBus implements InvalidationBus {
     private readonly publisher;
     private readonly subscriber;
     private readonly logger?;
+    private readonly signingKey?;
     private readonly handlers;
     private sharedListener?;
     private subscribePromise;
@@ -39,6 +69,9 @@ declare class RedisInvalidationBus implements InvalidationBus {
     publish(message: InvalidationMessage): Promise<void>;
     private dispatchToHandlers;
     private isInvalidationMessage;
+    private signMessage;
+    private verifySignedEnvelope;
+    private createSignature;
     private reportError;
 }
 
@@ -51,12 +84,19 @@ interface RedisTagIndexOptions {
     scanCount?: number;
     /** Number of shards for known-key sets. Defaults to 16. */
     knownKeysShards?: number;
+    /** Optional logger for legacy index warnings. */
+    logger?: CacheLogger;
+}
+interface RedisTagIndexMigrationResult {
+    migratedKeys: number;
 }
 declare class RedisTagIndex implements CacheTagIndex {
     private readonly client;
     private readonly prefix;
     private readonly scanCount;
     private readonly knownKeysShards;
+    private readonly logger?;
+    private warnedLegacyKnownKeys;
     constructor(options: RedisTagIndexOptions);
     /**
      * Records a key as known without changing tag assignments.
@@ -102,9 +142,13 @@ declare class RedisTagIndex implements CacheTagIndex {
      * Clears all Redis tag-index state under this prefix.
      */
     clear(): Promise<void>;
+    migrateLegacyKnownKeys(): Promise<RedisTagIndexMigrationResult>;
     private scanIndexKeys;
     private knownKeysKeyFor;
+    private knownKeysKeysForRead;
     private knownKeysKeys;
+    private legacyKnownKeysKey;
+    private warnLegacyKnownKeys;
     private keyTagsKey;
     private tagKeysKey;
 }
@@ -436,6 +480,11 @@ interface DiskLayerOptions {
      * Set to `false` to disable the limit.
      */
     maxEntryBytes?: number | false;
+    /**
+     * Maximum pending write operations allowed in the serialized write queue.
+     * Defaults to 10,000. Set to `false` to disable the guard.
+     */
+    maxWriteQueueDepth?: 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.
@@ -469,8 +518,10 @@ declare class DiskLayer implements CacheLayer {
     private readonly serializer;
     private readonly maxFiles;
     private readonly maxEntryBytes;
+    private readonly maxWriteQueueDepth;
     private readonly protection;
     private writeQueue;
+    private writeQueueDepth;
     /**
      * Creates a disk-backed cache layer.
      */
@@ -540,6 +591,7 @@ declare class DiskLayer implements CacheLayer {
     private resolveDirectory;
     private normalizeMaxFiles;
     private normalizeMaxEntryBytes;
+    private normalizeMaxWriteQueueDepth;
     private readEntryFile;
     private readHandleWithLimit;
     private scanEntries;
@@ -746,4 +798,4 @@ declare function createPrometheusMetricsExporter(stacks: CacheStack | Array<{
     name: string;
 }>): () => string;
 
-export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };
+export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisGenerationStore, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };