@fjell/cache 4.6.22 → 4.7.2

package/dist/eviction/EvictionStrategyFactory.d.ts

@@ -0,0 +1,12 @@
+import { EvictionPolicy } from '../Options';
+import { EvictionStrategy } from './EvictionStrategy';
+import { EvictionStrategyConfigs } from './EvictionStrategyConfig';
+/**
+ * Factory function to create eviction strategy instances with configuration
+ */
+export declare function createEvictionStrategy(policy: EvictionPolicy, maxCacheSize?: number, config?: EvictionStrategyConfigs): EvictionStrategy;
+/**
+ * Factory function for backwards compatibility
+ * @deprecated Use createEvictionStrategy with config parameter instead
+ */
+export declare function createEvictionStrategyLegacy(policy: EvictionPolicy, maxCacheSize?: number): EvictionStrategy;

package/dist/eviction/EvictionStrategyValidation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Validation functions for eviction strategy configurations
+ */
+import { ARCConfig, EvictionStrategyConfigs, LFUConfig, TwoQueueConfig } from './EvictionStrategyConfig';
+/**
+ * Sanitizes LFU configuration parameters, correcting invalid values
+ */
+export declare function sanitizeLFUConfig(config: Partial<LFUConfig>): Partial<LFUConfig>;
+/**
+ * Validates LFU configuration parameters (after sanitization)
+ */
+export declare function validateLFUConfig(config: Partial<LFUConfig>): void;
+/**
+ * Sanitizes ARC configuration parameters, correcting invalid values
+ */
+export declare function sanitizeARCConfig(config: Partial<ARCConfig>): Partial<ARCConfig>;
+/**
+ * Validates ARC configuration parameters (after sanitization)
+ */
+export declare function validateARCConfig(config: Partial<ARCConfig>): void;
+/**
+ * Sanitizes TwoQueue configuration parameters, correcting invalid values
+ */
+export declare function sanitizeTwoQueueConfig(config: Partial<TwoQueueConfig>): Partial<TwoQueueConfig>;
+/**
+ * Validates TwoQueue configuration parameters (after sanitization)
+ */
+export declare function validateTwoQueueConfig(config: Partial<TwoQueueConfig>): void;
+/**
+ * Validates any eviction strategy configuration
+ */
+export declare function validateEvictionStrategyConfig(config: Partial<EvictionStrategyConfigs>): void;
+/**
+ * Creates a validated configuration with defaults applied and invalid values sanitized
+ */
+export declare function createValidatedConfig<T extends EvictionStrategyConfigs>(baseConfig: T, userConfig: Partial<T>): T;

package/dist/eviction/index.d.ts

@@ -0,0 +1,10 @@
+export { EvictionStrategy, CacheItemMetadata, CacheMapMetadataProvider, EvictionContext } from './EvictionStrategy';
+export { createEvictionStrategy } from './EvictionStrategyFactory';
+export { EvictionManager } from './EvictionManager';
+export { LRUEvictionStrategy } from './strategies/LRUEvictionStrategy';
+export { LFUEvictionStrategy } from './strategies/LFUEvictionStrategy';
+export { FIFOEvictionStrategy } from './strategies/FIFOEvictionStrategy';
+export { MRUEvictionStrategy } from './strategies/MRUEvictionStrategy';
+export { RandomEvictionStrategy } from './strategies/RandomEvictionStrategy';
+export { ARCEvictionStrategy } from './strategies/ARCEvictionStrategy';
+export { TwoQueueEvictionStrategy } from './strategies/TwoQueueEvictionStrategy';

package/dist/eviction/strategies/ARCEvictionStrategy.d.ts

