@nestjs-redisx/cache 1.0.0

package/dist/stampede/infrastructure/stampede-protection.service.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Anti-stampede protection using local singleflight + distributed Redis lock.
+ *
+ * Two layers of protection:
+ * 1. Local singleflight — coalesces concurrent requests within the same process
+ * 2. Distributed lock — prevents duplicate loading across multiple instances
+ */
+import { IRedisDriver } from '@nestjs-redisx/core';
+import { ICachePluginOptions, IStampedeResult, IStampedeStats } from '../../shared/types';
+import { IStampedeProtection } from '../application/ports/stampede-protection.port';
+export declare class StampedeProtectionService implements IStampedeProtection {
+    private readonly options;
+    private readonly driver;
+    private readonly logger;
+    private readonly flights;
+    private readonly lockTimeout;
+    private readonly waitTimeout;
+    private prevented;
+    constructor(options: ICachePluginOptions, driver: IRedisDriver);
+    protect<T>(key: string, loader: () => Promise<T>): Promise<IStampedeResult<T>>;
+    clearKey(key: string): Promise<void>;
+    clearAll(): Promise<void>;
+    getStats(): IStampedeStats;
+    private waitForFlight;
+    private executeLoader;
+    private tryAcquireLock;
+    private releaseLock;
+    private generateLockValue;
+}
+//# sourceMappingURL=stampede-protection.service.d.ts.map

package/dist/stampede/infrastructure/stampede-protection.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stampede-protection.service.d.ts","sourceRoot":"","sources":["../../../src/stampede/infrastructure/stampede-protection.service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAgB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIjE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAyBpF,qBACa,yBAA0B,YAAW,mBAAmB;IASjE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,SAAS,CAAK;gBAIH,OAAO,EAAE,mBAAmB,EAE5B,MAAM,EAAE,YAAY;IAMjC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IA2E9E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASpC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAO/B,QAAQ,IAAI,cAAc;YAsBZ,aAAa;YA4Bb,aAAa;YA6Bb,cAAc;YAUd,WAAW;IAQzB,OAAO,CAAC,iBAAiB;CAG1B"}

package/dist/strategies/eviction-strategy.interface.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Eviction strategy interface for cache management.
+ * Defines how items should be evicted when cache reaches capacity.
+ */
+export interface IEvictionStrategy<K = string, _V = unknown> {
+    /**
+     * Records access to a key (for LRU, etc.)
+     *
+     * @param key - Cache key that was accessed
+     */
+    recordAccess(key: K): void;
+    /**
+     * Records insertion of a new key
+     *
+     * @param key - Cache key that was inserted
+     */
+    recordInsert(key: K): void;
+    /**
+     * Records deletion of a key
+     *
+     * @param key - Cache key that was deleted
+     */
+    recordDelete(key: K): void;
+    /**
+     * Selects key to evict based on strategy
+     *
+     * @returns Key to evict, or undefined if no candidates
+     */
+    selectVictim(): K | undefined;
+    /**
+     * Clears all tracking data
+     */
+    clear(): void;
+    /**
+     * Gets current size of tracked keys
+     */
+    size(): number;
+}
+//# sourceMappingURL=eviction-strategy.interface.d.ts.map

package/dist/strategies/eviction-strategy.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eviction-strategy.interface.d.ts","sourceRoot":"","sources":["../../src/strategies/eviction-strategy.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO;IACzD;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;OAIG;IACH,YAAY,IAAI,CAAC,GAAG,SAAS,CAAC;IAE9B;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;CAChB"}

package/dist/strategies/fifo.strategy.d.ts

