layercache 1.2.5 → 1.2.6

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-P07GCO2Y.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-P07GCO2Y.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-DLstcDMn.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-DLstcDMn.cjs';
 import Redis from 'ioredis';
 import 'node:events';
 
@@ -47,9 +47,12 @@ declare class RedisTagIndex implements CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    forEachKeyForTag(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     keysForPrefix(prefix: string): Promise<string[]>;
+    forEachKeyForPrefix(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
+    forEachKeyMatchingPattern(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     clear(): Promise<void>;
     private scanIndexKeys;
     private knownKeysKeyFor;
@@ -58,7 +61,12 @@ declare class RedisTagIndex implements CacheTagIndex {
     private tagKeysKey;
 }
 
-declare function createCacheStatsHandler(cache: CacheStack): (_request: unknown, response: {
+interface CacheStatsHandlerOptions {
+    allowPublicAccess?: boolean;
+    authorize?: (request: unknown) => boolean | Promise<boolean>;
+    unauthorizedStatusCode?: number;
+}
+declare function createCacheStatsHandler(cache: CacheStack, options?: CacheStatsHandlerOptions): (request: unknown, response: {
     setHeader?: (name: string, value: string) => void;
     end: (body: string) => void;
     statusCode?: number;
@@ -72,11 +80,19 @@ declare function createCachedMethodDecorator<TArgs extends unknown[] = unknown[]
 
 interface FastifyLike {
     decorate: (name: string, value: unknown) => void;
-    get?: (path: string, handler: () => unknown | Promise<unknown>) => void;
+    get?: (path: string, handler: (request: unknown, reply: FastifyLikeReply) => unknown | Promise<unknown>) => void;
+}
+interface FastifyLikeReply {
+    header?: (name: string, value: string) => unknown;
+    send?: (body: unknown) => unknown;
+    statusCode?: number;
 }
 interface FastifyLayercachePluginOptions {
     exposeStatsRoute?: boolean;
     statsPath?: string;
+    allowPublicStatsRoute?: boolean;
+    authorizeStatsRoute?: (request: unknown) => boolean | Promise<boolean>;
+    unauthorizedStatusCode?: number;
 }
 declare function createFastifyLayercachePlugin(cache: CacheStack, options?: FastifyLayercachePluginOptions): (fastify: FastifyLike) => Promise<void>;
 
@@ -86,6 +102,8 @@ interface ExpressLikeRequest {
     originalUrl?: string;
     path?: string;
     query?: Record<string, unknown>;
+    headers?: Headers | Record<string, unknown>;
+    get?: (name: string) => string | undefined | null;
 }
 interface ExpressLikeResponse {
     statusCode?: number;
@@ -104,6 +122,8 @@ interface ExpressCacheMiddlewareOptions extends CacheGetOptions {
      * Only cache responses for these HTTP methods. Defaults to `['GET']`.
      */
     methods?: string[];
+    /** Explicitly allow URL-only implicit cache keys. Disabled by default. */
+    allowPrivateCaching?: boolean;
 }
 /**
  * Express/Connect-compatible middleware that caches JSON responses.
@@ -124,6 +144,7 @@ declare function createExpressCacheMiddleware(cache: CacheStack, options?: Expre
 
 interface GraphqlCacheOptions<TArgs extends unknown[]> extends CacheGetOptions {
     keyResolver?: (...args: TArgs) => string;
+    allowImplicitContextCaching?: boolean;
 }
 declare function cacheGraphqlResolver<TArgs extends unknown[], TResult>(cache: CacheStack, prefix: string, resolver: (...args: TArgs) => Promise<TResult>, options?: GraphqlCacheOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
 
@@ -159,6 +180,7 @@ interface TrpcCacheMiddlewareContext<TInput = unknown, TResult = unknown> {
 }
 interface TrpcCacheMiddlewareOptions<TInput> extends CacheGetOptions {
     keyResolver?: (input: TInput, path?: string, type?: string) => string;
+    allowImplicitContextCaching?: boolean;
 }
 declare function createTrpcCacheMiddleware<TInput = unknown, TResult = unknown>(cache: CacheStack, prefix: string, options?: TrpcCacheMiddlewareOptions<TInput>): (context: TrpcCacheMiddlewareContext<TInput, TResult>) => Promise<{
     ok: boolean;
@@ -215,9 +237,11 @@ declare class RedisLayer implements CacheLayer {
      */
     clear(): Promise<void>;
     keys(): Promise<string[]>;
+    forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     private scanKeys;
     private withPrefix;
     private deserializeOrDelete;
+    private deleteCorruptedKey;
     private rewriteWithPrimarySerializer;
     private primarySerializer;
     private isSerializablePayload;
@@ -231,6 +255,7 @@ declare class RedisLayer implements CacheLayer {
      * Enforces a maximum decompressed size to prevent decompression bomb attacks.
      */
     private decodePayload;
+    private decompressWithLimit;
 }
 
 interface DiskLayerOptions {
@@ -244,6 +269,12 @@ interface DiskLayerOptions {
      * Defaults to unlimited.
      */
     maxFiles?: number;
+    /**
+     * Maximum size, in bytes, of a single cache file that this layer will read.
+     * Oversized entries are treated as corrupted and removed. Defaults to 16 MiB.
+     * Set to `false` to disable the limit.
+     */
+    maxEntryBytes?: number | false;
 }
 /**
  * A file-system backed cache layer.
@@ -263,6 +294,7 @@ declare class DiskLayer implements CacheLayer {
     private readonly directory;
     private readonly serializer;
     private readonly maxFiles;
+    private readonly maxEntryBytes;
     private writeQueue;
     constructor(options: DiskLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -280,12 +312,18 @@ declare class DiskLayer implements CacheLayer {
      * Expired entries are skipped and cleaned up during the scan.
      */
     keys(): Promise<string[]>;
+    forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     size(): Promise<number>;
     ping(): Promise<boolean>;
     dispose(): Promise<void>;
     private keyToPath;
     private resolveDirectory;
     private normalizeMaxFiles;
+    private normalizeMaxEntryBytes;
+    private readEntryFile;
+    private readHandleWithLimit;
+    private scanEntries;
+    private deletePathsWithConcurrency;
     private deserializeEntry;
     private safeDelete;
     private enqueueWrite;

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-P07GCO2Y.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-P07GCO2Y.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-DLstcDMn.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-DLstcDMn.js';
 import Redis from 'ioredis';
 import 'node:events';
 
@@ -47,9 +47,12 @@ declare class RedisTagIndex implements CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    forEachKeyForTag(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     keysForPrefix(prefix: string): Promise<string[]>;
+    forEachKeyForPrefix(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
+    forEachKeyMatchingPattern(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     clear(): Promise<void>;
     private scanIndexKeys;
     private knownKeysKeyFor;
@@ -58,7 +61,12 @@ declare class RedisTagIndex implements CacheTagIndex {
     private tagKeysKey;
 }
 
-declare function createCacheStatsHandler(cache: CacheStack): (_request: unknown, response: {
+interface CacheStatsHandlerOptions {
+    allowPublicAccess?: boolean;
+    authorize?: (request: unknown) => boolean | Promise<boolean>;
+    unauthorizedStatusCode?: number;
+}
+declare function createCacheStatsHandler(cache: CacheStack, options?: CacheStatsHandlerOptions): (request: unknown, response: {
     setHeader?: (name: string, value: string) => void;
     end: (body: string) => void;
     statusCode?: number;
@@ -72,11 +80,19 @@ declare function createCachedMethodDecorator<TArgs extends unknown[] = unknown[]
 
 interface FastifyLike {
     decorate: (name: string, value: unknown) => void;
-    get?: (path: string, handler: () => unknown | Promise<unknown>) => void;
+    get?: (path: string, handler: (request: unknown, reply: FastifyLikeReply) => unknown | Promise<unknown>) => void;
+}
+interface FastifyLikeReply {
+    header?: (name: string, value: string) => unknown;
+    send?: (body: unknown) => unknown;
+    statusCode?: number;
 }
 interface FastifyLayercachePluginOptions {
     exposeStatsRoute?: boolean;
     statsPath?: string;
+    allowPublicStatsRoute?: boolean;
+    authorizeStatsRoute?: (request: unknown) => boolean | Promise<boolean>;
+    unauthorizedStatusCode?: number;
 }
 declare function createFastifyLayercachePlugin(cache: CacheStack, options?: FastifyLayercachePluginOptions): (fastify: FastifyLike) => Promise<void>;
 
@@ -86,6 +102,8 @@ interface ExpressLikeRequest {
     originalUrl?: string;
     path?: string;
     query?: Record<string, unknown>;
+    headers?: Headers | Record<string, unknown>;
+    get?: (name: string) => string | undefined | null;
 }
 interface ExpressLikeResponse {
     statusCode?: number;
@@ -104,6 +122,8 @@ interface ExpressCacheMiddlewareOptions extends CacheGetOptions {
      * Only cache responses for these HTTP methods. Defaults to `['GET']`.
      */
     methods?: string[];
+    /** Explicitly allow URL-only implicit cache keys. Disabled by default. */
+    allowPrivateCaching?: boolean;
 }
 /**
  * Express/Connect-compatible middleware that caches JSON responses.
@@ -124,6 +144,7 @@ declare function createExpressCacheMiddleware(cache: CacheStack, options?: Expre
 
 interface GraphqlCacheOptions<TArgs extends unknown[]> extends CacheGetOptions {
     keyResolver?: (...args: TArgs) => string;
+    allowImplicitContextCaching?: boolean;
 }
 declare function cacheGraphqlResolver<TArgs extends unknown[], TResult>(cache: CacheStack, prefix: string, resolver: (...args: TArgs) => Promise<TResult>, options?: GraphqlCacheOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
 
@@ -159,6 +180,7 @@ interface TrpcCacheMiddlewareContext<TInput = unknown, TResult = unknown> {
 }
 interface TrpcCacheMiddlewareOptions<TInput> extends CacheGetOptions {
     keyResolver?: (input: TInput, path?: string, type?: string) => string;
+    allowImplicitContextCaching?: boolean;
 }
 declare function createTrpcCacheMiddleware<TInput = unknown, TResult = unknown>(cache: CacheStack, prefix: string, options?: TrpcCacheMiddlewareOptions<TInput>): (context: TrpcCacheMiddlewareContext<TInput, TResult>) => Promise<{
     ok: boolean;
@@ -215,9 +237,11 @@ declare class RedisLayer implements CacheLayer {
      */
     clear(): Promise<void>;
     keys(): Promise<string[]>;
+    forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     private scanKeys;
     private withPrefix;
     private deserializeOrDelete;
+    private deleteCorruptedKey;
     private rewriteWithPrimarySerializer;
     private primarySerializer;
     private isSerializablePayload;
@@ -231,6 +255,7 @@ declare class RedisLayer implements CacheLayer {
      * Enforces a maximum decompressed size to prevent decompression bomb attacks.
      */
     private decodePayload;
+    private decompressWithLimit;
 }
 
 interface DiskLayerOptions {
@@ -244,6 +269,12 @@ interface DiskLayerOptions {
      * Defaults to unlimited.
      */
     maxFiles?: number;
+    /**
+     * Maximum size, in bytes, of a single cache file that this layer will read.
+     * Oversized entries are treated as corrupted and removed. Defaults to 16 MiB.
+     * Set to `false` to disable the limit.
+     */
+    maxEntryBytes?: number | false;
 }
 /**
  * A file-system backed cache layer.
@@ -263,6 +294,7 @@ declare class DiskLayer implements CacheLayer {
     private readonly directory;
     private readonly serializer;
     private readonly maxFiles;
+    private readonly maxEntryBytes;
     private writeQueue;
     constructor(options: DiskLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -280,12 +312,18 @@ declare class DiskLayer implements CacheLayer {
      * Expired entries are skipped and cleaned up during the scan.
      */
     keys(): Promise<string[]>;
+    forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     size(): Promise<number>;
     ping(): Promise<boolean>;
     dispose(): Promise<void>;
     private keyToPath;
     private resolveDirectory;
     private normalizeMaxFiles;
+    private normalizeMaxEntryBytes;
+    private readEntryFile;
+    private readHandleWithLimit;
+    private scanEntries;
+    private deletePathsWithConcurrency;
     private deserializeEntry;
     private safeDelete;
     private enqueueWrite;