@@ -0,0 +1,73 @@
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
+import { ARCConfig } from '../EvictionStrategyConfig';
+/**
+ * ARC (Adaptive Replacement Cache) eviction strategy with enhanced frequency tracking
+ * Balances between recency (LRU) and frequency (LFU) dynamically with sophisticated frequency analysis
+ */
+export declare class ARCEvictionStrategy extends EvictionStrategy {
+    getStrategyName(): string;
+    private recentGhosts;
+    private frequentGhosts;
+    private targetRecentSize;
+    private readonly config;
+    private readonly maxGhostSize;
+    private lastDecayTime;
+    constructor(maxCacheSize?: number, config?: Partial<ARCConfig>);
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    private selectLRUFromItems;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    /**
+     * Add key to recent ghost list with proper size management
+     */
+    private addToRecentGhosts;
+    /**
+     * Add key to frequent ghost list with proper size management
+     */
+    private addToFrequentGhosts;
+    /**
+     * Cleanup ghost lists to prevent memory leaks
+     */
+    private cleanupGhostLists;
+    /**
+     * Enforce size limit on a ghost list by removing oldest entries
+     */
+    private enforceGhostListSizeLimit;
+    /**
+     * Determine if an item should be classified as frequent vs recent
+     */
+    private isFrequentItem;
+    /**
+     * Get effective frequency for an item, applying decay if enabled
+     */
+    private getEffectiveFrequency;
+    /**
+     * Calculate frequency score with decay applied
+     */
+    private calculateFrequencyScore;
+    /**
+     * Select eviction candidate using frequency-weighted approach
+     */
+    private selectFrequencyWeightedFromItems;
+    /**
+     * Apply periodic decay to frequency scores
+     */
+    private applyPeriodicDecay;
+    /**
+     * Get configuration for this strategy
+     */
+    getConfig(): ARCConfig;
+    /**
+     * Reset internal state (useful for testing)
+     */
+    reset(): void;
+    /**
+     * Get current adaptive state for monitoring/debugging
+     */
+    getAdaptiveState(): {
+        targetRecentSize: number;
+        recentGhostSize: number;
+        frequentGhostSize: number;
+    };
+}

package/dist/eviction/strategies/FIFOEvictionStrategy.d.ts

@@ -0,0 +1,12 @@
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
+/**
+ * FIFO (First-In, First-Out) eviction strategy
+ * Removes the oldest added item regardless of usage
+ */
+export declare class FIFOEvictionStrategy extends EvictionStrategy {
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    getStrategyName(): string;
+}

package/dist/eviction/strategies/LFUEvictionStrategy.d.ts

@@ -0,0 +1,38 @@
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
+import { LFUConfig } from '../EvictionStrategyConfig';
+/**
+ * LFU (Least Frequently Used) eviction strategy with frequency sketching and decay
+ * Uses probabilistic counting and time-based frequency decay for more accurate frequency estimation
+ * When configured with default settings, behaves like traditional LFU for backwards compatibility
+ */
+export declare class LFUEvictionStrategy extends EvictionStrategy {
+    getStrategyName(): string;
+    private readonly config;
+    private readonly sketch;
+    private lastDecayTime;
+    constructor(config?: Partial<LFUConfig>);
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    /**
+     * Get the effective frequency for an item, applying real-time decay if needed
+     */
+    private getEffectiveFrequency;
+    /**
+     * Calculate frequency score with decay applied
+     */
+    private calculateFrequencyScore;
+    /**
+     * Apply periodic decay to the frequency sketch and metadata
+     */
+    private applyPeriodicDecay;
+    /**
+     * Get configuration for this strategy
+     */
+    getConfig(): LFUConfig;
+    /**
+     * Reset frequency tracking (useful for testing or cache clearing)
+     */
+    reset(): void;
+}

package/dist/eviction/strategies/LRUEvictionStrategy.d.ts

@@ -0,0 +1,12 @@
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
+/**
+ * LRU (Least Recently Used) eviction strategy
+ * Removes the item that was accessed longest ago
+ */
+export declare class LRUEvictionStrategy extends EvictionStrategy {
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    getStrategyName(): string;
+}

package/dist/eviction/strategies/MRUEvictionStrategy.d.ts

@@ -0,0 +1,12 @@
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
+/**
+ * MRU (Most Recently Used) eviction strategy
+ * Removes the most recently accessed item
+ */
+export declare class MRUEvictionStrategy extends EvictionStrategy {
+    getStrategyName(): string;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+}

package/dist/eviction/strategies/RandomEvictionStrategy.d.ts

@@ -0,0 +1,12 @@
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
+/**
+ * Random eviction strategy
+ * Removes a random item from the cache
+ */
+export declare class RandomEvictionStrategy extends EvictionStrategy {
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    getStrategyName(): string;
+}

