layercache 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -6,6 +6,11 @@ interface LayerTtlMap {
 interface CacheWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
+    negativeCache?: boolean;
+    negativeTtl?: number | LayerTtlMap;
+    staleWhileRevalidate?: number | LayerTtlMap;
+    staleIfError?: number | LayerTtlMap;
+    ttlJitter?: number | LayerTtlMap;
 }
 interface CacheGetOptions extends CacheWriteOptions {
 }
@@ -24,6 +29,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,6 +49,11 @@ interface CacheMetricsSnapshot {
     deletes: number;
     backfills: number;
     invalidations: number;
+    staleHits: number;
+    refreshes: number;
+    refreshErrors: number;
+    writeFailures: number;
+    singleFlightWaits: number;
 }
 interface CacheLogger {
     debug(message: string, context?: Record<string, unknown>): void;
@@ -64,6 +76,14 @@ 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;
@@ -71,6 +91,16 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     publishSetInvalidation?: boolean;
+    negativeCaching?: boolean;
+    negativeTtl?: number | LayerTtlMap;
+    staleWhileRevalidate?: number | LayerTtlMap;
+    staleIfError?: number | LayerTtlMap;
+    ttlJitter?: number | LayerTtlMap;
+    writePolicy?: 'strict' | 'best-effort';
+    singleFlightCoordinator?: CacheSingleFlightCoordinator;
+    singleFlightLeaseMs?: number;
+    singleFlightTimeoutMs?: number;
+    singleFlightPollMs?: number;
 }
 
 declare class CacheStack {
@@ -83,6 +113,7 @@ declare class CacheStack {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly backgroundRefreshes;
     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>;
@@ -96,13 +127,27 @@ declare class CacheStack {
     resetMetrics(): 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;
 }
 
 declare class PatternMatcher {
@@ -170,6 +215,8 @@ 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>;
@@ -199,6 +246,8 @@ declare class RedisLayer implements CacheLayer {
     private readonly scanCount;
     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>;
@@ -218,10 +267,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;
 }
 
-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 CacheGetOptions, type CacheLayer, type CacheLogger, type CacheMGetEntry, type CacheMSetEntry, type CacheMetricsSnapshot, type CacheSerializer, type CacheSingleFlightCoordinator, type CacheSingleFlightExecutionOptions, CacheStack, type CacheStackOptions, type CacheTagIndex, type CacheWriteOptions, type InvalidationBus, type InvalidationMessage, JsonSerializer, type LayerTtlMap, MemoryLayer, MsgpackSerializer, PatternMatcher, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, TagIndex };

package/dist/index.d.ts

@@ -6,6 +6,11 @@ interface LayerTtlMap {
 interface CacheWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
+    negativeCache?: boolean;
+    negativeTtl?: number | LayerTtlMap;
+    staleWhileRevalidate?: number | LayerTtlMap;
+    staleIfError?: number | LayerTtlMap;
+    ttlJitter?: number | LayerTtlMap;
 }
 interface CacheGetOptions extends CacheWriteOptions {
 }
@@ -24,6 +29,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,6 +49,11 @@ interface CacheMetricsSnapshot {
     deletes: number;
     backfills: number;
     invalidations: number;
+    staleHits: number;
+    refreshes: number;
+    refreshErrors: number;
+    writeFailures: number;
+    singleFlightWaits: number;
 }
 interface CacheLogger {
     debug(message: string, context?: Record<string, unknown>): void;
@@ -64,6 +76,14 @@ 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;
@@ -71,6 +91,16 @@ interface CacheStackOptions {
     invalidationBus?: InvalidationBus;
     tagIndex?: CacheTagIndex;
     publishSetInvalidation?: boolean;
+    negativeCaching?: boolean;
+    negativeTtl?: number | LayerTtlMap;
+    staleWhileRevalidate?: number | LayerTtlMap;
+    staleIfError?: number | LayerTtlMap;
+    ttlJitter?: number | LayerTtlMap;
+    writePolicy?: 'strict' | 'best-effort';
+    singleFlightCoordinator?: CacheSingleFlightCoordinator;
+    singleFlightLeaseMs?: number;
+    singleFlightTimeoutMs?: number;
+    singleFlightPollMs?: number;
 }
 
 declare class CacheStack {
@@ -83,6 +113,7 @@ declare class CacheStack {
     private unsubscribeInvalidation?;
     private readonly logger;
     private readonly tagIndex;
+    private readonly backgroundRefreshes;
     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>;
@@ -96,13 +127,27 @@ declare class CacheStack {
     resetMetrics(): 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;
 }
 
 declare class PatternMatcher {
@@ -170,6 +215,8 @@ 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>;
@@ -199,6 +246,8 @@ declare class RedisLayer implements CacheLayer {
     private readonly scanCount;
     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>;
@@ -218,10 +267,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;
 }
 
-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 CacheGetOptions, type CacheLayer, type CacheLogger, type CacheMGetEntry, type CacheMSetEntry, type CacheMetricsSnapshot, type CacheSerializer, type CacheSingleFlightCoordinator, type CacheSingleFlightExecutionOptions, CacheStack, type CacheStackOptions, type CacheTagIndex, type CacheWriteOptions, type InvalidationBus, type InvalidationMessage, JsonSerializer, type LayerTtlMap, MemoryLayer, MsgpackSerializer, PatternMatcher, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, TagIndex };