layercache 1.4.0 → 2.1.0

package/dist/{edge-D2FpRlyS.d.cts → edge-BCU8D-Yd.d.cts}

@@ -8,30 +8,52 @@ declare class CacheMissError extends Error {
     readonly key: string;
     constructor(key: string);
 }
+/** Per-layer millisecond values keyed by each layer's `name`. */
 interface LayerTtlMap {
+    /** Millisecond value for the named layer, or `undefined` to fall back. */
     [layerName: string]: number | undefined;
 }
+/** Internal write classification used when resolving TTLs and entry options. */
 type CacheEntryWriteKind = 'value' | 'empty';
+/** Options that describe how a cache entry should be stored. */
 interface CacheEntryWriteOptions {
+    /** Tags to associate with the key for tag-based invalidation or expiration. */
     tags?: string[];
+    /** Fresh TTL in milliseconds, either uniform or per layer. */
     ttl?: number | LayerTtlMap;
+    /** Dynamic TTL policy used instead of, or before falling back to, `ttl`. */
     ttlPolicy?: CacheTtlPolicy;
+    /** TTL in milliseconds for cached null/empty results when negative caching is enabled. */
     negativeTtl?: number | LayerTtlMap;
+    /** Extra window in milliseconds where stale values are returned while refresh runs in the background. */
     staleWhileRevalidate?: number | LayerTtlMap;
+    /** Extra window in milliseconds where stale values are returned if refresh fails. */
     staleIfError?: number | LayerTtlMap;
+    /** Random +/- jitter in milliseconds applied to resolved TTLs to avoid synchronized expiry. */
     ttlJitter?: number | LayerTtlMap;
+    /** Increase TTL for frequently accessed keys using the adaptive TTL policy. */
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
 }
+/** Context passed to `contextOptions` before a value is written. */
 interface CacheContextOptionsContext {
+    /** Fully qualified cache key being written. */
     key: string;
+    /** Value returned by the fetcher or passed to `set()`. */
     value: unknown;
+    /** Whether the write stores a normal value or an empty/negative-cache marker. */
     kind: CacheEntryWriteKind;
 }
+/** Options accepted by write operations and read-through fetch writes. */
 interface CacheWriteOptions extends CacheEntryWriteOptions {
+    /** Cache `null` fetcher results using `negativeTtl` instead of treating them as misses. */
     negativeCache?: boolean;
+    /** Extend a key's TTL on fresh reads. */
     slidingTtl?: boolean;
+    /** Refresh in the background when the remaining TTL is at or below this threshold in milliseconds. */
     refreshAhead?: number | LayerTtlMap;
+    /** Circuit breaker controls for this operation's fetcher. */
     circuitBreaker?: CacheCircuitBreakerOptions;
+    /** Rate limit concurrent fetcher execution for this operation. */
     fetcherRateLimit?: CacheRateLimitOptions;
     /**
      * Optional predicate called with the fetcher's return value before caching.
@@ -61,31 +83,51 @@ interface CacheWriteOptions extends CacheEntryWriteOptions {
      */
     contextOptions?: (context: CacheContextOptionsContext) => CacheEntryWriteOptions | undefined;
 }
+/** Options accepted by read-through `get()` operations. */
 interface CacheGetOptions extends CacheWriteOptions {
 }
+/** Metadata passed to a read-through fetcher. */
 interface CacheFetcherContext<T = unknown> {
+    /** Fully qualified cache key being fetched. */
     key: string;
+    /** Existing stale value, when a refresh is triggered from stale state. */
     currentValue: T | undefined;
+    /** Cache state that caused the fetcher to run. */
     state: 'miss' | 'fresh' | 'stale-while-revalidate' | 'stale-if-error';
+    /** Layer that supplied the existing value, when available. */
     layer?: string;
 }
+/** Async function used by read-through cache operations to produce a value on miss or refresh. */
 type CacheFetcher<T = unknown> = (context: CacheFetcherContext<T>) => Promise<T>;
+/** Entry descriptor for `CacheStack.mget()`. */
 interface CacheMGetEntry<T> {
+    /** Cache key to read. */
     key: string;
+    /** Optional read-through fetcher for this key. */
     fetch?: CacheFetcher<T>;
+    /** Per-entry get/write options. */
     options?: CacheGetOptions;
 }