@@ -0,0 +1,86 @@
+/**
+ * First In First Out (FIFO) eviction strategy.
+ *
+ * Evicts the oldest inserted item when cache is full.
+ * Does not consider access patterns - only insertion order matters.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new FifoStrategy<string>();
+ *
+ * strategy.recordInsert('key1');
+ * strategy.recordInsert('key2');
+ * strategy.recordAccess('key1'); // Access doesn't affect order in FIFO
+ *
+ * const victim = strategy.selectVictim(); // Returns 'key1' (first inserted)
+ * ```
+ */
+import { IEvictionStrategy } from './eviction-strategy.interface';
+export declare class FifoStrategy<K = string> implements IEvictionStrategy<K> {
+    /**
+     * Queue maintaining keys in insertion order.
+     * First element is oldest (next to evict).
+     */
+    private readonly queue;
+    /**
+     * Set for O(1) existence checks
+     */
+    private readonly keySet;
+    constructor();
+    /**
+     * Records access to a key.
+     * In FIFO, access doesn't affect eviction order, so this is a no-op.
+     *
+     * @param _key - Key that was accessed
+     */
+    recordAccess(_key: K): void;
+    /**
+     * Records insertion of a new key.
+     *
+     * @param key - Key that was inserted
+     */
+    recordInsert(key: K): void;
+    /**
+     * Records deletion of a key.
+     *
+     * @param key - Key that was deleted
+     */
+    recordDelete(key: K): void;
+    /**
+     * Selects the oldest inserted key for eviction.
+     *
+     * @returns Oldest key (first in queue), or undefined if empty
+     */
+    selectVictim(): K | undefined;
+    /**
+     * Clears all tracking data.
+     */
+    clear(): void;
+    /**
+     * Gets current number of tracked keys.
+     *
+     * @returns Number of keys
+     */
+    size(): number;
+    /**
+     * Gets all keys in FIFO order (oldest to newest).
+     *
+     * @returns Array of keys in insertion order
+     */
+    getKeys(): K[];
+    /**
+     * Gets keys that should be evicted to reach target size.
+     *
+     * @param targetSize - Desired size after eviction
+     * @returns Array of keys to evict (oldest first)
+     */
+    getVictims(targetSize: number): K[];
+    /**
+     * Checks if a key is tracked.
+     *
+     * @param key - Key to check
+     * @returns True if key is tracked
+     */
+    has(key: K): boolean;
+}
+//# sourceMappingURL=fifo.strategy.d.ts.map

package/dist/strategies/fifo.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fifo.strategy.d.ts","sourceRoot":"","sources":["../../src/strategies/fifo.strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE,qBAAa,YAAY,CAAC,CAAC,GAAG,MAAM,CAAE,YAAW,iBAAiB,CAAC,CAAC,CAAC;IACnE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAM;IAE5B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;;IAOhC;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAK3B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAQ1B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAW1B;;;;OAIG;IACH,YAAY,IAAI,CAAC,GAAG,SAAS;IAI7B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,OAAO,IAAI,CAAC,EAAE;IAId;;;;;OAKG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,EAAE;IAUnC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;CAGrB"}

package/dist/strategies/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cache eviction strategies.
+ *
+ * @example
+ * ```typescript
+ * import { LruStrategy, FifoStrategy } from '@nestjs-redisx/cache';
+ *
+ * const lru = new LruStrategy<string>();
+ * lru.recordInsert('key1');
+ * lru.recordInsert('key2');
+ * lru.recordAccess('key1');
+ * const victim = lru.selectVictim(); // Returns 'key2'
+ * ```
+ */
+export type { IEvictionStrategy } from './eviction-strategy.interface';
+export { LruStrategy } from './lru.strategy';
+export { FifoStrategy } from './fifo.strategy';
+export { LfuStrategy } from './lfu.strategy';
+//# sourceMappingURL=index.d.ts.map

