layercache 1.4.0 → 2.1.0

package/dist/index.d.cts

@@ -1,12 +1,16 @@
-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-D2FpRlyS.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-D2FpRlyS.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-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 Redis from 'ioredis';
 import 'node:events';
 
 interface RedisInvalidationBusOptions {
+    /** Redis client used to publish invalidation messages. */
     publisher: Redis;
+    /** Redis client used for subscriptions. Defaults to `publisher.duplicate()`. */
     subscriber?: Redis;
+    /** Pub/sub channel name. Defaults to `layercache:invalidation`. */
     channel?: string;
+    /** Optional logger for invalid payloads or subscriber errors. */
     logger?: CacheLogger;
 }
 /**
@@ -25,7 +29,13 @@ declare class RedisInvalidationBus implements InvalidationBus {
     private sharedListener?;
     private subscribePromise;
     constructor(options: RedisInvalidationBusOptions);
+    /**
+     * Subscribes to invalidation messages and returns an unsubscribe function.
+     */
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void>>;
+    /**
+     * Publishes an invalidation message to other subscribers.
+     */
     publish(message: InvalidationMessage): Promise<void>;
     private dispatchToHandlers;
     private isInvalidationMessage;
@@ -33,9 +43,13 @@ declare class RedisInvalidationBus implements InvalidationBus {
 }
 
 interface RedisTagIndexOptions {
+    /** Redis client used for tag and known-key sets. */
     client: Redis;
+    /** Redis key prefix for index data. Defaults to `layercache:tag-index`. */
     prefix?: string;
+    /** Redis SCAN count hint used by pattern and prefix discovery. Defaults to 100. */
     scanCount?: number;
+    /** Number of shards for known-key sets. Defaults to 16. */
     knownKeysShards?: number;
 }
 declare class RedisTagIndex implements CacheTagIndex {
@@ -44,16 +58,49 @@ declare class RedisTagIndex implements CacheTagIndex {
     private readonly scanCount;
     private readonly knownKeysShards;
     constructor(options: RedisTagIndexOptions);
+    /**
+     * Records a key as known without changing tag assignments.
+     */
     touch(key: string): Promise<void>;
+    /**
+     * Replaces the tags associated with a key and records the key as known.
+     */
     track(key: string, tags: string[]): Promise<void>;
+    /**
+     * Removes a key from all tag mappings and known-key tracking.
+     */
     remove(key: string): Promise<void>;
+    /**
+     * Returns keys currently associated with a tag.
+     */
     keysForTag(tag: string): Promise<string[]>;
+    /**
+     * Visits keys currently associated with a tag.
+     */
     forEachKeyForTag(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /**
+     * Returns known keys that start with a prefix.
+     */
     keysForPrefix(prefix: string): Promise<string[]>;
+    /**
+     * Visits known keys that start with a prefix.
+     */
     forEachKeyForPrefix(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /**
+     * Returns the tags currently associated with a key.
+     */
     tagsForKey(key: string): Promise<string[]>;
+    /**
+     * Returns known keys matching a wildcard pattern.
+     */
     matchPattern(pattern: string): Promise<string[]>;
+    /**
+     * Visits known keys matching a wildcard pattern.
+     */
     forEachKeyMatchingPattern(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /**
+     * Clears all Redis tag-index state under this prefix.
+     */
     clear(): Promise<void>;
     private scanIndexKeys;
     private knownKeysKeyFor;
@@ -69,9 +116,14 @@ interface CacheStatsHandlerOptions {
      * future release.
      */
     allowPublicAccess?: boolean;
+    /** Authorize requests before returning cache stats. Required unless `allowPublicAccess` is true. */
     authorize?: (request: unknown) => boolean | Promise<boolean>;
+    /** Status code returned when a request is unauthorized. Defaults to 403. */
     unauthorizedStatusCode?: number;
 }
+/**
+ * Creates a small Node HTTP handler that returns `cache.getStats()` as JSON.
+ */
 declare function createCacheStatsHandler(cache: CacheStack, options?: CacheStatsHandlerOptions): (request: unknown, response: {
     setHeader?: (name: string, value: string) => void;
     end: (body: string) => void;
@@ -79,9 +131,14 @@ declare function createCacheStatsHandler(cache: CacheStack, options?: CacheStats
 }) => Promise<void>;
 
 interface CachedMethodDecoratorOptions<TArgs extends unknown[]> extends CacheWrapOptions<TArgs> {
+    /** Returns the CacheStack instance used for the decorated object instance. */
     cache: (instance: unknown) => CacheStack;
+    /** Cache key prefix for the method. Defaults to the decorated property name. */
     prefix?: string;
 }
+/**
+ * Creates a method decorator that caches async method results per instance.
+ */
 declare function createCachedMethodDecorator<TArgs extends unknown[] = unknown[]>(options: CachedMethodDecoratorOptions<TArgs>): MethodDecorator;
 
 interface FastifyLike {
@@ -94,7 +151,9 @@ interface FastifyLikeReply {
     statusCode?: number;
 }
 interface FastifyLayercachePluginOptions {
+    /** Register an HTTP route that returns `cache.getStats()`. Disabled by default. */
     exposeStatsRoute?: boolean;
+    /** Path for the stats route when `exposeStatsRoute` is enabled. Defaults to `/cache/stats`. */
     statsPath?: string;
     /**
      * @deprecated Exposing cache stats without authentication is a security risk.
@@ -102,9 +161,14 @@ interface FastifyLayercachePluginOptions {
      * removed in a future release.
      */
     allowPublicStatsRoute?: boolean;
+    /** Authorize requests to the stats route. Required unless `allowPublicStatsRoute` is true. */
     authorizeStatsRoute?: (request: unknown) => boolean | Promise<boolean>;
+    /** Status code returned when a stats route request is unauthorized. Defaults to 403. */
     unauthorizedStatusCode?: number;
 }
+/**
+ * Fastify plugin that decorates the server with `cache` and can expose a protected stats route.
+ */
 declare function createFastifyLayercachePlugin(cache: CacheStack, options?: FastifyLayercachePluginOptions): (fastify: FastifyLike) => Promise<void>;
 
 interface ExpressLikeRequest {
@@ -154,9 +218,14 @@ interface ExpressCacheMiddlewareOptions extends CacheGetOptions {
 declare function createExpressCacheMiddleware(cache: CacheStack, options?: ExpressCacheMiddlewareOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: NextFunction) => Promise<void>;
 
 interface GraphqlCacheOptions<TArgs extends unknown[]> extends CacheGetOptions {
+    /** Converts resolver arguments into a stable cache key suffix. */
     keyResolver?: (...args: TArgs) => string;
+    /** Allow fallback key generation from resolver args when no `keyResolver` is provided. */
     allowImplicitContextCaching?: boolean;
 }
+/**
+ * Wraps a GraphQL resolver with read-through caching.
+ */
 declare function cacheGraphqlResolver<TArgs extends unknown[], TResult>(cache: CacheStack, prefix: string, resolver: (...args: TArgs) => Promise<TResult>, options?: GraphqlCacheOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
 
 interface OpenTelemetrySpan {
@@ -180,18 +249,27 @@ declare function createOpenTelemetryPlugin(cache: CacheStack, tracer: OpenTeleme
 };
 
 interface TrpcCacheMiddlewareContext<TInput = unknown, TResult = unknown> {
+    /** Procedure path, when supplied by the adapter. */
     path?: string;
+    /** Procedure type, such as query or mutation. */
     type?: string;
+    /** Raw procedure input used by the key resolver. */
     rawInput?: TInput;
+    /** Runs the next tRPC middleware or resolver. */
     next: () => Promise<{
         ok: boolean;
         data?: TResult;
     }>;
 }
 interface TrpcCacheMiddlewareOptions<TInput> extends CacheGetOptions {
+    /** Converts procedure input and metadata into a stable cache key suffix. */
     keyResolver?: (input: TInput, path?: string, type?: string) => string;
+    /** Allow fallback key generation from procedure path and raw input. */
     allowImplicitContextCaching?: boolean;
 }
+/**
+ * Creates a tRPC middleware that caches successful procedure results.
+ */
 declare function createTrpcCacheMiddleware<TInput = unknown, TResult = unknown>(cache: CacheStack, prefix: string, options?: TrpcCacheMiddlewareOptions<TInput>): (context: TrpcCacheMiddlewareContext<TInput, TResult>) => Promise<{
     ok: boolean;
     data?: TResult;
@@ -199,14 +277,23 @@ declare function createTrpcCacheMiddleware<TInput = unknown, TResult = unknown>(
 
 type CompressionAlgorithm = 'gzip' | 'brotli';
 interface RedisLayerOptions {
+    /** ioredis client used for all Redis commands. */
     client: Redis;
+    /** Default TTL in milliseconds for writes that do not provide an explicit TTL. */
     ttl?: number;
+    /** Layer name used for metrics and per-layer TTL maps. Defaults to `redis`. */
     name?: string;
+    /** Serializer or serializer chain used to encode values before storage. */
     serializer?: CacheSerializer | CacheSerializer[];
+    /** Prefix prepended to every Redis key. */
     prefix?: string;
+    /** Allow `clear()` without a key prefix. Disabled by default to avoid deleting unrelated Redis keys. */
     allowUnprefixedClear?: boolean;
+    /** Redis SCAN count hint used when discovering keys. Defaults to 100. */
     scanCount?: number;
+    /** Optional compression algorithm applied to large serialized payloads. */
     compression?: CompressionAlgorithm;
+    /** Minimum serialized payload size in bytes before compression is attempted. Defaults to 1 KiB. */
     compressionThreshold?: number;
     /**
      * Maximum number of bytes allowed after decompression.
@@ -218,8 +305,12 @@ interface RedisLayerOptions {
      * Slow commands reject so CacheStack can treat the layer as degraded.
      */
     commandTimeoutMs?: number;
+    /** Disconnect the Redis client when this layer is disposed. Disabled by default. */
     disconnectOnDispose?: boolean;
 }
+/**
+ * Redis-backed cache layer for shared cross-process cache state.
+ */
 declare class RedisLayer implements CacheLayer {
     readonly name: string;
     readonly defaultTtl?: number;
@@ -234,25 +325,70 @@ declare class RedisLayer implements CacheLayer {
     private readonly decompressionMaxBytes;
     private readonly commandTimeoutMs;
     private readonly disconnectOnDispose;
+    /**
+     * Creates a Redis cache layer using an existing ioredis client.
+     */
     constructor(options: RedisLayerOptions);
+    /**
+     * Reads and unwraps a fresh value from Redis.
+     */
     get<T>(key: string): Promise<T | null>;
+    /**
+     * Reads the raw stored value or envelope from Redis.
+     */
     getEntry<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Reads many raw entries from Redis using a pipeline.
+     */
     getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Writes many entries to Redis using a pipeline.
+     */
     setMany(entries: CacheLayerSetManyEntry[]): Promise<void>;
+    /**
+     * Stores a value in Redis using the provided TTL or layer default TTL.
+     */
     set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
+    /**
+     * Deletes a key from Redis.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Deletes multiple keys from Redis in batches.
+     */
     deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Returns true when the key exists in Redis.
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Returns remaining Redis TTL in milliseconds, or null when absent or non-expiring.
+     */
     ttl(key: string): Promise<number | null>;
+    /**
+     * Returns the number of keys under this layer's prefix.
+     */
     size(): Promise<number>;
+    /**
+     * Runs a Redis ping command.
+     */
     ping(): Promise<boolean>;
+    /**
+     * Disconnects the Redis client when `disconnectOnDispose` is enabled.
+     */
     dispose(): Promise<void>;
     /**
      * Deletes all keys matching the layer's prefix in batches to avoid
      * loading millions of keys into memory at once.
      */
     clear(): Promise<void>;
+    /**
+     * Returns keys under this layer's prefix without the prefix included.
+     */
     keys(): Promise<string[]>;
+    /**
+     * Visits keys under this layer's prefix without materializing all results.
+     */
     forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     private scanKeys;
     private withPrefix;
@@ -279,9 +415,13 @@ declare class RedisLayer implements CacheLayer {
 }
 
 interface DiskLayerOptions {
+    /** Directory where cache entry files are stored. */
     directory: string;
+    /** Default TTL in milliseconds for writes that do not provide an explicit TTL. */
     ttl?: number;
+    /** Layer name used for metrics and per-layer TTL maps. Defaults to `disk`. */
     name?: string;
+    /** Serializer used to encode values before writing them to disk. */
     serializer?: CacheSerializer;
     /**
      * Maximum number of cache files to store on disk. When exceeded, the oldest
@@ -331,25 +471,70 @@ declare class DiskLayer implements CacheLayer {
     private readonly maxEntryBytes;
     private readonly protection;
     private writeQueue;
+    /**
+     * Creates a disk-backed cache layer.
+     */
     constructor(options: DiskLayerOptions);
+    /**
+     * Reads and unwraps a fresh value from disk.
+     */
     get<T>(key: string): Promise<T | null>;
+    /**
+     * Reads the raw stored value or envelope from disk.
+     */
     getEntry<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Stores a value on disk using the provided TTL or layer default TTL.
+     */
     set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
+    /**
+     * Reads many raw entries from disk.
+     */
     getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Writes many entries to disk.
+     */
     setMany(entries: CacheLayerSetManyEntry[]): Promise<void>;
+    /**
+     * Returns true when the key exists and has not expired.
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Returns remaining TTL in milliseconds, or null when absent or non-expiring.
+     */
     ttl(key: string): Promise<number | null>;
+    /**
+     * Deletes a key from disk.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Deletes multiple keys from disk.
+     */
     deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Removes all cache entry files from this layer's directory.
+     */
     clear(): Promise<void>;
     /**
      * Returns the original cache key strings stored on disk.
      * Expired entries are skipped and cleaned up during the scan.
      */
     keys(): Promise<string[]>;
+    /**
+     * Visits all non-expired keys stored on disk.
+     */
     forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /**
+     * Returns the number of non-expired entries stored on disk.
+     */
     size(): Promise<number>;
+    /**
+     * Verifies the cache directory can be created.
+     */
     ping(): Promise<boolean>;
+    /**
+     * Reserved for interface compatibility; DiskLayer does not hold persistent handles.
+     */
     dispose(): Promise<void>;
     private keyToPath;
     private resolveDirectory;
@@ -377,19 +562,27 @@ declare class DiskLayer implements CacheLayer {
  *   npm install memcache-client
  */
 interface MemcachedClient {
+    /** Read a raw value for `key`, returning null on miss. */
     get(key: string): Promise<{
         value: Buffer | null;
     } | null>;
+    /** Store a raw value with optional expiration in seconds. */
     set(key: string, value: string | Buffer, options?: {
         expires?: number;
     }): Promise<boolean | undefined>;
+    /** Delete a raw key. */
     delete(key: string): Promise<boolean | undefined>;
 }
 interface MemcachedLayerOptions {
+    /** Memcached-compatible client implementation. */
     client: MemcachedClient;
+    /** Default TTL in milliseconds for writes that do not provide an explicit TTL. */
     ttl?: number;
+    /** Layer name used for metrics and per-layer TTL maps. Defaults to `memcached`. */
     name?: string;
+    /** Prefix prepended to every Memcached key. */
     keyPrefix?: string;
+    /** Serializer used to encode values before storing them in Memcached. */
     serializer?: CacheSerializer;
 }
 /**
@@ -417,32 +610,74 @@ declare class MemcachedLayer implements CacheLayer {
     private readonly client;
     private readonly keyPrefix;
     private readonly serializer;
+    /**
+     * Creates a Memcached cache layer using a compatible client.
+     */
     constructor(options: MemcachedLayerOptions);
+    /**
+     * Reads and unwraps a fresh value from Memcached.
+     */
     get<T>(key: string): Promise<T | null>;
+    /**
+     * Reads the raw stored value or envelope from Memcached.
+     */
     getEntry<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Reads many raw entries from Memcached.
+     */
     getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Stores a value in Memcached using the provided TTL or layer default TTL.
+     */
     set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
+    /**
+     * Returns true when the key exists in Memcached.
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Deletes a key from Memcached.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Deletes multiple keys from Memcached.
+     */
     deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Always throws because Memcached has no safe prefix clear primitive.
+     */
     clear(): Promise<void>;
     private withPrefix;
     private validateKey;
 }
 
 declare class JsonSerializer implements CacheSerializer {
+    /**
+     * Serializes a value to JSON.
+     */
     serialize(value: unknown): string;
+    /**
+     * Parses JSON and sanitizes the result before returning it.
+     */
     deserialize<T>(payload: string | Buffer): T;
 }
 
 declare class MsgpackSerializer implements CacheSerializer {
+    /**
+     * Serializes a value to MessagePack bytes.
+     */
     serialize(value: unknown): Buffer;
+    /**
+     * Decodes MessagePack bytes and sanitizes the result before returning it.
+     */
     deserialize<T>(payload: string | Buffer): T;
 }
 
 interface RedisSingleFlightCoordinatorOptions {
+    /** Redis client used for lock acquisition, renewal, and release. */
     client: Redis;
+    /** Redis key prefix for single-flight locks. Defaults to `layercache:singleflight`. */
     prefix?: string;
+    /** Per-command timeout in milliseconds for Redis operations. */
     commandTimeoutMs?: number;
 }
 declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinator {
@@ -450,6 +685,10 @@ declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinat
     private readonly prefix;
     private readonly commandTimeoutMs;
     constructor(options: RedisSingleFlightCoordinatorOptions);
+    /**
+     * Executes `worker` when this process acquires the Redis lock; otherwise runs
+     * `waiter` while another process owns the work.
+     */
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
     private startLeaseRenewal;
     private normalizeCommandTimeoutMs;
@@ -475,6 +714,9 @@ declare class StampedeGuard {
     private readonly maxInFlight;
     private readonly entryTimeoutMs;
     constructor(options?: StampedeGuardOptions);
+    /**
+     * Deduplicates concurrent work for the same key in this process.
+     */
     execute<T>(key: string, task: () => Promise<T>): Promise<T>;
     private withTimeout;
     private releaseEntry;