@fjell/cache 4.6.22 → 4.7.0

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

@@ -0,0 +1,68 @@
+import { CacheItemMetadata, 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 {
+    private recentGhosts;
+    private frequentGhosts;
+    private targetRecentSize;
+    private readonly config;
+    private readonly maxGhostSize;
+    private lastDecayTime;
+    constructor(maxCacheSize?: number, config?: Partial<ARCConfig>);
+    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    private selectLRUFromItems;
+    onItemAccessed(key: string, metadata: CacheItemMetadata): void;
+    onItemAdded(key: string, metadata: CacheItemMetadata): void;
+    onItemRemoved(key: string): 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;
+    /**
+     * 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,11 @@
+import { CacheItemMetadata, 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(items: Map<string, CacheItemMetadata>): string | null;
+    onItemAccessed(_key: string, metadata: CacheItemMetadata): void;
+    onItemAdded(_key: string, metadata: CacheItemMetadata): void;
+    onItemRemoved(): void;
+}

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

@@ -0,0 +1,37 @@
+import { CacheItemMetadata, 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 {
+    private readonly config;
+    private readonly sketch;
+    private lastDecayTime;
+    constructor(config?: Partial<LFUConfig>);
+    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    onItemAccessed(key: string, metadata: CacheItemMetadata): void;
+    onItemAdded(key: string, metadata: CacheItemMetadata): void;
+    onItemRemoved(): 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,11 @@
+import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+/**
+ * LRU (Least Recently Used) eviction strategy
+ * Removes the item that was accessed longest ago
+ */
+export declare class LRUEvictionStrategy extends EvictionStrategy {
+    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    onItemAccessed(_key: string, metadata: CacheItemMetadata): void;
+    onItemAdded(_key: string, metadata: CacheItemMetadata): void;
+    onItemRemoved(): void;
+}

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

@@ -0,0 +1,11 @@
+import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+/**
+ * MRU (Most Recently Used) eviction strategy
+ * Removes the most recently accessed item
+ */
+export declare class MRUEvictionStrategy extends EvictionStrategy {
+    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    onItemAccessed(_key: string, metadata: CacheItemMetadata): void;
+    onItemAdded(_key: string, metadata: CacheItemMetadata): void;
+    onItemRemoved(): void;
+}

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

@@ -0,0 +1,11 @@
+import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+/**
+ * Random eviction strategy
+ * Removes a random item from the cache
+ */
+export declare class RandomEvictionStrategy extends EvictionStrategy {
+    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    onItemAccessed(_key: string, metadata: CacheItemMetadata): void;
+    onItemAdded(_key: string, metadata: CacheItemMetadata): void;
+    onItemRemoved(): void;
+}

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

@@ -0,0 +1,53 @@
+import { CacheItemMetadata, 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 {
+    private recentQueue;
+    private hotQueue;
+    private ghostQueue;
+    private readonly config;
+    private readonly maxRecentSize;
+    private readonly maxGhostSize;
+    private lastDecayTime;
+    constructor(maxCacheSize?: number, config?: Partial<TwoQueueConfig>);
+    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    /**
+     * 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, metadata: CacheItemMetadata): void;
+    onItemAdded(key: string, metadata: CacheItemMetadata): void;
+    onItemRemoved(key: string): 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,24 @@
-export * from './Aggregator';
-export * from './Cache';
-export * from './CacheMap';
-export * from './Instance';
-export * from './InstanceFactory';
-export * from './Operations';
-export * from './Registry';
+export { createCache, isCache } from './Cache';
+export type { Cache } from './Cache';
+export { CacheMap } from './CacheMap';
+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 } from './eviction';
+export type { CacheItemMetadata, EvictionStrategy } from './eviction';
+export { validateEvictionStrategyConfig, validateLFUConfig, validateARCConfig, validateTwoQueueConfig, createValidatedConfig } from './eviction/EvictionStrategyValidation';
+export { createOperations } from './Operations';
+export type { Operations } from './Operations';
+export { createAggregator, toCacheConfig } from './Aggregator';
+export type { Aggregator, CacheConfig, AggregateConfig } from './Aggregator';