layercache 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -1,6 +1,14 @@
 import { EventEmitter } from 'node:events';
 import Redis from 'ioredis';
 
+/**
+ * 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;
 }
@@ -16,6 +24,15 @@ interface CacheWriteOptions {
     refreshAhead?: number | LayerTtlMap;
     adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
+    /**
+     * 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 {
 }
@@ -63,6 +80,15 @@ 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;
@@ -82,6 +108,8 @@ interface CacheMetricsSnapshot {
     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;
 }
@@ -103,6 +131,8 @@ interface CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: 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>;
 }
@@ -205,6 +235,22 @@ interface CacheStatsSnapshot {
     }>;
     backgroundRefreshes: number;
 }
+/** 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. */
@@ -260,6 +306,10 @@ declare class CacheNamespace {
     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>;
@@ -270,10 +320,24 @@ declare class CacheNamespace {
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
     invalidateByPattern(pattern: 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;
 }
 
@@ -313,6 +377,12 @@ declare class CacheStack extends EventEmitter {
      * 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.
      */
@@ -357,6 +427,12 @@ declare class CacheStack extends EventEmitter {
      * Returns computed hit-rate statistics (overall and per-layer).
      */
     getHitRate(): CacheHitRateSnapshot;
+    /**
+     * 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>;
@@ -380,6 +456,7 @@ declare class CacheStack extends EventEmitter {
     private deleteKeys;
     private publishInvalidation;
     private handleInvalidationMessage;
+    private getTagsForKey;
     private formatError;
     private sleep;
     private shouldBroadcastL1Invalidation;
@@ -424,15 +501,23 @@ interface RedisInvalidationBusOptions {
     subscriber?: Redis;
     channel?: string;
 }
+/**
+ * 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 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 +536,7 @@ declare class RedisTagIndex implements CacheTagIndex {
     track(key: string, tags: string[]): Promise<void>;
     remove(key: string): Promise<void>;
     keysForTag(tag: string): Promise<string[]>;
+    tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
     private scanIndexKeys;
@@ -459,16 +545,28 @@ declare class RedisTagIndex implements CacheTagIndex {
     private tagKeysKey;
 }
 
+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[]>;
+    tagsForKey(key: string): Promise<string[]>;
     matchPattern(pattern: string): Promise<string[]>;
     clear(): Promise<void>;
+    private pruneKnownKeysIfNeeded;
 }
 
 declare function createCacheStatsHandler(cache: CacheStack): (_request: unknown, response: {
@@ -493,6 +591,48 @@ 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;
 }
@@ -602,7 +742,14 @@ declare class RedisLayer implements CacheLayer {
     private withPrefix;
     private deserializeOrDelete;
     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 +758,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,6 +782,7 @@ declare class DiskLayer implements CacheLayer {
     readonly isLocal = true;
     private readonly directory;
     private readonly serializer;
+    private readonly maxFiles;
     constructor(options: DiskLayerOptions);
     get<T>(key: string): Promise<T | null>;
     getEntry<T = unknown>(key: string): Promise<T | null>;
@@ -635,10 +792,18 @@ declare class DiskLayer implements CacheLayer {
     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>;
     private keyToPath;
     private safeDelete;
+    /**
+     * Removes the oldest files (by mtime) when the directory exceeds maxFiles.
+     */
+    private enforceMaxFiles;
 }
 
 /**
@@ -663,10 +828,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 +854,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 +898,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 +918,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 { type CacheAdaptiveTtlOptions, type CacheCircuitBreakerOptions, type CacheDegradationOptions, type CacheGetOptions, type CacheHitRateSnapshot, type CacheInspectResult, type CacheLayer, type CacheLayerLatency, type CacheLogger, type CacheMGetEntry, type CacheMSetEntry, type CacheMetricsSnapshot, CacheMissError, 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, createExpressCacheMiddleware, createFastifyLayercachePlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };