@fjell/cache 4.7.40 → 4.7.41

package/dist/cache/patterns/StaleWhileRevalidateCache.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Stale-While-Revalidate Cache Pattern
+ *
+ * Returns cached data immediately (even if stale) while fetching fresh data
+ * in the background. This keeps the UI responsive while ensuring eventual
+ * data freshness.
+ */
+import { TTLCalculator } from '../../ttl/TTLCalculator.js';
+import { ItemCache } from '../layers/ItemCache.js';
+import { CachedItem } from '../types/TwoLayerTypes.js';
+export interface StaleWhileRevalidateOptions {
+    /** TTL calculator for determining staleness */
+    ttlCalculator: TTLCalculator;
+    /** Maximum number of concurrent background refreshes */
+    maxConcurrentRefreshes?: number;
+    /** How long to wait before giving up on a refresh (milliseconds) */
+    refreshTimeout?: number;
+    /** Whether to extend TTL on refresh failures */
+    extendTTLOnError?: boolean;
+    /** Error TTL extension duration (seconds) */
+    errorTTLExtension?: number;
+}
+export interface RefreshContext<T> {
+    /** The cached item being refreshed */
+    cachedItem: CachedItem<T>;
+    /** Original TTL for this item */
+    originalTTL: number;
+    /** When the refresh started */
+    refreshStartedAt: Date;
+}
+/**
+ * Cache that implements the stale-while-revalidate pattern
+ */
+export declare class StaleWhileRevalidateCache<T> {
+    private itemCache;
+    private pendingRefreshes;
+    private refreshContexts;
+    private options;
+    constructor(itemCache: ItemCache<T>, options: StaleWhileRevalidateOptions);
+    /**
+     * Get item from cache with stale-while-revalidate behavior
+     */
+    get(key: string, fetcher: () => Promise<T | null>, ttl: number, itemType?: string): Promise<T | null>;
+    /**
+     * Force refresh of cached item
+     */
+    refresh(key: string, fetcher: () => Promise<T | null>, ttl: number): Promise<T | null>;
+    /**
+     * Check if key is currently being refreshed
+     */
+    isRefreshing(key: string): boolean;
+    /**
+     * Get refresh status for debugging
+     */
+    getRefreshStatus(): {
+        pendingRefreshes: number;
+        maxConcurrent: number;
+        activeRefreshes: Array<{
+            key: string;
+            startedAt: Date;
+            originalTTL: number;
+        }>;
+    };
+    /**
+     * Start background refresh for stale data
+     */
+    private revalidateInBackground;
+    /**
+     * Perform the actual background refresh
+     */
+    private performBackgroundRefresh;
+    /**
+     * Handle refresh errors
+     */
+    private handleRefreshError;
+    /**
+     * Fetch fresh data and cache it
+     */
+    private fetchAndCache;
+    /**
+     * Cancel pending refresh for a key
+     */
+    private cancelRefresh;
+    /**
+     * Clear all pending refreshes (useful for cleanup)
+     */
+    clearPendingRefreshes(): void;
+    /**
+     * Get statistics about cache behavior
+     */
+    getStats(): {
+        pendingRefreshes: number;
+        averageRefreshTime?: number;
+        refreshSuccessRate?: number;
+    };
+}
+/**
+ * Factory function to create a StaleWhileRevalidateCache
+ */
+export declare function createStaleWhileRevalidateCache<T>(itemCache: ItemCache<T>, options: StaleWhileRevalidateOptions): StaleWhileRevalidateCache<T>;
+//# sourceMappingURL=StaleWhileRevalidateCache.d.ts.map

package/dist/cache/patterns/StaleWhileRevalidateCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaleWhileRevalidateCache.d.ts","sourceRoot":"","sources":["../../../src/cache/patterns/StaleWhileRevalidateCache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,MAAM,WAAW,2BAA2B;IAC1C,+CAA+C;IAC/C,aAAa,EAAE,aAAa,CAAC;IAC7B,wDAAwD;IACxD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,sCAAsC;IACtC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,gBAAgB,EAAE,IAAI,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,yBAAyB,CAAC,CAAC;IACtC,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,OAAO,CAAwC;gBAGrD,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,2BAA2B;IAetC;;OAEG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IA0DpB;;OAEG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAO5F;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,gBAAgB,IAAI;QAClB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,KAAK,CAAC;YACrB,GAAG,EAAE,MAAM,CAAC;YACZ,SAAS,EAAE,IAAI,CAAC;YAChB,WAAW,EAAE,MAAM,CAAC;SACrB,CAAC,CAAC;KACF;IAgBH;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAmC9B;;OAEG;YACW,wBAAwB;IAiCtC;;OAEG;YACW,kBAAkB;IAsBhC;;OAEG;YACW,aAAa;IAoB3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAKrB;;OAEG;IACH,qBAAqB,IAAI,IAAI;IAK7B;;OAEG;IACH,QAAQ,IAAI;QACV,gBAAgB,EAAE,MAAM,CAAC;QACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC3B;CAMJ;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,EAC/C,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,2BAA2B,GACnC,yBAAyB,CAAC,CAAC,CAAC,CAE9B"}