package/dist/strategies/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/strategies/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/strategies/lfu.strategy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Least Frequently Used (LFU) eviction strategy.
+ *
+ * Evicts the least frequently accessed item when cache is full.
+ * Tracks access frequency for each key, with insertion order as tiebreaker.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new LfuStrategy<string>();
+ *
+ * strategy.recordInsert('key1');
+ * strategy.recordInsert('key2');
+ * strategy.recordAccess('key1'); // key1 frequency = 2
+ * strategy.recordAccess('key1'); // key1 frequency = 3
+ *
+ * const victim = strategy.selectVictim(); // Returns 'key2' (frequency = 1)
+ * ```
+ */
+import { IEvictionStrategy } from './eviction-strategy.interface';
+export declare class LfuStrategy<K = string> implements IEvictionStrategy<K> {
+    private readonly entries;
+    private insertCounter;
+    constructor();
+    /**
+     * Records access to a key, incrementing its frequency counter.
+     *
+     * @param key - Key that was accessed
+     */
+    recordAccess(key: K): void;
+    /**
+     * Records insertion of a new key with initial frequency of 1.
+     *
+     * @param key - Key that was inserted
+     */
+    recordInsert(key: K): void;
+    /**
+     * Records deletion of a key.
+     *
+     * @param key - Key that was deleted
+     */
+    recordDelete(key: K): void;
+    /**
+     * Selects the least frequently used key for eviction.
+     * When frequencies are equal, the oldest inserted key is selected.
+     *
+     * @returns Least frequently used key, or undefined if empty
+     */
+    selectVictim(): K | undefined;
+    /**
+     * Clears all tracking data.
+     */
+    clear(): void;
+    /**
+     * Gets current number of tracked keys.
+     *
+     * @returns Number of keys
+     */
+    size(): number;
+    /**
+     * Gets all keys sorted by frequency (lowest first), then by insertion order.
+     *
+     * @returns Array of keys sorted by eviction priority
+     */
+    getKeys(): K[];
+    /**
+     * Gets keys that should be evicted to reach target size.
+     *
+     * @param targetSize - Desired size after eviction
+     * @returns Array of keys to evict
+     */
+    getVictims(targetSize: number): K[];
+    /**
+     * Checks if a key is tracked.
+     *
+     * @param key - Key to check
+     * @returns True if key is tracked
+     */
+    has(key: K): boolean;
+    /**
+     * Gets the frequency count for a key.
+     *
+     * @param key - Key to check
+     * @returns Frequency count, or 0 if key not tracked
+     */
+    getFrequency(key: K): number;
+}
+//# sourceMappingURL=lfu.strategy.d.ts.map

package/dist/strategies/lfu.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lfu.strategy.d.ts","sourceRoot":"","sources":["../../src/strategies/lfu.strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAQlE,qBAAa,WAAW,CAAC,CAAC,GAAG,MAAM,CAAE,YAAW,iBAAiB,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,aAAa,CAAS;;IAO9B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAO1B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAW1B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAI1B;;;;;OAKG;IACH,YAAY,IAAI,CAAC,GAAG,SAAS;IAgB7B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,OAAO,IAAI,CAAC,EAAE;IAMd;;;;;OAKG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,EAAE;IAWnC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM;CAG7B"}

package/dist/strategies/lru.strategy.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Least Recently Used (LRU) eviction strategy.
+ *
+ * Evicts the least recently accessed item when cache is full.
+ * Uses a Map to maintain insertion order and updates order on access.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new LruStrategy<string>();
+ *
+ * strategy.recordInsert('key1');
+ * strategy.recordInsert('key2');
+ * strategy.recordAccess('key1'); // key1 is now most recent
+ *
+ * const victim = strategy.selectVictim(); // Returns 'key2' (least recent)
+ * ```
+ */
+import { IEvictionStrategy } from './eviction-strategy.interface';
+export declare class LruStrategy<K = string> implements IEvictionStrategy<K> {
+    /**
+     * Map maintaining keys in LRU order.
+     * JavaScript Map maintains insertion order, so we use delete+set to move to end.
+     */
+    private readonly keyOrder;
+    /**
+     * Timestamp counter for tracking access order
+     */
+    private timestamp;
+    constructor();
+    /**
+     * Records access to a key, moving it to most recently used position.
+     *
+     * @param key - Key that was accessed
+     */
+    recordAccess(key: K): void;
+    /**
+     * Records insertion of a new key.
+     *
+     * @param key - Key that was inserted
+     */
+    recordInsert(key: K): void;
+    /**
+     * Records deletion of a key.
+     *
+     * @param key - Key that was deleted
+     */
+    recordDelete(key: K): void;
+    /**
+     * Selects the least recently used key for eviction.
+     *
+     * @returns Least recently used key, or undefined if empty
+     */
+    selectVictim(): K | undefined;
+    /**
+     * Clears all tracking data.
+     */
+    clear(): void;
+    /**
+     * Gets current number of tracked keys.
+     *
+     * @returns Number of keys
+     */
+    size(): number;
+    /**
+     * Gets all keys in LRU order (oldest to newest).
+     *
+     * @returns Array of keys sorted by access time
+     */
+    getKeys(): K[];
+    /**
+     * Gets keys that should be evicted to reach target size.
+     *
+     * @param targetSize - Desired size after eviction
+     * @returns Array of keys to evict
+     */
+    getVictims(targetSize: number): K[];
+}
+//# sourceMappingURL=lru.strategy.d.ts.map

