@fjell/cache 4.7.0 → 4.7.4

package/dist/eviction/EvictionStrategy.d.ts

@@ -18,33 +18,125 @@ export interface CacheItemMetadata {
     lastFrequencyUpdate?: number;
     /** Raw frequency count before decay */
     rawFrequency?: number;
+    /** Additional strategy-specific metadata */
+    strategyData?: {
+        [key: string]: any;
+    };
+}
+/**
+ * Interface for CacheMap implementations to support metadata storage
+ * This allows eviction strategies to store and retrieve metadata independently of the storage mechanism
+ */
+export interface CacheMapMetadataProvider {
+    /**
+     * Get metadata for a specific item
+     * @param key - Item key
+     * @returns Metadata if exists, null otherwise
+     */
+    getMetadata(key: string): Promise<CacheItemMetadata | null>;
+    /**
+     * Set metadata for a specific item
+     * @param key - Item key
+     * @param metadata - Metadata to store
+     */
+    setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
+    /**
+     * Delete metadata for a specific item
+     * @param key - Item key
+     */
+    deleteMetadata(key: string): Promise<void>;
+    /**
+     * Get all metadata entries
+     * @returns Map of all metadata entries
+     */
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
+    /**
+     * Clear all metadata
+     */
+    clearMetadata(): Promise<void>;
+    /**
+     * Get current cache size information
+     * @returns Object with current size metrics
+     */
+    getCurrentSize(): Promise<{
+        itemCount: number;
+        sizeBytes: number;
+    }>;
+    /**
+     * Get cache size limits
+     * @returns Object with size limits (null means unlimited)
+     */
+    getSizeLimits(): Promise<{
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    }>;
+}
+/**
+ * Context provided to eviction strategies for decision making
+ */
+export interface EvictionContext {
+    /** Current cache size information */
+    currentSize: {
+        itemCount: number;
+        sizeBytes: number;
+    };
+    /** Cache size limits */
+    limits: {
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    };
+    /** Size of the item being added (for proactive eviction) */
+    newItemSize?: number;
 }
 /**
  * Abstract base class for cache eviction strategies.
  * Defines the core contract that all eviction policies must implement.
+ *
+ * Eviction strategies are now completely independent of CacheMap implementations
+ * and interact through the CacheMapMetadataProvider interface.
  */
 export declare abstract class EvictionStrategy {
     /**
-     * Select which item should be evicted based on the strategy
-     * @param items - Map of items with their metadata
-     * @returns Key of the item to evict, or null if no eviction needed
+     * Select which items should be evicted based on the strategy and context
+     * @param metadataProvider - Provider for accessing cache metadata
+     * @param context - Current cache state and limits
+     * @returns Array of keys to evict (empty array if no eviction needed)
      */
-    abstract selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    abstract selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
     /**
      * Update metadata when an item is accessed
      * @param key - Item key
-     * @param metadata - Current metadata
+     * @param metadataProvider - Provider for accessing cache metadata
      */
-    abstract onItemAccessed(key: string, metadata: CacheItemMetadata): void;
+    abstract onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
     /**
      * Update metadata when an item is added
      * @param key - Item key
-     * @param metadata - Initial metadata
+     * @param estimatedSize - Estimated size of the item in bytes
+     * @param metadataProvider - Provider for accessing cache metadata
      */
-    abstract onItemAdded(key: string, metadata: CacheItemMetadata): void;
+    abstract onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
     /**
      * Clean up when an item is removed
-     * @param key - Item key (optional for some strategies)
+     * @param key - Item key
+     * @param metadataProvider - Provider for accessing cache metadata
+     */
+    abstract onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    /**
+     * Get the name/identifier of this eviction strategy
+     * @returns String identifier for the strategy
+     */
+    abstract getStrategyName(): string;
+    /**
+     * Determine if eviction is needed based on current context
+     * @param context - Current cache state and limits
+     * @returns True if eviction should occur
+     */
+    protected isEvictionNeeded(context: EvictionContext): boolean;
+    /**
+     * Calculate how many items need to be evicted
+     * @param context - Current cache state and limits
+     * @returns Number of items that should be evicted
      */
-    abstract onItemRemoved(key?: string): void;
+    protected calculateEvictionCount(context: EvictionContext): number;
 }

