layercache 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from 'node:events';
 import Redis from 'ioredis';
 
 interface LayerTtlMap {
@@ -6,6 +7,15 @@ interface LayerTtlMap {
 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 {
 }
@@ -24,6 +34,8 @@ interface CacheLayer {
     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>;
@@ -42,9 +54,22 @@ interface CacheMetricsSnapshot {
     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>;
 }
 interface CacheLogger {
-    debug(message: string, context?: Record<string, unknown>): void;
+    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>;
@@ -64,16 +89,96 @@ 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;
     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;
+}
+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;
+}
+interface CacheWarmOptions {
+    concurrency?: number;
+    continueOnError?: 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;
 }
 
-declare class CacheStack {
+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>;
+    set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
+    delete(key: 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;
+    qualify(key: string): string;
+}
+
+declare class CacheStack extends EventEmitter {
     private readonly layers;
     private readonly options;
     private readonly stampedeGuard;
@@ -83,6 +188,12 @@ declare class CacheStack {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly backgroundRefreshes;
+    private readonly accessProfiles;
+    private readonly layerDegradedUntil;
+    private readonly circuitBreakers;
+    private isDisconnecting;
+    private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
     get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
     set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
@@ -90,19 +201,67 @@ declare class CacheStack {
     clear(): 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>;
+    wrap<TArgs extends unknown[], TResult>(prefix: string, fetcher: (...args: TArgs) => Promise<TResult>, options?: CacheWrapOptions<TArgs>): (...args: TArgs) => Promise<TResult | null>;
+    namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
+    getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
+    exportState(): Promise<CacheSnapshotEntry[]>;
+    importState(entries: CacheSnapshotEntry[]): Promise<void>;
+    persistToFile(filePath: string): Promise<void>;
+    restoreFromFile(filePath: string): Promise<void>;
     disconnect(): Promise<void>;
     private initialize;
-    private getFromLayers;
+    private fetchWithGuards;
+    private waitForFreshValue;
+    private fetchAndPopulate;
+    private storeEntry;
+    private readFromLayers;
+    private readLayerEntry;
     private backfill;
-    private setAcrossLayers;
-    private resolveTtl;
+    private writeAcrossLayers;
+    private executeLayerOperations;
+    private resolveFreshTtl;
+    private resolveLayerSeconds;
+    private readLayerNumber;
+    private applyJitter;
+    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 applyAdaptiveTtl;
+    private recordAccess;
+    private incrementMetricMap;
+    private shouldSkipLayer;
+    private handleLayerFailure;
+    private isGracefulDegradationEnabled;
+    private assertCircuitClosed;
+    private recordCircuitFailure;
+    private resetCircuitBreaker;
+    private isNegativeStoredValue;
+    private emitError;
+    private serializeKeyPart;
+    private isCacheSnapshotEntries;
+    private normalizeForSerialization;
 }
 
 declare class PatternMatcher {
@@ -118,9 +277,13 @@ declare class RedisInvalidationBus implements InvalidationBus {
     private readonly channel;
     private readonly publisher;
     private readonly subscriber;
+    private activeListener?;
     constructor(options: RedisInvalidationBusOptions);
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void>>;
     publish(message: InvalidationMessage): Promise<void>;
+    private handleMessage;
+    private isInvalidationMessage;
+    private reportError;
 }
 
 interface RedisTagIndexOptions {
@@ -157,6 +320,55 @@ declare class TagIndex implements CacheTagIndex {
     clear(): Promise<void>;
 }
 
+declare function createCacheStatsHandler(cache: CacheStack): (_request: unknown, response: {
+    setHeader?: (name: string, value: string) => void;
+    end: (body: string) => void;
+    statusCode?: number;
+}) => Promise<void>;
+
+interface CachedMethodDecoratorOptions<TArgs extends unknown[]> extends CacheWrapOptions<TArgs> {
+    cache: (instance: unknown) => CacheStack;
+    prefix?: string;
+}
+declare function createCachedMethodDecorator<TArgs extends unknown[] = unknown[]>(options: CachedMethodDecoratorOptions<TArgs>): MethodDecorator;
+
+interface FastifyLike {
+    decorate: (name: string, value: unknown) => void;
+    get?: (path: string, handler: () => unknown | Promise<unknown>) => void;
+}
+interface FastifyLayercachePluginOptions {
+    exposeStatsRoute?: boolean;
+    statsPath?: string;
+}
+declare function createFastifyLayercachePlugin(cache: CacheStack, options?: FastifyLayercachePluginOptions): (fastify: FastifyLike) => 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 TrpcCacheMiddlewareContext<TInput = unknown, TResult = unknown> {
+    path?: string;
+    type?: string;
+    rawInput?: TInput;
+    next: () => Promise<{
+        ok: boolean;
+        data?: TResult;
+    }>;
+}
+interface TrpcCacheMiddlewareOptions<TInput> extends CacheGetOptions {
+    keyResolver?: (input: TInput, path?: string, type?: string) => string;
+}
+declare function createTrpcCacheMiddleware<TInput = unknown, TResult = unknown>(cache: CacheStack, prefix: string, options?: TrpcCacheMiddlewareOptions<TInput>): (context: TrpcCacheMiddlewareContext<TInput, TResult>) => Promise<{
+    ok: boolean;
+    data?: TResult;
+} | null>;
+
+interface MemoryLayerSnapshotEntry {
+    key: string;
+    value: unknown;
+    expiresAt: number | null;
+}
 interface MemoryLayerOptions {
     ttl?: number;
     maxSize?: number;
@@ -170,15 +382,20 @@ declare class MemoryLayer implements CacheLayer {
     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>;
     delete(key: string): Promise<void>;
     deleteMany(keys: string[]): Promise<void>;
     clear(): Promise<void>;
     keys(): Promise<string[]>;
+    exportState(): MemoryLayerSnapshotEntry[];
+    importState(entries: MemoryLayerSnapshotEntry[]): void;
     private pruneExpired;
     private isExpired;
 }
 
+type CompressionAlgorithm = 'gzip' | 'brotli';
 interface RedisLayerOptions {
     client: Redis;
     ttl?: number;
@@ -187,6 +404,8 @@ interface RedisLayerOptions {
     prefix?: string;
     allowUnprefixedClear?: boolean;
     scanCount?: number;
+    compression?: CompressionAlgorithm;
+    compressionThreshold?: number;
 }
 declare class RedisLayer implements CacheLayer {
     readonly name: string;
@@ -197,8 +416,12 @@ declare class RedisLayer implements CacheLayer {
     private readonly prefix;
     private readonly allowUnprefixedClear;
     private readonly scanCount;
+    private readonly compression?;
+    private readonly compressionThreshold;
     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>>;
     set(key: string, value: unknown, ttl?: number | undefined): Promise<void>;
     delete(key: string): Promise<void>;
     deleteMany(keys: string[]): Promise<void>;
@@ -206,6 +429,10 @@ declare class RedisLayer implements CacheLayer {
     keys(): Promise<string[]>;
     private scanKeys;
     private withPrefix;
+    private deserializeOrDelete;
+    private isSerializablePayload;
+    private encodePayload;
+    private decodePayload;
 }
 
 declare class JsonSerializer implements CacheSerializer {
@@ -218,10 +445,21 @@ declare class MsgpackSerializer implements CacheSerializer {
     deserialize<T>(payload: string | Buffer): T;
 }
 
+interface RedisSingleFlightCoordinatorOptions {
+    client: Redis;
+    prefix?: string;
+}
+declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinator {
+    private readonly client;
+    private readonly prefix;
+    constructor(options: RedisSingleFlightCoordinatorOptions);
+    execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
+}
+
 declare class StampedeGuard {
     private readonly mutexes;
     execute<T>(key: string, task: () => Promise<T>): Promise<T>;
-    private getMutex;
+    private getMutexEntry;
 }
 
-export { type CacheGetOptions, type CacheLayer, type CacheLogger, type CacheMGetEntry, type CacheMSetEntry, type CacheMetricsSnapshot, type CacheSerializer, CacheStack, type CacheStackOptions, type CacheTagIndex, type CacheWriteOptions, type InvalidationBus, type InvalidationMessage, JsonSerializer, type LayerTtlMap, MemoryLayer, MsgpackSerializer, PatternMatcher, RedisInvalidationBus, RedisLayer, RedisTagIndex, StampedeGuard, TagIndex };
+export { type CacheAdaptiveTtlOptions, type CacheCircuitBreakerOptions, type CacheDegradationOptions, type CacheGetOptions, type CacheLayer, type CacheLogger, type CacheMGetEntry, type CacheMSetEntry, type CacheMetricsSnapshot, CacheNamespace, type CacheSerializer, type CacheSingleFlightCoordinator, type CacheSingleFlightExecutionOptions, type CacheSnapshotEntry, CacheStack, type CacheStackOptions, type CacheStatsSnapshot, type CacheTagIndex, type CacheWarmEntry, type CacheWarmOptions, type CacheWrapOptions, type CacheWriteOptions, type InvalidationBus, type InvalidationMessage, JsonSerializer, type LayerTtlMap, MemoryLayer, MsgpackSerializer, PatternMatcher, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, TagIndex, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createFastifyLayercachePlugin, createTrpcCacheMiddleware };