package/dist/strategies/lru.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.strategy.d.ts","sourceRoot":"","sources":["../../src/strategies/lru.strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE,qBAAa,WAAW,CAAC,CAAC,GAAG,MAAM,CAAE,YAAW,iBAAiB,CAAC,CAAC,CAAC;IAClE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;;IAO1B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAM1B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAK1B;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAI1B;;;;OAIG;IACH,YAAY,IAAI,CAAC,GAAG,SAAS;IAmB7B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,OAAO,IAAI,CAAC,EAAE;IAMd;;;;;OAKG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,EAAE;CAUpC"}

package/dist/swr/application/ports/swr-manager.port.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Stale-While-Revalidate manager interface.
+ */
+import { SwrEntry } from '../../../shared/types';
+export interface ISwrManager {
+    /**
+     * Gets value from SWR cache.
+     * Returns value with staleness flag.
+     *
+     * @param key - Cache key
+     * @returns SWR entry or null if not found
+     */
+    get<T>(key: string): Promise<SwrEntry<T> | null>;
+    /**
+     * Sets value in SWR cache with metadata.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param staleTimeSeconds - Time after which value is stale
+     */
+    set<T>(key: string, value: T, staleTimeSeconds: number): Promise<void>;
+    /**
+     * Deletes SWR entry.
+     *
+     * @param key - Cache key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Checks if an entry is stale (past staleAt timestamp).
+     *
+     * @param entry - SWR entry to check
+     * @returns True if entry is stale
+     */
+    isStale<T>(entry: SwrEntry<T>): boolean;
+    /**
+     * Checks if an entry has expired completely (past expiresAt timestamp).
+     *
+     * @param entry - SWR entry to check
+     * @returns True if entry has expired
+     */
+    isExpired<T>(entry: SwrEntry<T>): boolean;
+    /**
+     * Schedules background revalidation for a key.
+     *
+     * @param key - Cache key
+     * @param loader - Function to load fresh value
+     * @param onSuccess - Callback when revalidation succeeds
+     * @param onError - Optional callback when revalidation fails
+     */
+    scheduleRevalidation<T>(key: string, loader: () => Promise<T>, onSuccess: (value: T) => Promise<void>, onError?: (error: Error) => void): Promise<void>;
+    /**
+     * Checks if revalidation can be started for a key.
+     * Returns false if revalidation is already in progress.
+     *
+     * @param key - Cache key
+     * @returns True if revalidation can proceed
+     */
+    shouldRevalidate(key: string): boolean;
+    /**
+     * Creates an SWR entry with metadata.
+     *
+     * @param value - Value to cache
+     * @param freshTtl - Time in seconds until value becomes stale
+     * @param staleTtl - Optional time in seconds for stale period (defaults to config)
+     * @returns SWR entry with timestamps
+     */
+    createSwrEntry<T>(value: T, freshTtl: number, staleTtl?: number): SwrEntry<T>;
+    /**
+     * Gets SWR manager statistics.
+     *
+     * @returns Stats object with active revalidations count
+     */
+    getStats(): {
+        activeRevalidations: number;
+        enabled: boolean;
+        staleTtl: number;
+    };
+    /**
+     * Clears all pending revalidations.
+     */
+    clearRevalidations(): Promise<void>;
+}
+//# sourceMappingURL=swr-manager.port.d.ts.map

package/dist/swr/application/ports/swr-manager.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swr-manager.port.d.ts","sourceRoot":"","sources":["../../../../src/swr/application/ports/swr-manager.port.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAExC;;;;;OAKG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAE1C;;;;;;;OAOG;IACH,oBAAoB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExJ;;;;;;OAMG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAEvC;;;;;;;OAOG;IACH,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE9E;;;;OAIG;IACH,QAAQ,IAAI;QACV,mBAAmB,EAAE,MAAM,CAAC;QAC5B,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC"}

