layercache 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,227 @@
+import Redis from 'ioredis';
+
+interface LayerTtlMap {
+    [layerName: string]: number | undefined;
+}
+interface CacheWriteOptions {
+    tags?: string[];
+    ttl?: number | LayerTtlMap;
+}
+interface CacheGetOptions extends CacheWriteOptions {
+}
+interface CacheMGetEntry<T> {
+    key: string;
+    fetch?: () => Promise<T>;
+    options?: CacheGetOptions;
+}
+interface CacheMSetEntry<T> {
+    key: string;
+    value: T;
+    options?: CacheWriteOptions;
+}
+interface CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal?: boolean;
+    get<T>(key: string): Promise<T | null>;
+    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[]>;
+}
+interface CacheSerializer {
+    serialize(value: unknown): string | Buffer;
+    deserialize<T>(payload: string | Buffer): T;
+}
+interface CacheMetricsSnapshot {
+    hits: number;
+    misses: number;
+    fetches: number;
+    sets: number;
+    deletes: number;
+    backfills: number;
+    invalidations: number;
+}
+interface CacheLogger {
+    debug(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[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+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 CacheStackOptions {
+    logger?: CacheLogger | boolean;
+    metrics?: boolean;
+    stampedePrevention?: boolean;
+    invalidationBus?: InvalidationBus;
+    tagIndex?: CacheTagIndex;
+    publishSetInvalidation?: boolean;
+}
+
+declare class CacheStack {
+    private readonly layers;
+    private readonly options;
+    private readonly stampedeGuard;
+    private readonly metrics;
+    private readonly instanceId;
+    private readonly startup;
+    private unsubscribeInvalidation?;
+    private readonly logger;
+    private readonly tagIndex;
+    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>;
+    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>;
+    getMetrics(): CacheMetricsSnapshot;
+    resetMetrics(): void;
+    disconnect(): Promise<void>;
+    private initialize;
+    private getFromLayers;
+    private backfill;
+    private setAcrossLayers;
+    private resolveTtl;
+    private deleteKeys;
+    private publishInvalidation;
+    private handleInvalidationMessage;
+}
+
+declare class PatternMatcher {
+    static matches(pattern: string, value: string): boolean;
+}
+
+interface RedisInvalidationBusOptions {
+    publisher: Redis;
+    subscriber?: Redis;
+    channel?: string;
+}
+declare class RedisInvalidationBus implements InvalidationBus {
+    private readonly channel;
+    private readonly publisher;
+    private readonly subscriber;
+    constructor(options: RedisInvalidationBusOptions);
+    subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void>>;
+    publish(message: InvalidationMessage): Promise<void>;
+}
+
+interface RedisTagIndexOptions {
+    client: Redis;
+    prefix?: string;
+    scanCount?: number;
+}
+declare class RedisTagIndex implements CacheTagIndex {
+    private readonly client;
+    private readonly prefix;
+    private readonly scanCount;
+    constructor(options: RedisTagIndexOptions);
+    touch(key: string): Promise<void>;
+    track(key: string, tags: string[]): Promise<void>;
+    remove(key: string): Promise<void>;
+    keysForTag(tag: string): Promise<string[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+    private scanIndexKeys;
+    private knownKeysKey;
+    private keyTagsKey;
+    private tagKeysKey;
+}
+
+declare class TagIndex implements CacheTagIndex {
+    private readonly tagToKeys;
+    private readonly keyToTags;
+    private readonly knownKeys;
+    touch(key: string): Promise<void>;
+    track(key: string, tags: string[]): Promise<void>;
+    remove(key: string): Promise<void>;
+    keysForTag(tag: string): Promise<string[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+
+interface MemoryLayerOptions {
+    ttl?: number;
+    maxSize?: number;
+    name?: string;
+}
+declare class MemoryLayer implements CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal = true;
+    private readonly maxSize;
+    private readonly entries;
+    constructor(options?: MemoryLayerOptions);
+    get<T>(key: string): Promise<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[]>;
+    private pruneExpired;
+    private isExpired;
+}
+
+interface RedisLayerOptions {
+    client: Redis;
+    ttl?: number;
+    name?: string;
+    serializer?: CacheSerializer;
+    prefix?: string;
+    allowUnprefixedClear?: boolean;
+    scanCount?: number;
+}
+declare class RedisLayer implements CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal = false;
+    private readonly client;
+    private readonly serializer;
+    private readonly prefix;
+    private readonly allowUnprefixedClear;
+    private readonly scanCount;
+    constructor(options: RedisLayerOptions);
+    get<T>(key: string): Promise<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[]>;
+    private scanKeys;
+    private withPrefix;
+}
+
+declare class JsonSerializer implements CacheSerializer {
+    serialize(value: unknown): string;
+    deserialize<T>(payload: string | Buffer): T;
+}
+
+declare class MsgpackSerializer implements CacheSerializer {
+    serialize(value: unknown): Buffer;
+    deserialize<T>(payload: string | Buffer): 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 };

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+import Redis from 'ioredis';
+
+interface LayerTtlMap {
+    [layerName: string]: number | undefined;
+}
+interface CacheWriteOptions {
+    tags?: string[];
+    ttl?: number | LayerTtlMap;
+}
+interface CacheGetOptions extends CacheWriteOptions {
+}
+interface CacheMGetEntry<T> {
+    key: string;
+    fetch?: () => Promise<T>;
+    options?: CacheGetOptions;
+}
+interface CacheMSetEntry<T> {
+    key: string;
+    value: T;
+    options?: CacheWriteOptions;
+}
+interface CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal?: boolean;
+    get<T>(key: string): Promise<T | null>;
+    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[]>;
+}
+interface CacheSerializer {
+    serialize(value: unknown): string | Buffer;
+    deserialize<T>(payload: string | Buffer): T;
+}
+interface CacheMetricsSnapshot {
+    hits: number;
+    misses: number;
+    fetches: number;
+    sets: number;
+    deletes: number;
+    backfills: number;
+    invalidations: number;
+}
+interface CacheLogger {
+    debug(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[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+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 CacheStackOptions {
+    logger?: CacheLogger | boolean;
+    metrics?: boolean;
+    stampedePrevention?: boolean;
+    invalidationBus?: InvalidationBus;
+    tagIndex?: CacheTagIndex;
+    publishSetInvalidation?: boolean;
+}
+
+declare class CacheStack {
+    private readonly layers;
+    private readonly options;
+    private readonly stampedeGuard;
+    private readonly metrics;
+    private readonly instanceId;
+    private readonly startup;
+    private unsubscribeInvalidation?;
+    private readonly logger;
+    private readonly tagIndex;
+    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>;
+    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>;
+    getMetrics(): CacheMetricsSnapshot;
+    resetMetrics(): void;
+    disconnect(): Promise<void>;
+    private initialize;
+    private getFromLayers;
+    private backfill;
+    private setAcrossLayers;
+    private resolveTtl;
+    private deleteKeys;
+    private publishInvalidation;
+    private handleInvalidationMessage;
+}
+
+declare class PatternMatcher {
+    static matches(pattern: string, value: string): boolean;
+}
+
+interface RedisInvalidationBusOptions {
+    publisher: Redis;
+    subscriber?: Redis;
+    channel?: string;
+}
+declare class RedisInvalidationBus implements InvalidationBus {
+    private readonly channel;
+    private readonly publisher;
+    private readonly subscriber;
+    constructor(options: RedisInvalidationBusOptions);
+    subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void>>;
+    publish(message: InvalidationMessage): Promise<void>;
+}
+
+interface RedisTagIndexOptions {
+    client: Redis;
+    prefix?: string;
+    scanCount?: number;
+}
+declare class RedisTagIndex implements CacheTagIndex {
+    private readonly client;
+    private readonly prefix;
+    private readonly scanCount;
+    constructor(options: RedisTagIndexOptions);
+    touch(key: string): Promise<void>;
+    track(key: string, tags: string[]): Promise<void>;
+    remove(key: string): Promise<void>;
+    keysForTag(tag: string): Promise<string[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+    private scanIndexKeys;
+    private knownKeysKey;
+    private keyTagsKey;
+    private tagKeysKey;
+}
+
+declare class TagIndex implements CacheTagIndex {
+    private readonly tagToKeys;
+    private readonly keyToTags;
+    private readonly knownKeys;
+    touch(key: string): Promise<void>;
+    track(key: string, tags: string[]): Promise<void>;
+    remove(key: string): Promise<void>;
+    keysForTag(tag: string): Promise<string[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+
+interface MemoryLayerOptions {
+    ttl?: number;
+    maxSize?: number;
+    name?: string;
+}
+declare class MemoryLayer implements CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal = true;
+    private readonly maxSize;
+    private readonly entries;
+    constructor(options?: MemoryLayerOptions);
+    get<T>(key: string): Promise<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[]>;
+    private pruneExpired;
+    private isExpired;
+}
+
+interface RedisLayerOptions {
+    client: Redis;
+    ttl?: number;
+    name?: string;
+    serializer?: CacheSerializer;
+    prefix?: string;
+    allowUnprefixedClear?: boolean;
+    scanCount?: number;
+}
+declare class RedisLayer implements CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal = false;
+    private readonly client;
+    private readonly serializer;
+    private readonly prefix;
+    private readonly allowUnprefixedClear;
+    private readonly scanCount;
+    constructor(options: RedisLayerOptions);
+    get<T>(key: string): Promise<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[]>;
+    private scanKeys;
+    private withPrefix;
+}
+
+declare class JsonSerializer implements CacheSerializer {
+    serialize(value: unknown): string;
+    deserialize<T>(payload: string | Buffer): T;
+}
+
+declare class MsgpackSerializer implements CacheSerializer {
+    serialize(value: unknown): Buffer;
+    deserialize<T>(payload: string | Buffer): 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 };