layercache 1.2.0 → 1.2.1

package/dist/edge-C1sBhTfv.d.ts

@@ -0,0 +1,667 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Thrown by `CacheStack.getOrThrow()` when no value is found for the given key
+ * (fetcher returned null or no fetcher was provided and the key is absent).
+ */
+declare class CacheMissError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+interface LayerTtlMap {
+    [layerName: string]: number | undefined;
+}
+interface CacheWriteOptions {
+    tags?: string[];
+    ttl?: number | LayerTtlMap;
+    ttlPolicy?: CacheTtlPolicy;
+    negativeCache?: boolean;
+    negativeTtl?: number | LayerTtlMap;
+    staleWhileRevalidate?: number | LayerTtlMap;
+    staleIfError?: number | LayerTtlMap;
+    ttlJitter?: number | LayerTtlMap;
+    slidingTtl?: boolean;
+    refreshAhead?: number | LayerTtlMap;
+    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
+    circuitBreaker?: CacheCircuitBreakerOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
+    /**
+     * Optional predicate called with the fetcher's return value before caching.
+     * Return `false` to skip storing the value in the cache (but still return it
+     * to the caller). Useful for not caching failed API responses or empty results.
+     *
+     * @example
+     * cache.get('key', fetchData, { shouldCache: (v) => v.status === 200 })
+     */
+    shouldCache?: (value: unknown) => boolean;
+}
+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>;
+    /**
+     * Bulk read fast-path. Implementations should return raw stored entries using
+     * the same semantics as `getEntry()` so CacheStack can resolve envelopes,
+     * stale windows, and negative-cache markers consistently.
+     */
+    getMany?<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany?(entries: CacheLayerSetManyEntry[]): Promise<void>;
+    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[]>;
+    ping?(): Promise<boolean>;
+    dispose?(): Promise<void>;
+    /**
+     * 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;
+}
+/** Per-layer latency statistics (rolling window of sampled read durations). */
+interface CacheLayerLatency {
+    /** Average read latency in milliseconds. */
+    avgMs: number;
+    /** Maximum observed read latency in milliseconds. */
+    maxMs: number;
+    /** Number of samples used to compute the statistics. */
+    count: number;
+}
+/** 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>;
+    /** Per-layer read latency statistics (sampled from successful reads). */
+    latencyByLayer: Record<string, CacheLayerLatency>;
+    /** 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[]>;
+    keysForPrefix?(prefix: string): Promise<string[]>;
+    /** Returns the tags associated with a specific key, or an empty array. */
+    tagsForKey?(key: string): Promise<string[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+interface CacheLayerSetManyEntry {
+    key: string;
+    value: unknown;
+    ttl?: number;
+}
+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;
+    generation?: number;
+    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';
+    writeStrategy?: 'write-through' | 'write-behind';
+    writeBehind?: CacheWriteBehindOptions;
+    fetcherRateLimit?: CacheRateLimitOptions;
+    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;
+}
+type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
+    alignTo: number;
+} | ((context: CacheTtlPolicyContext) => number | undefined);
+interface CacheTtlPolicyContext {
+    key: string;
+    value: unknown;
+}
+interface CacheCircuitBreakerOptions {
+    failureThreshold?: number;
+    cooldownMs?: number;
+}
+interface CacheDegradationOptions {
+    retryAfterMs?: number;
+}
+interface CacheRateLimitOptions {
+    maxConcurrent?: number;
+    intervalMs?: number;
+    maxPerInterval?: number;
+}
+interface CacheWriteBehindOptions {
+    flushIntervalMs?: number;
+    batchSize?: number;
+    maxQueueSize?: 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;
+}
+interface CacheHealthCheckResult {
+    layer: string;
+    healthy: boolean;
+    latencyMs: number;
+    error?: string;
+}
+/** Detailed inspection result for a single cache key. */
+interface CacheInspectResult {
+    key: string;
+    /** Layers in which the key is currently stored (not expired). */
+    foundInLayers: string[];
+    /** Remaining fresh TTL in seconds, or null if no expiry or not an envelope. */
+    freshTtlSeconds: number | null;
+    /** Remaining stale-while-revalidate window in seconds, or null. */
+    staleTtlSeconds: number | null;
+    /** Remaining stale-if-error window in seconds, or null. */
+    errorTtlSeconds: number | null;
+    /** Whether the key is currently serving stale-while-revalidate. */
+    isStale: boolean;
+    /** Tags associated with this key (from the TagIndex). */
+    tags: string[];
+}
+/** 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;
+    };
+}
+
+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;
+    cleanupIntervalMs?: number;
+    onEvict?: (key: string, value: unknown) => void;
+}
+declare class MemoryLayer implements CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal = true;
+    private readonly maxSize;
+    private readonly evictionPolicy;
+    private readonly onEvict?;
+    private readonly entries;
+    private cleanupTimer?;
+    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>>;
+    setMany(entries: CacheLayerSetManyEntry[]): Promise<void>;
+    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>;
+    ping(): Promise<boolean>;
+    dispose(): Promise<void>;
+    keys(): Promise<string[]>;
+    exportState(): MemoryLayerSnapshotEntry[];
+    importState(entries: MemoryLayerSnapshotEntry[]): void;
+    private evict;
+    private pruneExpired;
+    private isExpired;
+}
+
+declare class PatternMatcher {
+    /**
+     * Tests whether a glob-style pattern matches a value.
+     * Supports `*` (any sequence of characters) and `?` (any single character).
+     * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
+     * quadratic memory usage on long patterns/keys.
+     */
+    static matches(pattern: string, value: string): boolean;
+    /**
+     * Linear-time glob matching with O(1) extra memory.
+     */
+    private static matchLinear;
+}
+
+interface TagIndexOptions {
+    /**
+     * Maximum number of keys tracked in `knownKeys`. When exceeded, the oldest
+     * 10 % of keys are pruned to keep memory bounded.
+     * Defaults to unlimited.
+     */
+    maxKnownKeys?: number;
+}
+declare class TagIndex implements CacheTagIndex {
+    private readonly tagToKeys;
+    private readonly keyToTags;
+    private readonly knownKeys;
+    private readonly maxKnownKeys;
+    constructor(options?: TagIndexOptions);
+    touch(key: string): Promise<void>;
+    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 pruneKnownKeysIfNeeded;
+    private removeKey;
+}
+
+declare class CacheNamespace {
+    private readonly cache;
+    private readonly prefix;
+    private static readonly metricsMutexes;
+    private metrics;
+    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>;
+    /**
+     * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+     */
+    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
+    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>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
+    /**
+     * Returns detailed metadata about a single cache key within this namespace.
+     */
+    inspect(key: string): Promise<CacheInspectResult | null>;
+    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;
+    /**
+     * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
+     *
+     * ```ts
+     * const tenant = cache.namespace('tenant:abc')
+     * const posts = tenant.namespace('posts')
+     * // keys become: "tenant:abc:posts:mykey"
+     * ```
+     */
+    namespace(childPrefix: string): CacheNamespace;
+    qualify(key: string): string;
+    private trackMetrics;
+    private getMetricsMutex;
+}
+
+/** 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;
+    removeAllListeners<K extends keyof CacheStackEvents>(event?: K): this;
+    listeners<K extends keyof CacheStackEvents>(event: K): Array<(data: CacheStackEvents[K]) => void>;
+    listenerCount<K extends keyof CacheStackEvents>(event: K): number;
+    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 fetchRateLimiter;
+    private readonly backgroundRefreshes;
+    private readonly layerDegradedUntil;
+    private readonly ttlResolver;
+    private readonly circuitBreakerManager;
+    private currentGeneration?;
+    private readonly writeBehindQueue;
+    private writeBehindTimer?;
+    private writeBehindFlushPromise?;
+    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>;
+    /**
+     * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+     * Useful when the value is expected to exist or the fetcher is expected to
+     * return non-null.
+     */
+    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
+    /**
+     * 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>;
+    invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    invalidateByPattern(pattern: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<void>;
+    getMetrics(): CacheMetricsSnapshot;
+    getStats(): CacheStatsSnapshot;
+    resetMetrics(): void;
+    /**
+     * Returns computed hit-rate statistics (overall and per-layer).
+     */
+    getHitRate(): CacheHitRateSnapshot;
+    healthCheck(): Promise<CacheHealthCheckResult[]>;
+    bumpGeneration(nextGeneration?: number): number;
+    /**
+     * Returns detailed metadata about a single cache key: which layers contain it,
+     * remaining fresh/stale/error TTLs, and associated tags.
+     * Returns `null` if the key does not exist in any layer.
+     */
+    inspect(key: string): Promise<CacheInspectResult | null>;
+    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 writeBatch;
+    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 getTagsForKey;
+    private formatError;
+    private sleep;
+    private shouldBroadcastL1Invalidation;
+    private initializeWriteBehind;
+    private shouldWriteBehind;
+    private enqueueWriteBehind;
+    private flushWriteBehindQueue;
+    private buildLayerSetEntry;
+    private intersectKeys;
+    private qualifyKey;
+    private qualifyPattern;
+    private stripQualifiedKey;
+    private generationPrefix;
+    private deleteKeysFromLayers;
+    private validateConfiguration;
+    private validateWriteOptions;
+    private validateLayerNumberOption;
+    private validatePositiveNumber;
+    private validateNonNegativeNumber;
+    private validateCacheKey;
+    private validateTtlPolicy;
+    private assertActive;
+    private awaitStartup;
+    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;
+}
+
+interface HonoLikeRequest {
+    method?: string;
+    url?: string;
+    path?: string;
+    query?: Record<string, unknown>;
+}
+interface HonoLikeContext {
+    req: HonoLikeRequest;
+    header?: (name: string, value: string) => void;
+    json: (body: unknown, status?: number) => Response | Promise<Response> | unknown;
+}
+interface HonoCacheMiddlewareOptions extends CacheGetOptions {
+    keyResolver?: (request: HonoLikeRequest) => string;
+    methods?: string[];
+}
+declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<void>;
+
+export { type CacheStatsSnapshot as A, type CacheTtlPolicy as B, type CacheLogger as C, type CacheTtlPolicyContext as D, type CacheWarmEntry as E, type CacheWarmOptions as F, type CacheWarmProgress as G, type CacheWriteBehindOptions as H, type InvalidationBus as I, type CacheWriteOptions as J, type EvictionPolicy as K, type LayerTtlMap as L, MemoryLayer as M, type MemoryLayerOptions as N, type MemoryLayerSnapshotEntry as O, PatternMatcher as P, createHonoCacheMiddleware as Q, TagIndex as T, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheDegradationOptions as m, type CacheHealthCheckResult as n, type CacheHitRateSnapshot as o, type CacheInspectResult as p, type CacheLayerLatency as q, type CacheMGetEntry as r, type CacheMSetEntry as s, type CacheMetricsSnapshot as t, CacheMissError as u, CacheNamespace as v, type CacheRateLimitOptions as w, type CacheSnapshotEntry as x, type CacheStackEvents as y, type CacheStackOptions as z };