package/dist/swr/infrastructure/swr-manager.service.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Stale-While-Revalidate manager.
+ * Serves stale data while revalidating in the background.
+ */
+import { ICachePluginOptions, SwrEntry } from '../../shared/types';
+import { ISwrManager } from '../application/ports/swr-manager.port';
+export declare class SwrManagerService implements ISwrManager {
+    private readonly options;
+    private readonly logger;
+    private readonly jobs;
+    private readonly staleTtl;
+    private readonly enabled;
+    constructor(options: ICachePluginOptions);
+    get<T>(_key: string): Promise<SwrEntry<T> | null>;
+    set<T>(_key: string, _value: T, _staleTimeSeconds: number): Promise<void>;
+    delete(_key: string): Promise<void>;
+    isStale<T>(entry: SwrEntry<T>): boolean;
+    isExpired<T>(entry: SwrEntry<T>): boolean;
+    shouldRevalidate(key: string): boolean;
+    scheduleRevalidation<T>(key: string, loader: () => Promise<T>, onSuccess: (value: T) => Promise<void>, onError?: (error: Error) => void): Promise<void>;
+    createSwrEntry<T>(value: T, freshTtl: number, staleTtl?: number): SwrEntry<T>;
+    getStats(): {
+        activeRevalidations: number;
+        enabled: boolean;
+        staleTtl: number;
+    };
+    clearRevalidations(): Promise<void>;
+    private executeRevalidation;
+}
+//# sourceMappingURL=swr-manager.service.d.ts.map

package/dist/swr/infrastructure/swr-manager.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swr-manager.service.d.ts","sourceRoot":"","sources":["../../../src/swr/infrastructure/swr-manager.service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAUpE,qBACa,iBAAkB,YAAW,WAAW;IAQjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgD;IACrE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAIf,OAAO,EAAE,mBAAmB;IAOzC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAMjD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO;IASvC,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO;IAKzC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAMhC,oBAAoB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB7J,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC;IAa7E,QAAQ;;;;;IASF,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;YAI3B,mBAAmB;CAgBlC"}

package/dist/tags/application/ports/tag-index.port.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Tag index repository interface.
+ */
+export interface ITagIndex {
+    /**
+     * Adds cache key to tag indexes.
+     *
+     * @param key - Cache key (with full prefix)
+     * @param tags - Array of tags
+     */
+    addKeyToTags(key: string, tags: string[]): Promise<void>;
+    /**
+     * Removes cache key from specified tag indexes.
+     *
+     * @param key - Cache key
+     * @param tags - Tags to remove the key from
+     */
+    removeKeyFromTags(key: string, tags: string[]): Promise<void>;
+    /**
+     * Gets all cache keys associated with a tag.
+     *
+     * @param tag - Tag name
+     * @returns Array of cache keys
+     */
+    getKeysByTag(tag: string): Promise<string[]>;
+    /**
+     * Invalidates tag - deletes all associated cache keys and the tag index.
+     *
+     * @param tag - Tag name
+     * @returns Number of keys deleted
+     */
+    invalidateTag(tag: string): Promise<number>;
+    /**
+     * Invalidates multiple tags.
+     *
+     * @param tags - Array of tag names
+     * @returns Total number of keys deleted
+     */
+    invalidateTags(tags: string[]): Promise<number>;
+    /**
+     * Clears all tag indexes.
+     */
+    clearAllTags(): Promise<void>;
+    /**
+     * Gets statistics for a specific tag.
+     *
+     * @param tag - Tag name
+     * @returns Object with key count and existence flag
+     */
+    getTagStats(tag: string): Promise<{
+        keyCount: number;
+        exists: boolean;
+    }>;
+}
+//# sourceMappingURL=tag-index.port.d.ts.map

package/dist/tags/application/ports/tag-index.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-index.port.d.ts","sourceRoot":"","sources":["../../../../src/tags/application/ports/tag-index.port.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;;;OAKG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhD;;OAEG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC1E"}