+/** Entry descriptor for `CacheStack.mset()`. */
 interface CacheMSetEntry<T> {
+    /** Cache key to write. */
     key: string;
+    /** Value to store. */
     value: T;
+    /** Per-entry write options. */
     options?: CacheWriteOptions;
 }
 /** Interface that all cache backend implementations must satisfy. */
 interface CacheLayer {
+    /** Human-readable unique layer name used for metrics and per-layer options. */
     readonly name: string;
+    /** Default TTL in milliseconds used when a write does not provide one. */
     readonly defaultTtl?: number;
+    /** Whether the layer is local to this process, such as memory or disk. */
     readonly isLocal?: boolean;
+    /** Read and unwrap a fresh value, returning `null` on miss or expiry. */
     get<T>(key: string): Promise<T | null>;
+    /** Read the raw stored value or envelope so CacheStack can resolve stale state. */
     getEntry?<T = unknown>(key: string): Promise<T | null>;
     /**
      * Bulk read fast-path. Implementations should return raw stored entries using
@@ -93,14 +135,23 @@ interface CacheLayer {
      * stale windows, and negative-cache markers consistently.
      */
     getMany?<T>(keys: string[]): Promise<Array<T | null>>;
+    /** Bulk write entries; implementations may use this as an optimized fast path. */
     setMany?(entries: CacheLayerSetManyEntry[]): Promise<void>;
+    /** Store a raw value for `ttl` milliseconds, or without expiry when omitted. */
     set(key: string, value: unknown, ttl?: number): Promise<void>;
+    /** Delete a key from this layer. */
     delete(key: string): Promise<void>;
+    /** Remove all keys from this layer. */
     clear(): Promise<void>;
+    /** Delete several keys from this layer; CacheStack falls back to `delete()` when absent. */
     deleteMany?(keys: string[]): Promise<void>;
+    /** Return known keys in this layer for pattern or prefix invalidation. */
     keys?(): Promise<string[]>;
+    /** Visit known keys without materializing the full key list. */
     forEachKey?(visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /** Health check hook used by `CacheStack.healthCheck()`. */
     ping?(): Promise<boolean>;
+    /** Release sockets, timers, or other resources held by the layer. */
     dispose?(): Promise<void>;
     /**
      * Returns true if the key exists and has not expired.
@@ -119,8 +170,11 @@ interface CacheLayer {
      */
     size?(): Promise<number>;
 }
+/** Serializer used by layers that convert values to bytes or strings. */
 interface CacheSerializer {
+    /** Convert a value to a storable payload. */
     serialize(value: unknown): string | Buffer;
+    /** Restore a value from a payload. */
     deserialize<T>(payload: string | Buffer): T;
 }
 /** Per-layer latency statistics (rolling window of sampled read durations). */
@@ -134,22 +188,39 @@ interface CacheLayerLatency {
 }
 /** Snapshot of cumulative cache counters. */
 interface CacheMetricsSnapshot {
+    /** Number of successful cache reads. */
     hits: number;
+    /** Number of reads that did not find a usable value. */
     misses: number;
+    /** Number of fetcher executions. */
     fetches: number;
+    /** Number of cache write operations. */
     sets: number;
+    /** Number of delete operations. */
     deletes: number;
+    /** Number of values backfilled from slower layers into faster layers. */
     backfills: number;
+    /** Number of invalidation operations. */
     invalidations: number;
+    /** Number of stale values returned to callers. */
     staleHits: number;
+    /** Number of background refresh attempts. */
     refreshes: number;
+    /** Number of failed refresh attempts. */
     refreshErrors: number;
+    /** Number of layer write failures. */
     writeFailures: number;
+    /** Number of requests that waited for a single-flight result. */
     singleFlightWaits: number;
+    /** Number of cached negative/empty results served. */
     negativeCacheHits: number;
+    /** Number of times circuit breakers blocked a fetcher. */
     circuitBreakerTrips: number;
+    /** Number of operations skipped or retried due to degraded layers. */
     degradedOperations: number;
+    /** Hit counts grouped by layer name. */
     hitsByLayer: Record<string, number>;
+    /** Miss counts grouped by layer name. */
     missesByLayer: Record<string, number>;
     /** Per-layer read latency statistics (sampled from successful reads). */
     latencyByLayer: Record<string, CacheLayerLatency>;
@@ -164,86 +235,154 @@ interface CacheHitRateSnapshot {
     byLayer: Record<string, number>;
 }
 interface CacheLogger {
+    /** Low-volume diagnostic events. */
     debug?(message: string, context?: Record<string, unknown>): void;
+    /** Informational operational messages. */
     info?(message: string, context?: Record<string, unknown>): void;
+    /** Recoverable problems or risky configuration warnings. */
     warn?(message: string, context?: Record<string, unknown>): void;
+    /** Errors surfaced by cache operations or layer integrations. */
     error?(message: string, context?: Record<string, unknown>): void;
 }
+/** Index used to map cache keys to tags and discover keys for invalidation. */
 interface CacheTagIndex {
+    /** Record that a key exists, even when it has no tags. */
     touch(key: string): Promise<void>;
+    /** Associate a key with the provided tags, replacing any previous tag set. */
     track(key: string, tags: string[]): Promise<void>;
+    /** Remove all tag/index metadata for a key. */
     remove(key: string): Promise<void>;
+    /** Return keys currently associated with a tag. */
     keysForTag(tag: string): Promise<string[]>;
+    /** Visit keys for a tag without materializing all results. */
     forEachKeyForTag?(tag: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /** Return known keys with the given prefix. */
     keysForPrefix?(prefix: string): Promise<string[]>;
+    /** Visit known keys with the given prefix without materializing all results. */
     forEachKeyForPrefix?(prefix: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
     /** Returns the tags associated with a specific key, or an empty array. */
     tagsForKey?(key: string): Promise<string[]>;
+    /** Return known keys matching a wildcard pattern. */
     matchPattern(pattern: string): Promise<string[]>;
+    /** Visit known keys matching a wildcard pattern without materializing all results. */
     forEachKeyMatchingPattern?(pattern: string, visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /** Remove all index state. */
     clear(): Promise<void>;
 }
+/** Raw layer bulk-write entry. */
 interface CacheLayerSetManyEntry {
+    /** Cache key to write. */
     key: string;
+    /** Raw value or envelope to store. */
     value: unknown;
+    /** TTL in milliseconds for this layer entry. */
     ttl?: number;
 }
+/** Cross-process invalidation message sent through an `InvalidationBus`. */
 interface InvalidationMessage {
+    /** Message target scope. */
     scope: 'key' | 'keys' | 'clear';
+    /** Sender instance id; receivers ignore messages from themselves. */
     sourceId: string;
+    /** Keys affected by key- or keys-scoped messages. */
     keys?: string[];
+    /** Operation that produced this invalidation. */
     operation?: 'write' | 'delete' | 'invalidate' | 'expire' | 'clear';
 }
+/** Pub/sub abstraction used to broadcast invalidation across CacheStack instances. */
 interface InvalidationBus {
+    /** Register a message handler and return an unsubscribe function. */
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void> | void>;
+    /** Publish an invalidation message to other subscribers. */
     publish(message: InvalidationMessage): Promise<void>;
 }
+/** Timing controls for a distributed single-flight execution. */
 interface CacheSingleFlightExecutionOptions {
+    /** Lease duration in milliseconds for the worker lock. */
     leaseMs: number;
+    /** Maximum time in milliseconds a waiter should poll for the worker result. */
     waitTimeoutMs: number;
+    /** Poll interval in milliseconds for waiters. */
     pollIntervalMs: number;
+    /** Optional interval in milliseconds for renewing a worker lock lease. */
     renewIntervalMs?: number;
 }
+/** Coordinator that deduplicates fetchers across processes. */
 interface CacheSingleFlightCoordinator {
+    /** Run `worker` when this process wins the lock, otherwise run `waiter`. */
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
 }
+/** Global options for a `CacheStack` instance. */
 interface CacheStackOptions {
+    /** Logger instance, `true` for console debug logging, or `false`/omitted for quiet mode. */
     logger?: CacheLogger | boolean;
+    /** Enable metrics collection. Currently metrics are always collected; this is kept for API compatibility. */
     metrics?: boolean;
+    /** Deduplicate concurrent local fetches for the same key. */
     stampedePrevention?: boolean;
+    /** Maximum number of distinct keys allowed in the local stampede guard. */
     stampedeMaxInFlight?: number;
+    /** Timeout in milliseconds for a local stampede-guarded fetch. */
     stampedeEntryTimeoutMs?: number;
+    /** Bus used to receive and publish cross-process invalidation messages. */
     invalidationBus?: InvalidationBus;
+    /** Tag index implementation used for tag, prefix, and pattern discovery. */
     tagIndex?: CacheTagIndex;
+    /** Generation number prefixed onto all keys for instant bulk invalidation. */
     generation?: number;
+    /** Enable cleanup for keys from previous generations. */
     generationCleanup?: boolean | CacheGenerationCleanupOptions;
+    /** Broadcast writes to other instances so their L1/local layers drop stale values. */
     broadcastL1Invalidation?: boolean;
     /**
      * @deprecated Use `broadcastL1Invalidation` instead.
      */
     publishSetInvalidation?: boolean;
+    /** Cache null fetcher results as negative entries. */
     negativeCaching?: boolean;
+    /** Default negative-cache TTL in milliseconds. */
     negativeTtl?: number | LayerTtlMap;
+    /** Default stale-while-revalidate window in milliseconds. */
     staleWhileRevalidate?: number | LayerTtlMap;
+    /** Default stale-if-error window in milliseconds. */
     staleIfError?: number | LayerTtlMap;
+    /** Default TTL jitter in milliseconds. */
     ttlJitter?: number | LayerTtlMap;
+    /** Default refresh-ahead threshold in milliseconds. */
     refreshAhead?: number | LayerTtlMap;
+    /** Default adaptive TTL policy. */
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
+    /** Default circuit breaker settings for fetchers. */
     circuitBreaker?: CacheCircuitBreakerOptions;
+    /** Keep using healthy layers when another layer fails temporarily. */
     gracefulDegradation?: boolean | CacheDegradationOptions;
+    /** Write behavior: fail on any layer error (`strict`) or only if all layers fail (`best-effort`). */
     writePolicy?: 'strict' | 'best-effort';
+    /** Write immediately to all layers or queue writes behind the response path. */
     writeStrategy?: 'write-through' | 'write-behind';
+    /** Queue controls used when `writeStrategy` is `write-behind`. */
     writeBehind?: CacheWriteBehindOptions;
+    /** Default fetcher rate limit settings. */
     fetcherRateLimit?: CacheRateLimitOptions;
+    /** Max milliseconds allowed for background refresh before it is aborted. */
     backgroundRefreshTimeoutMs?: number;
+    /** Coordinator used for distributed single-flight fetcher deduplication. */
     singleFlightCoordinator?: CacheSingleFlightCoordinator;
+    /** Distributed single-flight lock lease in milliseconds. */
     singleFlightLeaseMs?: number;
+    /** Maximum milliseconds waiters poll for distributed single-flight completion. */
     singleFlightTimeoutMs?: number;
+    /** Poll interval in milliseconds for distributed single-flight waiters. */
     singleFlightPollMs?: number;
+    /** Interval in milliseconds for renewing distributed single-flight leases. */
     singleFlightRenewIntervalMs?: number;
+    /** Base directory that constrains snapshot persistence paths, or `false` to disable path sandboxing. */
     snapshotBaseDir?: string | false;
+    /** Maximum snapshot file size in bytes accepted during restore, or `false` to disable. */
     snapshotMaxBytes?: number | false;
+    /** Maximum number of entries exported or imported in one snapshot, or `false` to disable. */
     snapshotMaxEntries?: number | false;
+    /** Maximum keys one invalidation scan may affect, or `false` to disable the guard. */
     invalidationMaxKeys?: number | false;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
@@ -252,85 +391,140 @@ interface CacheStackOptions {
      */
     maxProfileEntries?: number;
 }
+/** Adaptive TTL policy settings for hot keys. */
 interface CacheAdaptiveTtlOptions {
+    /** Number of accesses after which a key is considered hot. */
     hotAfter?: number;
+    /** TTL increment in milliseconds, uniform or per layer. */
     step?: number | LayerTtlMap;
+    /** Maximum TTL in milliseconds after adaptive increases. */
     maxTtl?: number | LayerTtlMap;
 }
+/** Options for pruning keys from older generations. */
 interface CacheGenerationCleanupOptions {
+    /** Number of old-generation keys to remove per cleanup batch. */
     batchSize?: number;
 }
+/** Built-in TTL policies or a function that returns a TTL in milliseconds. */
 type CacheTtlPolicy = 'until-midnight' | 'next-hour' | {
     alignTo: number;
 } | ((context: CacheTtlPolicyContext) => number | undefined);
+/** Context passed to a custom TTL policy. */
 interface CacheTtlPolicyContext {
+    /** Fully qualified cache key being written. */
     key: string;
+    /** Value being written. */
     value: unknown;
 }
+/** Circuit breaker settings for protecting failing fetchers. */
 interface CacheCircuitBreakerOptions {
+    /** Consecutive failures before the circuit opens. */
     failureThreshold?: number;
+    /** Milliseconds before an open circuit allows another attempt. */
     cooldownMs?: number;
 }
+/** Graceful degradation settings for temporarily unhealthy layers. */
 interface CacheDegradationOptions {
+    /** Milliseconds to skip a failed layer before trying it again. */
     retryAfterMs?: number;
 }
+/** Fetcher concurrency/rate limiting settings. */
 interface CacheRateLimitOptions {
+    /** Maximum concurrent fetchers allowed in the selected scope. */
     maxConcurrent?: number;
+    /** Window size in milliseconds for `maxPerInterval`. */
     intervalMs?: number;
+    /** Maximum fetches allowed per interval window. */
     maxPerInterval?: number;
+    /** Whether limits apply globally, per cache key, or per fetcher function. */
     scope?: 'global' | 'key' | 'fetcher';
+    /** Custom bucket id used to group otherwise unrelated fetches. */
     bucketKey?: string;
 }
+/** Queue controls for write-behind mode. */
 interface CacheWriteBehindOptions {
+    /** Milliseconds between automatic queue flushes. */
     flushIntervalMs?: number;
+    /** Maximum entries flushed in one batch. */
     batchSize?: number;
+    /** Maximum queued writes before new writes are rejected. */
     maxQueueSize?: number;
 }
+/** Entry used by `CacheStack.warm()` to pre-populate a key. */
 interface CacheWarmEntry<T = unknown> {
+    /** Cache key to warm. */
     key: string;
+    /** Fetcher used to produce the value. */
     fetcher: CacheFetcher<T>;
+    /** Cache options applied while warming this entry. */
     options?: CacheGetOptions;
+    /** Higher priority entries are warmed first. */
     priority?: number;
 }
 /** Options controlling the cache warm-up process. */
 interface CacheWarmOptions {
+    /** Number of warm fetchers to run concurrently. Defaults to 4. */
     concurrency?: number;
+    /** Continue warming remaining entries after an entry fails. */
     continueOnError?: boolean;
     /** Called after each entry is processed (success or failure). */
     onProgress?: (progress: CacheWarmProgress) => void;
 }
 /** Progress information delivered to `CacheWarmOptions.onProgress`. */
 interface CacheWarmProgress {
+    /** Number of entries processed so far. */
     completed: number;
+    /** Total entries scheduled for warming. */
     total: number;
+    /** Key that just finished processing. */
     key: string;
+    /** Whether the key was warmed successfully. */
     success: boolean;
 }
+/** Options for `CacheStack.wrap()` and `CacheNamespace.wrap()`. */
 interface CacheWrapOptions<TArgs extends unknown[] = unknown[]> extends CacheGetOptions {
+    /** Converts wrapper function arguments into a cache key suffix. */
     keyResolver?: (...args: TArgs) => string;
 }
+/** Entry exported by snapshot APIs. */
 interface CacheSnapshotEntry {
+    /** Cache key. */
     key: string;
+    /** Stored value or envelope. */
     value: unknown;
+    /** Remaining TTL in milliseconds, when available. */
     ttl?: number;
 }
+/** Snapshot of metrics, layer health state, and active background work. */
 interface CacheStatsSnapshot {
+    /** Current cumulative metrics. */
     metrics: CacheMetricsSnapshot;
+    /** Layer-level runtime state. */
     layers: Array<{
+        /** Layer name. */
         name: string;
+        /** Whether the layer is local to this process. */
         isLocal: boolean;
+        /** Timestamp in milliseconds until which the layer is degraded, or null. */
         degradedUntil: number | null;
     }>;
+    /** Number of background refreshes currently running. */
     backgroundRefreshes: number;
 }
+/** Result returned by `CacheStack.healthCheck()`. */
 interface CacheHealthCheckResult {
+    /** Layer name. */
     layer: string;
+    /** Whether the layer responded successfully. */
     healthy: boolean;
+    /** Time spent checking this layer in milliseconds. */
     latencyMs: number;
+    /** Failure message when `healthy` is false. */
     error?: string;
 }
 /** Detailed inspection result for a single cache key. */
 interface CacheInspectResult {
+    /** User-facing cache key. */
     key: string;
     /** Layers in which the key is currently stored (not expired). */
     foundInLayers: string[];
@@ -414,8 +608,11 @@ interface CacheStackEvents {
 }
 
 interface MemoryLayerSnapshotEntry {
+    /** Cache key stored in the snapshot. */
     key: string;
+    /** Stored raw value or envelope. */
     value: unknown;
+    /** Absolute expiry timestamp in milliseconds, or null for no expiry. */
     expiresAt: number | null;
 }
 /**
@@ -426,13 +623,22 @@ interface MemoryLayerSnapshotEntry {
  */
 type EvictionPolicy = 'lru' | 'lfu' | 'fifo';
 interface MemoryLayerOptions {
+    /** Default TTL in milliseconds for entries written without an explicit TTL. */
     ttl?: number;
+    /** Maximum number of entries retained in memory. Defaults to 1,000. */
     maxSize?: number;
+    /** Layer name used for metrics and per-layer TTL maps. Defaults to `memory`. */
     name?: string;
+    /** Eviction policy used when `maxSize` is exceeded. Defaults to `lru`. */
     evictionPolicy?: EvictionPolicy;
+    /** Milliseconds between automatic expired-entry cleanup passes. Disabled when omitted. */
     cleanupIntervalMs?: number;
+    /** Called with the key and unwrapped value whenever an entry is evicted. */
     onEvict?: (key: string, value: unknown) => void;
 }
+/**
+ * In-process cache layer with TTL support and bounded-size eviction.
+ */
 declare class MemoryLayer implements CacheLayer {
     readonly name: string;
     readonly defaultTtl?: number;
@@ -442,23 +648,77 @@ declare class MemoryLayer implements CacheLayer {
     private readonly onEvict?;
     private readonly entries;
     private cleanupTimer?;
+    /**
+     * Creates an in-memory cache layer.
+     */
     constructor(options?: MemoryLayerOptions);
+    /**
+     * Reads and unwraps a fresh value from memory.
+     */
     get<T>(key: string): Promise<T | null>;
+    /**
+     * Reads the raw stored value or envelope from memory.
+     */
     getEntry<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Reads many raw entries from memory.
+     */
     getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Writes many entries to memory.
+     */
     setMany(entries: CacheLayerSetManyEntry[]): Promise<void>;
+    /**
+     * Stores a value in memory using the provided TTL or layer default TTL.
+     */
     set(key: string, value: unknown, ttl?: number | undefined): 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>;
+    /**
+     * Returns the number of currently retained, non-expired entries.
+     */
     size(): Promise<number>;
+    /**
+     * Deletes a key from memory.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Deletes multiple keys from memory.
+     */
     deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Removes all entries from memory.
+     */
     clear(): Promise<void>;
+    /**
+     * Health check hook that always succeeds for the in-process layer.
+     */
     ping(): Promise<boolean>;
+    /**
+     * Stops the cleanup timer, when one is active.
+     */
     dispose(): Promise<void>;
+    /**
+     * Returns all currently retained, non-expired keys.
+     */
     keys(): Promise<string[]>;
+    /**
+     * Visits all currently retained, non-expired keys.
+     */
     forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
+    /**
+     * Exports memory entries for process-local snapshots.
+     */
     exportState(): MemoryLayerSnapshotEntry[];
+    /**
+     * Imports entries previously produced by `exportState()`.
+     */
     importState(entries: MemoryLayerSnapshotEntry[]): void;
     private evict;
     private pruneExpired;
@@ -495,16 +755,49 @@ declare class TagIndex implements CacheTagIndex {
     private nextNodeId;
     private readonly root;
     constructor(options?: TagIndexOptions);
+    /**
+     * 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 tag and known-key index state.
+     */
     clear(): Promise<void>;
     private createTrieNode;
     private insertKnownKey;
@@ -517,41 +810,133 @@ declare class TagIndex implements CacheTagIndex {
     private removeKnownKey;
 }
 
+/**
+ * Prefix-scoped view over a `CacheStack`.
+ *
+ * All keys and tags passed through the namespace are qualified with the
+ * namespace prefix, while metrics are tracked separately for namespace usage.
+ */
 declare class CacheNamespace {
     private readonly cache;
     private readonly prefix;
     private static readonly metricsMutexes;
     private metrics;
+    /**
+     * Creates a namespace backed by an existing cache stack.
+     */
     constructor(cache: CacheStack, prefix: string);
+    /**
+     * Reads a key inside this namespace and optionally runs a read-through fetcher
+     * on miss or refresh.
+     */
     get<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
+    /**
+     * Alias for `get(key, fetcher, options)` that makes the get-or-set behavior explicit.
+     */
     getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      */
     getOrThrow<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T>;
+    /**
+     * Returns true when the namespaced key exists and has not expired in any layer.
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Returns the remaining TTL in milliseconds for the namespaced key.
+     */
     ttl(key: string): Promise<number | null>;
+    /**
+     * Stores a value under a namespaced key.
+     */
     set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
+    /**
+     * Deletes a namespaced key from all layers.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Deletes multiple namespaced keys from all layers.
+     */
     mdelete(keys: string[]): Promise<void>;
+    /**
+     * Alias for `delete(key)` scoped to this namespace.
+     */
+    invalidateByKey(key: string): Promise<void>;
+    /**
+     * Alias for `mdelete(keys)` scoped to this namespace.
+     */
+    invalidateByKeys(keys: string[]): Promise<void>;
+    /**
+     * Marks one exact namespaced key expired without deleting its stale value.
+     */
+    expireByKey(key: string): Promise<void>;
+    /**
+     * Marks multiple exact namespaced keys expired without deleting their stale values.
+     */
+    expireByKeys(keys: string[]): Promise<void>;
+    /**
+     * Clears all keys in this namespace by invalidating the namespace prefix.
+     */
     clear(): Promise<void>;
+    /**
+     * Reads many namespaced keys concurrently.
+     */
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
+    /**
+     * Writes many namespaced entries concurrently.
+     */
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
+    /**
+     * Deletes keys associated with a tag scoped to this namespace.
+     */
     invalidateByTag(tag: string): Promise<void>;
+    /**
+     * Expires keys associated with a tag scoped to this namespace while preserving stale windows.
+     */
     expireByTag(tag: string): Promise<void>;
+    /**
+     * Deletes keys associated with any or all namespace-scoped tags.
+     */
     invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    /**
+     * Expires keys associated with any or all namespace-scoped tags while preserving stale windows.
+     */
     expireByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    /**
+     * Deletes namespaced keys matching a wildcard pattern.
+     */
     invalidateByPattern(pattern: string): Promise<void>;
+    /**
+     * Expires namespaced keys matching a wildcard pattern while preserving stale windows.
+     */
     expireByPattern(pattern: string): Promise<void>;
+    /**
+     * Deletes namespaced keys with the provided prefix.
+     */
     invalidateByPrefix(prefix: string): Promise<void>;
+    /**
+     * Expires namespaced keys with the provided prefix while preserving stale windows.
+     */
     expireByPrefix(prefix: string): Promise<void>;
     /**
      * Returns detailed metadata about a single cache key within this namespace.
      */
     inspect(key: string): Promise<CacheInspectResult | null>;
+    /**
+     * Returns a cached wrapper whose generated keys are scoped to this namespace.
+     */
     wrap<TArgs extends unknown[], TResult>(keyPrefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
+    /**
+     * Warms entries after qualifying each key and tag with this namespace prefix.
+     */
     warm(entries: CacheWarmEntry[], options?: CacheWarmOptions): Promise<void>;
+    /**
+     * Returns metrics accumulated by operations performed through this namespace.
+     */
     getMetrics(): CacheMetricsSnapshot;
+    /**
+     * Returns hit-rate statistics for operations performed through this namespace.
+     */
     getHitRate(): CacheHitRateSnapshot;
     /**
      * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
@@ -563,6 +948,9 @@ declare class CacheNamespace {
      * ```
      */
     namespace(childPrefix: string): CacheNamespace;
+    /**
+     * Qualifies a raw key with this namespace prefix.
+     */
     qualify(key: string): string;
     private qualifyTag;
     private qualifyGetOptions;
@@ -574,14 +962,27 @@ declare class CacheNamespace {
 
 /** Typed overloads for EventEmitter so callers get autocomplete on event names. */
 interface CacheStack {
+    /** Register a typed CacheStack event listener. */
     on<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
+    /** Register a typed CacheStack event listener that runs once. */
     once<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
+    /** Remove a typed CacheStack event listener. */
     off<K extends keyof CacheStackEvents>(event: K, listener: (data: CacheStackEvents[K]) => void): this;
+    /** Remove all listeners, optionally only for one typed CacheStack event. */
     removeAllListeners<K extends keyof CacheStackEvents>(event?: K): this;
+    /** Return listeners registered for a typed CacheStack event. */
     listeners<K extends keyof CacheStackEvents>(event: K): Array<(data: CacheStackEvents[K]) => void>;
+    /** Return the listener count for a typed CacheStack event. */
     listenerCount<K extends keyof CacheStackEvents>(event: K): number;
+    /** Emit a typed CacheStack event. Mostly useful for custom integrations. */
     emit<K extends keyof CacheStackEvents>(event: K, data: CacheStackEvents[K]): boolean;
 }
+/**
+ * Multi-layer read-through cache coordinator.
+ *
+ * Layers are checked from fastest to slowest, partial hits are backfilled into
+ * faster layers, and misses can be resolved by read-through fetchers.
+ */
 declare class CacheStack extends EventEmitter {
     private readonly layers;
     private readonly options;
@@ -607,6 +1008,9 @@ declare class CacheStack extends EventEmitter {
     private isDisconnecting;
     private readonly reader;
     private disconnectPromise?;
+    /**
+     * Creates a cache stack from ordered layers and optional global behavior settings.
+     */
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
     /**
      * Read-through cache get.
@@ -643,13 +1047,45 @@ declare class CacheStack extends EventEmitter {
      * Deletes the key from all layers and publishes an invalidation message.
      */
     delete(key: string): Promise<void>;
+    /**
+     * Clears every configured layer, removes tag metadata, resets internal TTL
+     * profiles, and broadcasts a clear invalidation message.
+     */
     clear(): Promise<void>;
     /**
      * Deletes multiple keys at once. More efficient than calling `delete()` in a loop.
      */
     mdelete(keys: string[]): Promise<void>;
+    /**
+     * Alias for `delete(key)` that matches the `invalidateBy*` API family.
+     */
+    invalidateByKey(key: string): Promise<void>;
+    /**
+     * Alias for `mdelete(keys)` that matches the `invalidateBy*` API family.
+     */
+    invalidateByKeys(keys: string[]): Promise<void>;
+    /**
+     * Marks one exact key expired without deleting its stale value.
+     */
+    expireByKey(key: string): Promise<void>;
+    /**
+     * Marks multiple exact keys expired without deleting their stale values.
+     */
+    expireByKeys(keys: string[]): Promise<void>;
+    /**
+     * Reads many keys concurrently. Simple reads use layer-level bulk fast paths;
+     * entries with fetchers or options fall back to per-entry read-through logic.
+     */
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
+    /**
+     * Writes many entries concurrently using each layer's bulk write fast path
+     * when available.
+     */
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
+    /**
+     * Pre-populates cache entries by running their fetchers with bounded
+     * concurrency. Higher-priority entries run first.
+     */
     warm(entries: CacheWarmEntry[], options?: CacheWarmOptions): Promise<void>;
     /**
      * Returns a cached version of `fetcher`. The cache key is derived from
@@ -661,21 +1097,64 @@ declare class CacheStack extends EventEmitter {
      * `prefix:`. Useful for multi-tenant or module-level isolation.
      */
     namespace(prefix: string): CacheNamespace;
+    /**
+     * Deletes every key currently associated with `tag` and broadcasts an
+     * invalidation message.
+     */
     invalidateByTag(tag: string): Promise<void>;
+    /**
+     * Marks every key associated with `tag` as expired while preserving stale
+     * windows for stale serving.
+     */
     expireByTag(tag: string): Promise<void>;
+    /**
+     * Deletes keys associated with any or all of the provided tags and broadcasts
+     * an invalidation message.
+     */
     invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    /**
+     * Marks keys associated with any or all of the provided tags as expired while
+     * preserving stale windows for stale serving.
+     */
     expireByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    /**
+     * Deletes keys matching a wildcard pattern such as `user:*`.
+     */
     invalidateByPattern(pattern: string): Promise<void>;
+    /**
+     * Marks keys matching a wildcard pattern as expired while preserving stale
+     * windows for stale serving.
+     */
     expireByPattern(pattern: string): Promise<void>;
+    /**
+     * Deletes keys that start with the provided prefix.
+     */
     invalidateByPrefix(prefix: string): Promise<void>;
+    /**
+     * Marks keys that start with the provided prefix as expired while preserving
+     * stale windows for stale serving.
+     */
     expireByPrefix(prefix: string): Promise<void>;
+    /**
+     * Returns cumulative cache metrics since startup or the last `resetMetrics()`.
+     */
     getMetrics(): CacheMetricsSnapshot;
+    /**
+     * Returns metrics plus layer degradation state and active background refresh count.
+     */
     getStats(): CacheStatsSnapshot;
+    /**
+     * Resets cumulative metrics counters.
+     */
     resetMetrics(): void;
     /**
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    /**
+     * Runs each layer's `ping()` hook when available and returns per-layer health
+     * and latency information.
+     */
     healthCheck(): Promise<CacheHealthCheckResult[]>;
     /**
      * Rotates the active generation prefix used for all future cache keys.
@@ -689,10 +1168,26 @@ declare class CacheStack extends EventEmitter {
      * Returns `null` if the key does not exist in any layer.
      */
     inspect(key: string): Promise<CacheInspectResult | null>;
+    /**
+     * Exports cache entries from configured layers for process-local snapshots.
+     */
     exportState(): Promise<CacheSnapshotEntry[]>;
+    /**
+     * Imports entries produced by `exportState()` into the configured layers.
+     */
     importState(entries: CacheSnapshotEntry[]): Promise<void>;
+    /**
+     * Writes a snapshot file containing current cache entries.
+     */
     persistToFile(filePath: string): Promise<void>;
+    /**
+     * Restores cache entries from a snapshot file.
+     */
     restoreFromFile(filePath: string): Promise<void>;
+    /**
+     * Flushes background work, unsubscribes from buses, disposes timers, and then
+     * disposes each layer that provides `dispose()`.
+     */
     disconnect(): Promise<void>;
     private initialize;
     private storeEntry;
@@ -754,10 +1249,19 @@ interface HonoLikeContext {
     json: (body: unknown, status?: number) => Response | Promise<Response> | unknown;
 }
 interface HonoCacheMiddlewareOptions extends CacheGetOptions {
+    /**
+     * Resolves a cache key from the incoming Hono request. Defaults to
+     * `GET:<normalized path>` when `allowPrivateCaching` is enabled.
+     */
     keyResolver?: (request: HonoLikeRequest) => string;
+    /** Only cache responses for these HTTP methods. Defaults to `['GET']`. */
     methods?: string[];
+    /** Explicitly allow URL-only implicit cache keys. Disabled by default. */
     allowPrivateCaching?: boolean;
 }
+/**
+ * Hono-compatible middleware that caches JSON responses for selected methods.
+ */
 declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<unknown>;
 
 export { CacheNamespace as A, type CacheRateLimitOptions as B, type CacheLogger as C, type CacheSnapshotEntry as D, type CacheStackEvents as E, type CacheStackOptions as F, type CacheStatsSnapshot as G, type CacheTtlPolicy as H, type InvalidationBus as I, type CacheTtlPolicyContext as J, type CacheWarmEntry as K, type CacheWarmOptions as L, type CacheWarmProgress as M, type CacheWriteBehindOptions as N, type CacheWriteOptions as O, type EvictionPolicy as P, type LayerTtlMap as Q, MemoryLayer as R, type MemoryLayerOptions as S, type MemoryLayerSnapshotEntry as T, PatternMatcher as U, TagIndex as V, createHonoCacheMiddleware as W, 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 CacheContextOptionsContext as m, type CacheDegradationOptions as n, type CacheEntryWriteKind as o, type CacheEntryWriteOptions as p, type CacheFetcher as q, type CacheFetcherContext as r, type CacheHealthCheckResult as s, type CacheHitRateSnapshot as t, type CacheInspectResult as u, type CacheLayerLatency as v, type CacheMGetEntry as w, type CacheMSetEntry as x, type CacheMetricsSnapshot as y, CacheMissError as z };