package/dist/eviction/index.d.ts

@@ -1,5 +1,6 @@
-export { EvictionStrategy, CacheItemMetadata } from './EvictionStrategy';
+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';

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

@@ -1,10 +1,11 @@
-import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+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;
@@ -12,11 +13,11 @@ export declare class ARCEvictionStrategy extends EvictionStrategy {
     private readonly maxGhostSize;
     private lastDecayTime;
     constructor(maxCacheSize?: number, config?: Partial<ARCConfig>);
-    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
     private selectLRUFromItems;
-    onItemAccessed(key: string, metadata: CacheItemMetadata): void;
-    onItemAdded(key: string, metadata: CacheItemMetadata): void;
-    onItemRemoved(key: string): void;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
     /**
      * Add key to recent ghost list with proper size management
      */
@@ -29,6 +30,10 @@ export declare class ARCEvictionStrategy extends EvictionStrategy {
      * 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
      */

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

@@ -1,11 +1,12 @@
-import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+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(items: Map<string, CacheItemMetadata>): string | null;
-    onItemAccessed(_key: string, metadata: CacheItemMetadata): void;
-    onItemAdded(_key: string, metadata: CacheItemMetadata): void;
-    onItemRemoved(): void;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    getStrategyName(): string;
 }

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

@@ -1,4 +1,4 @@
-import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
 import { LFUConfig } from '../EvictionStrategyConfig';
 /**
  * LFU (Least Frequently Used) eviction strategy with frequency sketching and decay
@@ -6,14 +6,15 @@ import { LFUConfig } from '../EvictionStrategyConfig';
  * 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(items: Map<string, CacheItemMetadata>): string | null;
-    onItemAccessed(key: string, metadata: CacheItemMetadata): void;
-    onItemAdded(key: string, metadata: CacheItemMetadata): void;
-    onItemRemoved(): void;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
     /**
      * Get the effective frequency for an item, applying real-time decay if needed
      */

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

@@ -1,11 +1,12 @@
-import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+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(items: Map<string, CacheItemMetadata>): string | null;
-    onItemAccessed(_key: string, metadata: CacheItemMetadata): void;
-    onItemAdded(_key: string, metadata: CacheItemMetadata): void;
-    onItemRemoved(): void;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    getStrategyName(): string;
 }

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

@@ -1,11 +1,12 @@
-import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+import { CacheMapMetadataProvider, EvictionContext, 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;
+    getStrategyName(): string;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
 }

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

@@ -1,11 +1,12 @@
-import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+import { CacheMapMetadataProvider, EvictionContext, 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;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    getStrategyName(): string;
 }

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

@@ -1,4 +1,4 @@
-import { CacheItemMetadata, EvictionStrategy } from '../EvictionStrategy';
+import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../EvictionStrategy';
 import { TwoQueueConfig } from '../EvictionStrategyConfig';
 /**
  * 2Q (Two Queues) eviction strategy with enhanced frequency tracking
@@ -6,6 +6,7 @@ import { TwoQueueConfig } from '../EvictionStrategyConfig';
  * 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;
@@ -14,7 +15,7 @@ export declare class TwoQueueEvictionStrategy extends EvictionStrategy {
     private readonly maxGhostSize;
     private lastDecayTime;
     constructor(maxCacheSize?: number, config?: Partial<TwoQueueConfig>);
-    selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
     /**
      * Select eviction candidate from hot queue using traditional LRU
      */
@@ -23,9 +24,9 @@ export declare class TwoQueueEvictionStrategy extends EvictionStrategy {
      * 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;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<void>;
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
     /**
      * Determine if an item should be promoted from recent to hot queue
      */

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { createCache, isCache } from './Cache';
-export type { Cache } 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';
@@ -15,10 +17,14 @@ 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 { 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';