package/dist/tags/infrastructure/repositories/tag-index.repository.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tag index repository for tag-based cache invalidation.
+ * Maintains mapping of tags to cache keys.
+ */
+import { IRedisDriver } from '@nestjs-redisx/core';
+import { ICachePluginOptions } from '../../../shared/types';
+import { ITagIndex } from '../../application/ports/tag-index.port';
+import { LuaScriptLoader } from '../services/lua-script-loader.service';
+export declare class TagIndexRepository implements ITagIndex {
+    private readonly driver;
+    private readonly options;
+    private readonly luaLoader;
+    private readonly tagPrefix;
+    constructor(driver: IRedisDriver, options: ICachePluginOptions, luaLoader: LuaScriptLoader);
+    addKeyToTags(key: string, tags: string[]): Promise<void>;
+    removeKeyFromTags(key: string, tags: string[]): Promise<void>;
+    getKeysByTag(tag: string): Promise<string[]>;
+    invalidateTag(tag: string): Promise<number>;
+    invalidateTags(tags: string[]): Promise<number>;
+    clearAllTags(): Promise<void>;
+    getTagStats(tag: string): Promise<{
+        keyCount: number;
+        exists: boolean;
+    }>;
+    /**
+     * Validates tags using Tags value object.
+     *
+     * @param tags - Array of tag strings
+     * @returns Array of validated tag strings
+     * @throws CacheError if validation fails
+     * @private
+     */
+    private validateTags;
+    private buildTagKey;
+    private scanKeys;
+}
+//# sourceMappingURL=tag-index.repository.d.ts.map

package/dist/tags/infrastructure/repositories/tag-index.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-index.repository.d.ts","sourceRoot":"","sources":["../../../../src/tags/infrastructure/repositories/tag-index.repository.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAgB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAKxE,qBACa,kBAAmB,YAAW,SAAS;IAI1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IALvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGM,MAAM,EAAE,YAAY,EACZ,OAAO,EAAE,mBAAmB,EAC/B,SAAS,EAAE,eAAe;IAQlE,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BxD,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB7D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAY5C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC3C,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAsB/C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB7B,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAc9E;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;YAIL,QAAQ;CAevB"}

package/dist/tags/infrastructure/scripts/lua-scripts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Inline Lua scripts for tag-based cache invalidation.
+ *
+ * Scripts are stored as inline strings to avoid issues with file reading
+ * after build (dist directory doesn't contain .lua files).
+ */
+/**
+ * Atomically adds a cache key to multiple tag sets.
+ *
+ * KEYS[1..N] = tag set keys
+ * ARGV[1] = cache key to add
+ * ARGV[2] = TTL for tag sets in seconds
+ *
+ * Returns: number of tag sets updated
+ */
+export declare const ADD_KEY_TO_TAGS_SCRIPT: string;
+/**
+ * Atomically invalidates all cache keys for a tag.
+ *
+ * KEYS[1] = tag set key (e.g., "cache:_tag:users")
+ *
+ * Returns: number of deleted cache keys
+ */
+export declare const INVALIDATE_TAG_SCRIPT: string;
+//# sourceMappingURL=lua-scripts.d.ts.map

package/dist/tags/infrastructure/scripts/lua-scripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lua-scripts.d.ts","sourceRoot":"","sources":["../../../../src/tags/infrastructure/scripts/lua-scripts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAW3B,CAAC;AAET;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAuB1B,CAAC"}

package/dist/tags/infrastructure/services/lua-script-loader.service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Lua script loader service.
+ * Loads inline Lua scripts and registers them with Redis.
+ *
+ * Scripts are stored as inline strings to avoid issues with file reading
+ * after build (dist directory doesn't contain .lua files).
+ */
+import { OnModuleInit } from '@nestjs/common';
+import { IRedisDriver } from '@nestjs-redisx/core';
+export declare class LuaScriptLoader implements OnModuleInit {
+    private readonly driver;
+    private readonly logger;
+    private readonly scriptShas;
+    constructor(driver: IRedisDriver);
+    onModuleInit(): Promise<void>;
+    /**
+     * Loads all Lua scripts into Redis.
+     */
+    private loadScripts;
+    /**
+     * Executes a Lua script by name using EVALSHA.
+     *
+     * @param scriptName - Name of the script
+     * @param keys - Redis keys to pass to the script
+     * @param args - Arguments to pass to the script
+     * @returns Script execution result
+     */
+    evalSha(scriptName: string, keys: string[], args: (string | number)[]): Promise<unknown>;
+    /**
+     * Gets the SHA hash of a loaded script.
+     *
+     * @param scriptName - Name of the script
+     * @returns SHA hash or undefined if not loaded
+     */
+    getSha(scriptName: string): string | undefined;
+    /**
+     * Checks if a script is loaded.
+     *
+     * @param scriptName - Name of the script
+     * @returns True if script is loaded
+     */
+    isLoaded(scriptName: string): boolean;
+}
+//# sourceMappingURL=lua-script-loader.service.d.ts.map