package/dist/cache/types/TwoLayerTypes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Two-Layer Cache Architecture Types
+ * Separates item storage from query result storage to prevent cache poisoning
+ */
+export interface ItemCacheLayer<T> {
+    get(key: string): Promise<T | null>;
+    set(key: string, item: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export interface CachedItem<T> {
+    data: T;
+    createdAt: Date;
+    expiresAt: Date;
+}
+export interface QueryCacheLayer {
+    getResult(queryKey: string): Promise<QueryResult | null>;
+    setResult(queryKey: string, result: QueryResult): Promise<void>;
+    invalidatePattern(pattern: string): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface QueryResult {
+    itemKeys: string[];
+    metadata: QueryMetadata;
+}
+export interface QueryMetadata {
+    queryType: string;
+    isComplete: boolean;
+    createdAt: Date;
+    expiresAt: Date;
+    filter?: string;
+    params?: any;
+    ttl?: number;
+    baseTTL?: number;
+    adjustments?: {
+        peakHours?: {
+            applied: boolean;
+            multiplier: number;
+        };
+    };
+}
+export interface TwoLayerCacheOptions {
+    itemTTL?: number;
+    queryTTL?: number;
+    facetTTL?: number;
+    debug?: boolean;
+}
+export interface CacheKeyBuilder {
+    buildItemKey<T>(item: T): string;
+    buildQueryKey(queryType: string, params?: any): string;
+}
+//# sourceMappingURL=TwoLayerTypes.d.ts.map

package/dist/cache/types/TwoLayerTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TwoLayerTypes.d.ts","sourceRoot":"","sources":["../../../src/cache/types/TwoLayerTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAID,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACzD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,GAAG,CAAC;IAGb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE;QACZ,SAAS,CAAC,EAAE;YACV,OAAO,EAAE,OAAO,CAAC;YACjB,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC;CACH;AAID,MAAM,WAAW,oBAAoB;IAEnC,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IACjC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC;CACxD"}

package/dist/cache/warming/CacheWarmer.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Cache Warming System
+ *
+ * Proactively populates cache with commonly accessed data to improve hit rates.
+ * Supports periodic warming, priority-based execution, and failure handling.
+ */
+import { WarmingQuery } from '../../ttl/TTLConfig.js';
+export interface CacheWarmerOptions {
+    /** Interval between warming cycles (milliseconds) */
+    interval: number;
+    /** Maximum number of concurrent warming operations */
+    maxConcurrency?: number;
+    /** How long to wait for a warming operation before timing out (milliseconds) */
+    operationTimeout?: number;
+    /** Whether to continue warming on individual failures */
+    continueOnError?: boolean;
+    /** Debug logging */
+    debug?: boolean;
+}
+export interface WarmingOperation<T> {
+    /** Unique identifier for this warming operation */
+    id: string;
+    /** Parameters for the operation */
+    params: any;
+    /** Priority (1-10, higher = more important) */
+    priority: number;
+    /** Function to fetch the data */
+    fetcher: () => Promise<T[]>;
+    /** TTL multiplier for warmed data (optional) */
+    ttlMultiplier?: number;
+}
+export interface WarmingResult {
+    /** Operation ID */
+    operationId: string;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Number of items warmed */
+    itemsWarmed: number;
+    /** Time taken in milliseconds */
+    duration: number;
+    /** Error if failed */
+    error?: string;
+}
+export interface WarmingStats {
+    /** Total warming cycles completed */
+    totalCycles: number;
+    /** Total operations attempted */
+    totalOperations: number;
+    /** Total successful operations */
+    successfulOperations: number;
+    /** Total items warmed */
+    totalItemsWarmed: number;
+    /** Average items per operation */
+    averageItemsPerOperation: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Currently running operations */
+    activeOperations: number;
+    /** Last warming cycle timestamp */
+    lastWarmingAt?: Date;
+    /** Next warming cycle timestamp */
+    nextWarmingAt?: Date;
+}
+/**
+ * Cache warming system that proactively populates cache with common queries
+ */
+export declare class CacheWarmer<T> {
+    private options;
+    private operations;
+    private activeOperations;
+    private intervalId?;
+    private stats;
+    constructor(options: CacheWarmerOptions);
+    /**
+     * Add warming operations from configuration
+     */
+    addOperationsFromConfig(queries: WarmingQuery[], fetcherFactory: (params: any) => () => Promise<T[]>): void;
+    /**
+     * Add a single warming operation
+     */
+    addOperation(operation: WarmingOperation<T>): void;
+    /**
+     * Remove a warming operation
+     */
+    removeOperation(operationId: string): boolean;
+    /**
+     * Start periodic warming
+     */
+    startPeriodicWarming(): void;
+    /**
+     * Stop periodic warming
+     */
+    stopPeriodicWarming(): void;
+    /**
+     * Perform a single warming cycle
+     */
+    performWarmingCycle(): Promise<WarmingResult[]>;
+    /**
+     * Perform a single warming operation
+     */
+    private performWarmingOperation;
+    /**
+     * Execute the actual operation with timeout handling
+     */
+    private executeOperation;
+    /**
+     * Warm specific operations immediately
+     */
+    warmOperations(operationIds: string[]): Promise<WarmingResult[]>;
+    /**
+     * Get current warming statistics
+     */
+    getStats(): WarmingStats;
+    /**
+     * Get list of configured operations
+     */
+    getOperations(): Array<{
+        id: string;
+        priority: number;
+        params: any;
+    }>;
+    /**
+     * Check if warming is currently active
+     */
+    isActive(): boolean;
+    /**
+     * Clear all statistics
+     */
+    resetStats(): void;
+    /**
+     * Update internal statistics
+     */
+    private updateStats;
+    /**
+     * Generate a unique operation ID from parameters
+     */
+    private generateOperationId;
+    /**
+     * Cleanup - stop warming and clear operations
+     */
+    cleanup(): void;
+}
+/**
+ * Factory function to create a CacheWarmer
+ */
+export declare function createCacheWarmer<T>(options: CacheWarmerOptions): CacheWarmer<T>;
+//# sourceMappingURL=CacheWarmer.d.ts.map

package/dist/cache/warming/CacheWarmer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheWarmer.d.ts","sourceRoot":"","sources":["../../../src/cache/warming/CacheWarmer.ts"],"names":[],"mappings":"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"}