package/dist/eviction/strategies/TwoQueueEvictionStrategy.d.ts

@@ -0,0 +1,54 @@
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
+import { TwoQueueConfig } from '../EvictionStrategyConfig';
+/**
+ * 2Q (Two Queues) eviction strategy with enhanced frequency tracking
+ * Maintains separate queues for recent and frequently accessed items
+ * Uses frequency analysis for promotion decisions and weighted LRU in hot queue
+ */
+export declare class TwoQueueEvictionStrategy extends EvictionStrategy {
+    getStrategyName(): string;
+    private recentQueue;
+    private hotQueue;
+    private ghostQueue;
+    private readonly config;
+    private readonly maxRecentSize;
+    private readonly maxGhostSize;
+    private lastDecayTime;
+    constructor(maxCacheSize?: number, config?: Partial<TwoQueueConfig>);
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    /**
+     * Select eviction candidate from hot queue using traditional LRU
+     */
+    private selectFromHotQueueLRU;
+    /**
+     * Select eviction candidate from hot queue using frequency-weighted LRU
+     */
+    private selectFromHotQueueFrequencyWeighted;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    /**
+     * Determine if an item should be promoted from recent to hot queue
+     */
+    private shouldPromoteToHotQueue;
+    /**
+     * Get effective frequency for an item, applying decay if enabled
+     */
+    private getEffectiveFrequency;
+    /**
+     * Calculate frequency score with decay applied
+     */
+    private calculateFrequencyScore;
+    /**
+     * Apply periodic decay to hot queue items
+     */
+    private applyPeriodicDecay;
+    /**
+     * Get configuration for this strategy
+     */
+    getConfig(): TwoQueueConfig;
+    /**
+     * Reset internal state (useful for testing)
+     */
+    reset(): void;
+}

package/dist/index.d.ts

@@ -1,7 +1,30 @@
-export * from './Aggregator';
-export * from './Cache';
-export * from './CacheMap';
-export * from './Instance';
-export * from './InstanceFactory';
-export * from './Operations';
+export { createCache, isCache } from './Cache';
+export type { Cache, CacheInfo } from './Cache';
+export { CacheMap } from './CacheMap';
+export { CacheStatsManager } from './CacheStats';
+export type { CacheStats } from './CacheStats';
+export { MemoryCacheMap } from './memory/MemoryCacheMap';
+export { EnhancedMemoryCacheMap } from './memory/EnhancedMemoryCacheMap';
+export { LocalStorageCacheMap } from './browser/LocalStorageCacheMap';
+export { SessionStorageCacheMap } from './browser/SessionStorageCacheMap';
+export { IndexDBCacheMap } from './browser/IndexDBCacheMap';
+export { AsyncIndexDBCacheMap } from './browser/AsyncIndexDBCacheMap';
+export { createOptions, createCacheMap, validateOptions } from './Options';
+export type { Options, CacheType, EvictionPolicy, CacheSizeConfig, IndexedDBConfig, WebStorageConfig, MemoryConfig, CacheMapFactory } from './Options';
+export { createInstanceFactory } from './InstanceFactory';
+export type { InstanceFactory } from './InstanceFactory';
+export { createInstance, isInstance } from './Instance';
+export type { Instance } from './Instance';
+export { normalizeKeyValue, createNormalizedHashFunction, isLocKeyArrayEqual, normalizeLocKeyItem } from './normalization';
+export { parseSizeString, formatBytes, estimateValueSize, validateSizeConfig } from './utils/CacheSize';
+export { createEvictionStrategy, EvictionManager } from './eviction';
+export type { CacheItemMetadata, CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from './eviction';
+export { TTLManager } from './ttl';
+export type { TTLConfig, TTLItemMetadata } from './ttl';
+export { validateEvictionStrategyConfig, validateLFUConfig, validateARCConfig, validateTwoQueueConfig, createValidatedConfig } from './eviction/EvictionStrategyValidation';
+export { createOperations } from './Operations';
+export type { Operations } from './Operations';
+export * from './events';
+export { createAggregator, toCacheConfig } from './Aggregator';
+export type { Aggregator, CacheConfig, AggregateConfig } from './Aggregator';
 export * from './Registry';