layercache 1.1.0 → 1.2.1

package/dist/index.d.ts

@@ -1,438 +1,32 @@
-import { EventEmitter } from 'node:events';
+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-C1sBhTfv.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-C1sBhTfv.js';
 import Redis from 'ioredis';
-
-interface LayerTtlMap {
-    [layerName: string]: number | undefined;
-}
-interface CacheWriteOptions {
-    tags?: string[];
-    ttl?: number | LayerTtlMap;
-    negativeCache?: boolean;
-    negativeTtl?: number | LayerTtlMap;
-    staleWhileRevalidate?: number | LayerTtlMap;
-    staleIfError?: number | LayerTtlMap;
-    ttlJitter?: number | LayerTtlMap;
-    slidingTtl?: boolean;
-    refreshAhead?: number | LayerTtlMap;
-    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
-    circuitBreaker?: CacheCircuitBreakerOptions;
-}
-interface CacheGetOptions extends CacheWriteOptions {
-}
-interface CacheMGetEntry<T> {
-    key: string;
-    fetch?: () => Promise<T>;
-    options?: CacheGetOptions;
-}
-interface CacheMSetEntry<T> {
-    key: string;
-    value: T;
-    options?: CacheWriteOptions;
-}
-/** Interface that all cache backend implementations must satisfy. */
-interface CacheLayer {
-    readonly name: string;
-    readonly defaultTtl?: number;
-    readonly isLocal?: boolean;
-    get<T>(key: string): Promise<T | null>;
-    getEntry?<T = unknown>(key: string): Promise<T | null>;
-    getMany?<T>(keys: string[]): Promise<Array<T | null>>;
-    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[]>;
-    /**
-     * Returns true if the key exists and has not expired.
-     * Implementations may omit this; CacheStack will fall back to `get()`.
-     */
-    has?(key: string): Promise<boolean>;
-    /**
-     * Returns the remaining TTL in seconds for the key, or null if the key
-     * does not exist, has no TTL, or has already expired.
-     * Implementations may omit this.
-     */
-    ttl?(key: string): Promise<number | null>;
-    /**
-     * Returns the number of entries currently held by this layer.
-     * Implementations may omit this.
-     */
-    size?(): Promise<number>;
-}
-interface CacheSerializer {
-    serialize(value: unknown): string | Buffer;
-    deserialize<T>(payload: string | Buffer): T;
-}
-/** Snapshot of cumulative cache counters. */
-interface CacheMetricsSnapshot {
-    hits: number;
-    misses: number;
-    fetches: number;
-    sets: number;
-    deletes: number;
-    backfills: number;
-    invalidations: number;
-    staleHits: number;
-    refreshes: number;
-    refreshErrors: number;
-    writeFailures: number;
-    singleFlightWaits: number;
-    negativeCacheHits: number;
-    circuitBreakerTrips: number;
-    degradedOperations: number;
-    hitsByLayer: Record<string, number>;
-    missesByLayer: Record<string, number>;
-    /** Timestamp (ms since epoch) when metrics were last reset. */
-    resetAt: number;
-}
-/** Computed hit-rate statistics derived from CacheMetricsSnapshot. */
-interface CacheHitRateSnapshot {
-    /** Overall hit rate across all layers (0–1). */
-    overall: number;
-    /** Per-layer hit rates (0–1 each). */
-    byLayer: Record<string, number>;
-}
-interface CacheLogger {
-    debug?(message: string, context?: Record<string, unknown>): void;
-    info?(message: string, context?: Record<string, unknown>): void;
-    warn?(message: string, context?: Record<string, unknown>): void;
-    error?(message: string, context?: Record<string, unknown>): void;
-}
-interface CacheTagIndex {
-    touch(key: string): Promise<void>;
-    track(key: string, tags: string[]): Promise<void>;
-    remove(key: string): Promise<void>;
-    keysForTag(tag: string): Promise<string[]>;
-    matchPattern(pattern: string): Promise<string[]>;
-    clear(): Promise<void>;
-}
-interface InvalidationMessage {
-    scope: 'key' | 'keys' | 'clear';
-    sourceId: string;
-    keys?: string[];
-    operation?: 'write' | 'delete' | 'invalidate' | 'clear';
-}
-interface InvalidationBus {
-    subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void> | void>;
-    publish(message: InvalidationMessage): Promise<void>;
-}
-interface CacheSingleFlightExecutionOptions {
-    leaseMs: number;
-    waitTimeoutMs: number;
-    pollIntervalMs: number;
-}
-interface CacheSingleFlightCoordinator {
-    execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
-}
-interface CacheStackOptions {
-    logger?: CacheLogger | boolean;
-    metrics?: boolean;
-    stampedePrevention?: boolean;
-    invalidationBus?: InvalidationBus;
-    tagIndex?: CacheTagIndex;
-    broadcastL1Invalidation?: boolean;
-    /**
-     * @deprecated Use `broadcastL1Invalidation` instead.
-     */
-    publishSetInvalidation?: boolean;
-    negativeCaching?: boolean;
-    negativeTtl?: number | LayerTtlMap;
-    staleWhileRevalidate?: number | LayerTtlMap;
-    staleIfError?: number | LayerTtlMap;
-    ttlJitter?: number | LayerTtlMap;
-    refreshAhead?: number | LayerTtlMap;
-    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
-    circuitBreaker?: CacheCircuitBreakerOptions;
-    gracefulDegradation?: boolean | CacheDegradationOptions;
-    writePolicy?: 'strict' | 'best-effort';
-    singleFlightCoordinator?: CacheSingleFlightCoordinator;
-    singleFlightLeaseMs?: number;
-    singleFlightTimeoutMs?: number;
-    singleFlightPollMs?: number;
-    /**
-     * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
-     * before the oldest entries are pruned. Prevents unbounded memory growth.
-     * Defaults to 100 000.
-     */
-    maxProfileEntries?: number;
-}
-interface CacheAdaptiveTtlOptions {
-    hotAfter?: number;
-    step?: number | LayerTtlMap;
-    maxTtl?: number | LayerTtlMap;
-}
-interface CacheCircuitBreakerOptions {
-    failureThreshold?: number;
-    cooldownMs?: number;
-}
-interface CacheDegradationOptions {
-    retryAfterMs?: number;
-}
-interface CacheWarmEntry<T = unknown> {
-    key: string;
-    fetcher: () => Promise<T>;
-    options?: CacheGetOptions;
-    priority?: number;
-}
-/** Options controlling the cache warm-up process. */
-interface CacheWarmOptions {
-    concurrency?: number;
-    continueOnError?: boolean;
-    /** Called after each entry is processed (success or failure). */
-    onProgress?: (progress: CacheWarmProgress) => void;
-}
-/** Progress information delivered to `CacheWarmOptions.onProgress`. */
-interface CacheWarmProgress {
-    completed: number;
-    total: number;
-    key: string;
-    success: boolean;
-}
-interface CacheWrapOptions<TArgs extends unknown[] = unknown[]> extends CacheGetOptions {
-    keyResolver?: (...args: TArgs) => string;
-}
-interface CacheSnapshotEntry {
-    key: string;
-    value: unknown;
-    ttl?: number;
-}
-interface CacheStatsSnapshot {
-    metrics: CacheMetricsSnapshot;
-    layers: Array<{
-        name: string;
-        isLocal: boolean;
-        degradedUntil: number | null;
-    }>;
-    backgroundRefreshes: number;
-}
-/** All events emitted by CacheStack and their payload shapes. */
-interface CacheStackEvents {
-    /** Fired on every cache hit. */
-    hit: {
-        key: string;
-        layer: string;
-        state: 'fresh' | 'stale-while-revalidate' | 'stale-if-error';
-    };
-    /** Fired on every cache miss before the fetcher runs. */
-    miss: {
-        key: string;
-        mode: string;
-    };
-    /** Fired after a value is stored in the cache. */
-    set: {
-        key: string;
-        kind: string;
-        tags?: string[];
-    };
-    /** Fired after one or more keys are deleted. */
-    delete: {
-        keys: string[];
-    };
-    /** Fired when a value is backfilled into a faster layer. */
-    backfill: {
-        key: string;
-        layer: string;
-    };
-    /** Fired when a stale value is returned to the caller. */
-    'stale-serve': {
-        key: string;
-        state: string;
-        layer: string;
-    };
-    /** Fired when a duplicate request is deduplicated in stampede prevention. */
-    'stampede-dedupe': {
-        key: string;
-    };
-    /** Fired after a key is successfully warmed. */
-    warm: {
-        key: string;
-    };
-    /** Fired when an error occurs (layer failure, circuit breaker, etc.). */
-    error: {
-        operation: string;
-        [key: string]: unknown;
-    };
-}
-
-declare class CacheNamespace {
-    private readonly cache;
-    private readonly prefix;
-    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>;
-    has(key: string): Promise<boolean>;
-    ttl(key: string): Promise<number | null>;
-    set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
-    delete(key: string): Promise<void>;
-    mdelete(keys: string[]): Promise<void>;
-    clear(): Promise<void>;
-    mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
-    mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
-    invalidateByTag(tag: string): Promise<void>;
-    invalidateByPattern(pattern: string): Promise<void>;
-    wrap<TArgs extends unknown[], TResult>(keyPrefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
-    warm(entries: CacheWarmEntry[], options?: CacheWarmOptions): Promise<void>;
-    getMetrics(): CacheMetricsSnapshot;
-    getHitRate(): CacheHitRateSnapshot;
-    qualify(key: string): string;
-}
-
-/** Typed overloads for EventEmitter so callers get autocomplete on event names. */
-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;
-    emit<K extends keyof CacheStackEvents>(event: K, data: CacheStackEvents[K]): boolean;
-}
-declare class CacheStack extends EventEmitter {
-    private readonly layers;
-    private readonly options;
-    private readonly stampedeGuard;
-    private readonly metricsCollector;
-    private readonly instanceId;
-    private readonly startup;
-    private unsubscribeInvalidation?;
-    private readonly logger;
-    private readonly tagIndex;
-    private readonly backgroundRefreshes;
-    private readonly layerDegradedUntil;
-    private readonly ttlResolver;
-    private readonly circuitBreakerManager;
-    private isDisconnecting;
-    private disconnectPromise?;
-    constructor(layers: CacheLayer[], options?: CacheStackOptions);
-    /**
-     * Read-through cache get.
-     * Returns the cached value if present and fresh, or invokes `fetcher` on a miss
-     * and stores the result across all layers. Returns `null` if the key is not found
-     * and no `fetcher` is provided.
-     */
-    get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
-    /**
-     * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
-     * Fetches and caches the value if not already present.
-     */
-    getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
-    /**
-     * Returns true if the given key exists and is not expired in any layer.
-     */
-    has(key: string): Promise<boolean>;
-    /**
-     * Returns the remaining TTL in seconds for the key in the fastest layer
-     * that has it, or null if the key is not found / has no TTL.
-     */
-    ttl(key: string): Promise<number | null>;
-    /**
-     * Stores a value in all cache layers. Overwrites any existing value.
-     */
-    set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
-    /**
-     * Deletes the key from all layers and publishes an invalidation message.
-     */
-    delete(key: string): Promise<void>;
-    clear(): Promise<void>;
-    /**
-     * Deletes multiple keys at once. More efficient than calling `delete()` in a loop.
-     */
-    mdelete(keys: string[]): Promise<void>;
-    mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
-    mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
-    warm(entries: CacheWarmEntry[], options?: CacheWarmOptions): Promise<void>;
-    /**
-     * Returns a cached version of `fetcher`. The cache key is derived from
-     * `prefix` plus the serialized arguments unless a `keyResolver` is provided.
-     */
-    wrap<TArgs extends unknown[], TResult>(prefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
-    /**
-     * Creates a `CacheNamespace` that automatically prefixes all keys with
-     * `prefix:`. Useful for multi-tenant or module-level isolation.
-     */
-    namespace(prefix: string): CacheNamespace;
-    invalidateByTag(tag: string): Promise<void>;
-    invalidateByPattern(pattern: string): Promise<void>;
-    getMetrics(): CacheMetricsSnapshot;
-    getStats(): CacheStatsSnapshot;
-    resetMetrics(): void;
-    /**
-     * Returns computed hit-rate statistics (overall and per-layer).
-     */
-    getHitRate(): CacheHitRateSnapshot;
-    exportState(): Promise<CacheSnapshotEntry[]>;
-    importState(entries: CacheSnapshotEntry[]): Promise<void>;
-    persistToFile(filePath: string): Promise<void>;
-    restoreFromFile(filePath: string): Promise<void>;
-    disconnect(): Promise<void>;
-    private initialize;
-    private fetchWithGuards;
-    private waitForFreshValue;
-    private fetchAndPopulate;
-    private storeEntry;
-    private readFromLayers;
-    private readLayerEntry;
-    private backfill;
-    private writeAcrossLayers;
-    private executeLayerOperations;
-    private resolveFreshTtl;
-    private resolveLayerSeconds;
-    private shouldNegativeCache;
-    private scheduleBackgroundRefresh;
-    private resolveSingleFlightOptions;
-    private deleteKeys;
-    private publishInvalidation;
-    private handleInvalidationMessage;
-    private formatError;
-    private sleep;
-    private shouldBroadcastL1Invalidation;
-    private deleteKeysFromLayers;
-    private validateConfiguration;
-    private validateWriteOptions;
-    private validateLayerNumberOption;
-    private validatePositiveNumber;
-    private validateNonNegativeNumber;
-    private validateCacheKey;
-    private serializeOptions;
-    private validateAdaptiveTtlOptions;
-    private validateCircuitBreakerOptions;
-    private applyFreshReadPolicies;
-    private shouldSkipLayer;
-    private handleLayerFailure;
-    private isGracefulDegradationEnabled;
-    private recordCircuitFailure;
-    private isNegativeStoredValue;
-    private emitError;
-    private serializeKeyPart;
-    private isCacheSnapshotEntries;
-    private normalizeForSerialization;
-}
-
-declare class PatternMatcher {
-    /**
-     * Tests whether a glob-style pattern matches a value.
-     * Supports `*` (any sequence of characters) and `?` (any single character).
-     * Uses a linear-time algorithm to avoid ReDoS vulnerabilities.
-     */
-    static matches(pattern: string, value: string): boolean;
-    /**
-     * Linear-time glob matching using dynamic programming.
-     * Avoids catastrophic backtracking that RegExp-based glob matching can cause.
-     */
-    private static matchLinear;
-}
+import 'node:events';
 
 interface RedisInvalidationBusOptions {
     publisher: Redis;
     subscriber?: Redis;
     channel?: string;
+    logger?: CacheLogger;
 }
+/**
+ * Redis pub/sub invalidation bus.
+ *
+ * Supports multiple concurrent subscriptions — each `CacheStack` instance
+ * can independently call `subscribe()` and receive its own unsubscribe handle.
+ * The underlying Redis SUBSCRIBE is only issued once and shared across all handlers.
+ */
 declare class RedisInvalidationBus implements InvalidationBus {
     private readonly channel;
     private readonly publisher;
     private readonly subscriber;
-    private activeListener?;
+    private readonly logger?;
+    private readonly handlers;
+    private sharedListener?;
     constructor(options: RedisInvalidationBusOptions);
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void>>;
     publish(message: InvalidationMessage): Promise<void>;
-    private handleMessage;
+    private dispatchToHandlers;
     private isInvalidationMessage;
     private reportError;
 }
@@ -451,6 +45,8 @@ declare class RedisTagIndex implements CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    keysForPrefix(prefix: string): Promise<string[]>;
+    tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
     private scanIndexKeys;
@@ -459,18 +55,6 @@ declare class RedisTagIndex implements CacheTagIndex {
     private tagKeysKey;
 }
 
-declare class TagIndex implements CacheTagIndex {
-    private readonly tagToKeys;
-    private readonly keyToTags;
-    private readonly knownKeys;
-    touch(key: string): Promise<void>;
-    track(key: string, tags: string[]): Promise<void>;
-    remove(key: string): Promise<void>;
-    keysForTag(tag: string): Promise<string[]>;
-    matchPattern(pattern: string): Promise<string[]>;
-    clear(): Promise<void>;
-}
-
 declare function createCacheStatsHandler(cache: CacheStack): (_request: unknown, response: {
     setHeader?: (name: string, value: string) => void;
     end: (body: string) => void;
@@ -493,11 +77,74 @@ interface FastifyLayercachePluginOptions {
 }
 declare function createFastifyLayercachePlugin(cache: CacheStack, options?: FastifyLayercachePluginOptions): (fastify: FastifyLike) => Promise<void>;
 
+interface ExpressLikeRequest {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    path?: string;
+    query?: Record<string, unknown>;
+}
+interface ExpressLikeResponse {
+    statusCode?: number;
+    setHeader?: (name: string, value: string) => void;
+    json?: (body: unknown) => void;
+    end?: (body?: string) => void;
+}
+type NextFunction = (error?: unknown) => void;
+interface ExpressCacheMiddlewareOptions extends CacheGetOptions {
+    /**
+     * Resolves a cache key from the incoming request. Defaults to
+     * `GET:<req.originalUrl || req.url>`.
+     */
+    keyResolver?: (req: ExpressLikeRequest) => string;
+    /**
+     * Only cache responses for these HTTP methods. Defaults to `['GET']`.
+     */
+    methods?: string[];
+}
+/**
+ * Express/Connect-compatible middleware that caches JSON responses.
+ *
+ * ```ts
+ * import express from 'express'
+ * import { CacheStack, MemoryLayer, createExpressCacheMiddleware } from 'layercache'
+ *
+ * const cache = new CacheStack([new MemoryLayer({ ttl: 60 })])
+ * const app = express()
+ *
+ * app.get('/api/data', createExpressCacheMiddleware(cache, { ttl: 30 }), (req, res) => {
+ *   res.json({ fresh: true })
+ * })
+ * ```
+ */
+declare function createExpressCacheMiddleware(cache: CacheStack, options?: ExpressCacheMiddlewareOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: NextFunction) => Promise<void>;
+
 interface GraphqlCacheOptions<TArgs extends unknown[]> extends CacheGetOptions {
     keyResolver?: (...args: TArgs) => string;
 }
 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 {
+    setAttribute?: (name: string, value: unknown) => void;
+    recordException?: (error: unknown) => void;
+    end: () => void;
+}
+interface OpenTelemetryTracer {
+    startSpan: (name: string, options?: {
+        attributes?: Record<string, unknown>;
+    }) => OpenTelemetrySpan;
+}
+/**
+ * Lightweight OpenTelemetry instrumentation for a CacheStack instance.
+ *
+ * Note: this implementation wraps instance methods directly. Avoid stacking
+ * multiple OpenTelemetry plugins on the same CacheStack at the same time,
+ * because each plugin replaces and later restores those methods.
+ */
+declare function createOpenTelemetryPlugin(cache: CacheStack, tracer: OpenTelemetryTracer): {
+    uninstall(): void;
+};
+
 interface TrpcCacheMiddlewareContext<TInput = unknown, TResult = unknown> {
     path?: string;
     type?: string;
@@ -515,83 +162,44 @@ declare function createTrpcCacheMiddleware<TInput = unknown, TResult = unknown>(
     data?: TResult;
 } | null>;
 
-interface MemoryLayerSnapshotEntry {
-    key: string;
-    value: unknown;
-    expiresAt: number | null;
-}
-/**
- * Eviction policy applied when `maxSize` is reached.
- * - `lru` (default): evicts the Least Recently Used entry.
- * - `lfu`: evicts the Least Frequently Used entry.
- * - `fifo`: evicts the oldest inserted entry.
- */
-type EvictionPolicy = 'lru' | 'lfu' | 'fifo';
-interface MemoryLayerOptions {
-    ttl?: number;
-    maxSize?: number;
-    name?: string;
-    evictionPolicy?: EvictionPolicy;
-}
-declare class MemoryLayer implements CacheLayer {
-    readonly name: string;
-    readonly defaultTtl?: number;
-    readonly isLocal = true;
-    private readonly maxSize;
-    private readonly evictionPolicy;
-    private readonly entries;
-    constructor(options?: MemoryLayerOptions);
-    get<T>(key: string): Promise<T | null>;
-    getEntry<T = unknown>(key: string): Promise<T | null>;
-    getMany<T>(keys: string[]): Promise<Array<T | null>>;
-    set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
-    has(key: string): Promise<boolean>;
-    ttl(key: string): Promise<number | null>;
-    size(): Promise<number>;
-    delete(key: string): Promise<void>;
-    deleteMany(keys: string[]): Promise<void>;
-    clear(): Promise<void>;
-    keys(): Promise<string[]>;
-    exportState(): MemoryLayerSnapshotEntry[];
-    importState(entries: MemoryLayerSnapshotEntry[]): void;
-    private evict;
-    private pruneExpired;
-    private isExpired;
-}
-
 type CompressionAlgorithm = 'gzip' | 'brotli';
 interface RedisLayerOptions {
     client: Redis;
     ttl?: number;
     name?: string;
-    serializer?: CacheSerializer;
+    serializer?: CacheSerializer | CacheSerializer[];
     prefix?: string;
     allowUnprefixedClear?: boolean;
     scanCount?: number;
     compression?: CompressionAlgorithm;
     compressionThreshold?: number;
+    disconnectOnDispose?: boolean;
 }
 declare class RedisLayer implements CacheLayer {
     readonly name: string;
     readonly defaultTtl?: number;
     readonly isLocal = false;
     private readonly client;
-    private readonly serializer;
+    private readonly serializers;
     private readonly prefix;
     private readonly allowUnprefixedClear;
     private readonly scanCount;
     private readonly compression?;
     private readonly compressionThreshold;
+    private readonly disconnectOnDispose;
     constructor(options: RedisLayerOptions);
     get<T>(key: string): Promise<T | null>;
     getEntry<T = unknown>(key: string): Promise<T | null>;
     getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany(entries: CacheLayerSetManyEntry[]): Promise<void>;
     set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
     delete(key: string): Promise<void>;
     deleteMany(keys: string[]): Promise<void>;
     has(key: string): Promise<boolean>;
     ttl(key: string): Promise<number | null>;
     size(): Promise<number>;
+    ping(): Promise<boolean>;
+    dispose(): Promise<void>;
     /**
      * Deletes all keys matching the layer's prefix in batches to avoid
      * loading millions of keys into memory at once.
@@ -601,8 +209,17 @@ declare class RedisLayer implements CacheLayer {
     private scanKeys;
     private withPrefix;
     private deserializeOrDelete;
+    private rewriteWithPrimarySerializer;
+    private primarySerializer;
     private isSerializablePayload;
+    /**
+     * Compresses the payload asynchronously if compression is enabled and the
+     * payload exceeds the threshold. This avoids blocking the event loop.
+     */
     private encodePayload;
+    /**
+     * Decompresses the payload asynchronously if a compression header is present.
+     */
     private decodePayload;
 }
 
@@ -611,12 +228,21 @@ interface DiskLayerOptions {
     ttl?: number;
     name?: string;
     serializer?: CacheSerializer;
+    /**
+     * 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.
+     */
+    maxFiles?: number;
 }
 /**
  * A file-system backed cache layer.
  * Each key is stored as a separate JSON file in `directory`.
  * Useful for persisting cache across process restarts without needing Redis.
  *
+ * - `keys()` returns the original cache key strings (not hashes).
+ * - `maxFiles` limits on-disk entries; when exceeded, oldest files are evicted.
+ *
  * NOTE: DiskLayer is designed for low-to-medium traffic scenarios.
  * For high-throughput workloads, use MemoryLayer + RedisLayer.
  */
@@ -626,19 +252,34 @@ declare class DiskLayer implements CacheLayer {
     readonly isLocal = true;
     private readonly directory;
     private readonly serializer;
+    private readonly maxFiles;
+    private writeQueue;
     constructor(options: DiskLayerOptions);
     get<T>(key: string): Promise<T | null>;
     getEntry<T = unknown>(key: string): Promise<T | null>;
     set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
+    getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany(entries: CacheLayerSetManyEntry[]): Promise<void>;
     has(key: string): Promise<boolean>;
     ttl(key: string): Promise<number | null>;
     delete(key: string): Promise<void>;
     deleteMany(keys: string[]): Promise<void>;
     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[]>;
     size(): Promise<number>;
+    ping(): Promise<boolean>;
+    dispose(): Promise<void>;
     private keyToPath;
     private safeDelete;
+    private enqueueWrite;
+    /**
+     * Removes the oldest files (by mtime) when the directory exceeds maxFiles.
+     */
+    private enforceMaxFiles;
 }
 
 /**
@@ -663,10 +304,14 @@ interface MemcachedLayerOptions {
     ttl?: number;
     name?: string;
     keyPrefix?: string;
+    serializer?: CacheSerializer;
 }
 /**
  * Memcached-backed cache layer.
  *
+ * Now supports pluggable serializers (default: JSON), StoredValueEnvelope
+ * for stale-while-revalidate / stale-if-error semantics, and bulk reads.
+ *
  * Example usage with `memjs`:
  * ```ts
  * import Memjs from 'memjs'
@@ -685,9 +330,13 @@ declare class MemcachedLayer implements CacheLayer {
     readonly isLocal = false;
     private readonly client;
     private readonly keyPrefix;
+    private readonly serializer;
     constructor(options: MemcachedLayerOptions);
     get<T>(key: string): Promise<T | null>;
+    getEntry<T = unknown>(key: string): Promise<T | null>;
+    getMany<T>(keys: string[]): Promise<Array<T | null>>;
     set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
+    has(key: string): Promise<boolean>;
     delete(key: string): Promise<void>;
     deleteMany(keys: string[]): Promise<void>;
     clear(): Promise<void>;
@@ -725,6 +374,9 @@ declare class StampedeGuard {
  * Returns a function that generates a Prometheus-compatible text exposition
  * of the cache metrics from one or more CacheStack instances.
  *
+ * Now includes per-layer latency gauges (`layercache_layer_latency_avg_ms`,
+ * `layercache_layer_latency_max_ms`, `layercache_layer_latency_count`).
+ *
  * Usage example:
  * ```ts
  * const collect = createPrometheusMetricsExporter(cache)
@@ -742,4 +394,4 @@ declare function createPrometheusMetricsExporter(stacks: CacheStack | Array<{
     name: string;
 }>): () => string;
 
-export { type CacheAdaptiveTtlOptions, type CacheCircuitBreakerOptions, type CacheDegradationOptions, type CacheGetOptions, type CacheHitRateSnapshot, type CacheLayer, type CacheLogger, type CacheMGetEntry, type CacheMSetEntry, type CacheMetricsSnapshot, CacheNamespace, type CacheSerializer, type CacheSingleFlightCoordinator, type CacheSingleFlightExecutionOptions, type CacheSnapshotEntry, CacheStack, type CacheStackEvents, type CacheStackOptions, type CacheStatsSnapshot, type CacheTagIndex, type CacheWarmEntry, type CacheWarmOptions, type CacheWarmProgress, type CacheWrapOptions, type CacheWriteOptions, DiskLayer, type EvictionPolicy, type InvalidationBus, type InvalidationMessage, JsonSerializer, type LayerTtlMap, type MemcachedClient, MemcachedLayer, MemoryLayer, type MemoryLayerSnapshotEntry, MsgpackSerializer, PatternMatcher, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, TagIndex, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createFastifyLayercachePlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };
+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 };