@fjell/cache 4.6.22 → 4.7.2

package/dist/browser/SessionStorageCacheMap.d.ts

@@ -0,0 +1,51 @@
+import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheMap } from "../CacheMap";
+import { CacheItemMetadata } from "../eviction/EvictionStrategy";
+/**
+ * SessionStorage implementation of CacheMap for browser environments.
+ * Data persists only for the current browser tab/session.
+ *
+ * Note: SessionStorage has a ~5MB limit and stores strings only.
+ * Data is synchronous but is lost when the tab is closed.
+ */
+export declare class SessionStorageCacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends CacheMap<V, S, L1, L2, L3, L4, L5> {
+    readonly implementationType = "browser/sessionStorage";
+    private keyPrefix;
+    private normalizedHashFunction;
+    private readonly verificationHashFunction;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, keyPrefix?: string);
+    private getStorageKey;
+    private getAllStorageKeys;
+    private hasCollisionForHash;
+    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<V | null>;
+    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): void;
+    includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<boolean>;
+    delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<boolean>;
+    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    clone(): Promise<SessionStorageCacheMap<V, S, L1, L2, L3, L4, L5>>;
+    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    values(): Promise<V[]>;
+    clear(): void;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
+    hasQueryResult(queryHash: string): boolean;
+    deleteQueryResult(queryHash: string): void;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
+    clearQueryResults(): void;
+    getMetadata(key: string): CacheItemMetadata | null;
+    setMetadata(key: string, metadata: CacheItemMetadata): void;
+    deleteMetadata(key: string): void;
+    getAllMetadata(): Map<string, CacheItemMetadata>;
+    clearMetadata(): void;
+    getCurrentSize(): {
+        itemCount: number;
+        sizeBytes: number;
+    };
+    getSizeLimits(): {
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    };
+}

package/dist/events/CacheEventEmitter.d.ts

@@ -0,0 +1,82 @@
+import { Item } from "@fjell/core";
+import { AnyCacheEvent, CacheEventListener, CacheSubscription, CacheSubscriptionOptions } from "./CacheEventTypes";
+/**
+ * Cache event emitter that manages subscriptions and event dispatching
+ */
+export declare class CacheEventEmitter<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    private subscriptions;
+    private nextSubscriptionId;
+    private isDestroyed;
+    private cleanupInterval;
+    private readonly CLEANUP_INTERVAL_MS;
+    private readonly MAX_INACTIVE_TIME_MS;
+    private readonly WEAK_REF_ENABLED;
+    constructor();
+    /**
+     * Start periodic cleanup of inactive subscriptions
+     */
+    private startPeriodicCleanup;
+    /**
+     * Perform periodic cleanup of inactive subscriptions
+     */
+    private performPeriodicCleanup;
+    /**
+     * Subscribe to cache events
+     */
+    subscribe(listener: CacheEventListener<V, S, L1, L2, L3, L4, L5>, options?: CacheSubscriptionOptions<S, L1, L2, L3, L4, L5>): CacheSubscription;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(subscriptionId: string): boolean;
+    /**
+     * Emit an event to all matching subscriptions
+     */
+    emit(event: AnyCacheEvent<V, S, L1, L2, L3, L4, L5>): void;
+    /**
+     * Get count of active subscriptions
+     */
+    getSubscriptionCount(): number;
+    /**
+     * Get subscription details (for debugging)
+     */
+    getSubscriptions(): Array<{
+        id: string;
+        options: CacheSubscriptionOptions<S, L1, L2, L3, L4, L5>;
+    }>;
+    /**
+     * Destroy the event emitter and clean up all subscriptions
+     */
+    destroy(): void;
+    /**
+     * Check if an event should be emitted to a specific subscription
+     */
+    private shouldEmitToSubscription;
+    /**
+     * Emit event to a specific subscription, handling debouncing
+     */
+    private emitToSubscription;
+    /**
+     * Normalize a key for comparison
+     */
+    private normalizeKey;
+    /**
+     * Normalize a location key for comparison
+     */
+    private normalizeLocKey;
+    /**
+     * Check if two location arrays match
+     */
+    private locationsMatch;
+    /**
+     * Check if a key matches location filters
+     */
+    private keyMatchesLocations;
+    /**
+     * Check if two queries match (improved comparison)
+     */
+    private queriesMatch;
+    /**
+     * Handle errors that occur in event listeners
+     */
+    private handleListenerError;
+}

package/dist/events/CacheEventFactory.d.ts

@@ -0,0 +1,121 @@
+import { ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheClearedEvent, ItemEvent, LocationInvalidatedEvent, QueryEvent, QueryInvalidatedEvent } from "./CacheEventTypes";
+/**
+ * Factory functions for creating cache events
+ */
+export declare class CacheEventFactory {
+    private static lastTimestamp;
+    private static cleanupInterval;
+    private static instanceCount;
+    private static readonly CLEANUP_INTERVAL_MS;
+    private static readonly MAX_TIMESTAMP_AGE_MS;
+    /**
+     * Initialize cleanup mechanism when first instance is created
+     */
+    private static initializeCleanup;
+    /**
+     * Cleanup mechanism when instance is destroyed
+     */
+    static destroyInstance(): void;
+    /**
+     * Start automatic cleanup timer
+     */
+    private static startCleanupTimer;
+    /**
+     * Stop automatic cleanup timer
+     */
+    private static stopCleanupTimer;
+    /**
+     * Perform periodic cleanup of stale timestamp state
+     */
+    private static performCleanup;
+    /**
+     * Reset the timestamp state (useful for testing)
+     */
+    static resetTimestamp(): void;
+    /**
+     * Generate a unique timestamp that is always greater than the previous one
+     */
+    private static generateTimestamp;
+    /**
+     * Extract affected locations from an item key
+     */
+    private static extractAffectedLocations;
+    /**
+     * Create an item-related event
+     */
+    static createItemEvent<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(type: 'item_created' | 'item_updated' | 'item_removed' | 'item_retrieved' | 'item_set', key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: V | null, options?: {
+        previousItem?: V | null | null;
+        source?: 'api' | 'cache' | 'operation';
+        affectedLocations?: LocKeyArray<L1, L2, L3, L4, L5> | [];
+        context?: {
+            operation?: string;
+            requestId?: string;
+            userId?: string;
+        };
+    }): ItemEvent<V, S, L1, L2, L3, L4, L5>;
+    /**
+     * Create a query event
+     */
+    static createQueryEvent<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | [], items: V[], options?: {
+        source?: 'api' | 'cache' | 'operation';
+        context?: {
+            operation?: string;
+            requestId?: string;
+            userId?: string;
+        };
+    }): QueryEvent<V, S, L1, L2, L3, L4, L5>;
+    /**
+     * Create a cache cleared event
+     */
+    static createCacheClearedEvent(itemsCleared: number, queryCacheCleared?: boolean, options?: {
+        source?: 'api' | 'cache' | 'operation';
+        context?: {
+            operation?: string;
+            requestId?: string;
+            userId?: string;
+        };
+    }): CacheClearedEvent;
+    /**
+     * Create a location invalidated event
+     */
+    static createLocationInvalidatedEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(locations: LocKeyArray<L1, L2, L3, L4, L5> | [], affectedKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[], options?: {
+        source?: 'api' | 'cache' | 'operation';
+        context?: {
+            operation?: string;
+            requestId?: string;
+            userId?: string;
+        };
+    }): LocationInvalidatedEvent<S, L1, L2, L3, L4, L5>;
+    /**
+     * Create a query invalidated event
+     */
+    static createQueryInvalidatedEvent(invalidatedQueries: string[], reason: 'manual' | 'item_changed' | 'location_changed' | 'ttl_expired', options?: {
+        source?: 'api' | 'cache' | 'operation';
+        context?: {
+            operation?: string;
+            requestId?: string;
+            userId?: string;
+        };
+    }): QueryInvalidatedEvent;
+    /**
+     * Create an item created event
+     */
+    static itemCreated<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: V, source?: 'api' | 'cache' | 'operation'): ItemEvent<V, S, L1, L2, L3, L4, L5>;
+    /**
+     * Create an item updated event
+     */
+    static itemUpdated<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: V, previousItem?: V | null, source?: 'api' | 'cache' | 'operation'): ItemEvent<V, S, L1, L2, L3, L4, L5>;
+    /**
+     * Create an item removed event
+     */
+    static itemRemoved<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, previousItem?: V | null, source?: 'api' | 'cache' | 'operation'): ItemEvent<V, S, L1, L2, L3, L4, L5>;
+    /**
+     * Create an item retrieved event
+     */
+    static itemRetrieved<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: V, source?: 'api' | 'cache' | 'operation'): ItemEvent<V, S, L1, L2, L3, L4, L5>;
+    /**
+     * Create an item set event (direct cache operation)
+     */
+    static itemSet<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: V, previousItem?: V | null): ItemEvent<V, S, L1, L2, L3, L4, L5>;
+}

package/dist/events/CacheEventTypes.d.ts

@@ -0,0 +1,122 @@
+import { ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+/**
+ * Types of events that can be emitted by the cache system
+ */
+export type CacheEventType = 'item_created' | 'item_updated' | 'item_removed' | 'item_retrieved' | 'item_set' | 'items_queried' | 'cache_cleared' | 'location_invalidated' | 'query_invalidated';
+/**
+ * Base interface for all cache events
+ */
+export interface CacheEvent {
+    /** Type of the event */
+    type: CacheEventType;
+    /** Timestamp when the event occurred */
+    timestamp: number;
+    /** Source of the event */
+    source: 'api' | 'cache' | 'operation';
+    /** Optional context about what triggered this event */
+    context?: {
+        operation?: string;
+        requestId?: string;
+        userId?: string;
+    };
+}
+/**
+ * Event emitted when a single item is affected
+ */
+export interface ItemEvent<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends CacheEvent {
+    type: 'item_created' | 'item_updated' | 'item_removed' | 'item_retrieved' | 'item_set';
+    /** The key of the affected item */
+    key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>;
+    /** The current item (null for 'item_removed') */
+    item: V | null;
+    /** The previous item before the change (for updates/removals) */
+    previousItem?: V | null;
+    /** Locations affected by this change */
+    affectedLocations?: LocKeyArray<L1, L2, L3, L4, L5> | [];
+}
+/**
+ * Event emitted when multiple items are affected by a query
+ */
+export interface QueryEvent<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends CacheEvent {
+    type: 'items_queried';
+    /** The query that was executed */
+    query: ItemQuery;
+    /** Locations where the query was executed */
+    locations: LocKeyArray<L1, L2, L3, L4, L5> | [];
+    /** Items returned by the query */
+    items: V[];
+    /** Keys of all items affected by this query */
+    affectedKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+}
+/**
+ * Event emitted when the entire cache is cleared
+ */
+export interface CacheClearedEvent extends CacheEvent {
+    type: 'cache_cleared';
+    /** Number of items that were cleared */
+    itemsCleared: number;
+    /** Whether query cache was also cleared */
+    queryCacheCleared: boolean;
+}
+/**
+ * Event emitted when specific locations are invalidated
+ */
+export interface LocationInvalidatedEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends CacheEvent {
+    type: 'location_invalidated';
+    /** Locations that were invalidated */
+    locations: LocKeyArray<L1, L2, L3, L4, L5> | [];
+    /** Keys of items that were affected by the invalidation */
+    affectedKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+}
+/**
+ * Event emitted when cached query results are invalidated
+ */
+export interface QueryInvalidatedEvent extends CacheEvent {
+    type: 'query_invalidated';
+    /** Queries that were invalidated (query hashes) */
+    invalidatedQueries: string[];
+    /** Reason for invalidation */
+    reason: 'manual' | 'item_changed' | 'location_changed' | 'ttl_expired';
+}
+/**
+ * Union type of all possible cache events
+ */
+export type AnyCacheEvent<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = ItemEvent<V, S, L1, L2, L3, L4, L5> | QueryEvent<V, S, L1, L2, L3, L4, L5> | CacheClearedEvent | LocationInvalidatedEvent<S, L1, L2, L3, L4, L5> | QueryInvalidatedEvent;
+/**
+ * Function type for cache event listeners
+ */
+export type CacheEventListener<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = (event: AnyCacheEvent<V, S, L1, L2, L3, L4, L5>) => void;
+/**
+ * Options for subscribing to cache events
+ */
+export interface CacheSubscriptionOptions<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /** Only emit events for specific keys */
+    keys?: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    /** Only emit events for specific locations */
+    locations?: LocKeyArray<L1, L2, L3, L4, L5> | [];
+    /** Only emit events matching this query */
+    query?: ItemQuery;
+    /** Filter by event types */
+    eventTypes?: CacheEventType[];
+    /** Debounce events by this many milliseconds */
+    debounceMs?: number;
+    /** Whether to emit events for items that match the subscription criteria */
+    includeExistingItems?: boolean;
+    /** Optional error handler for listener errors */
+    onError?: (error: Error, event: any) => void;
+    /** Use weak references for the listener (default: true if WeakRef is available) */
+    useWeakRef?: boolean;
+}
+/**
+ * Represents an active subscription to cache events
+ */
+export interface CacheSubscription {
+    /** Unique identifier for this subscription */
+    id: string;
+    /** Unsubscribe from events */
+    unsubscribe: () => void;
+    /** Check if this subscription is still active */
+    isActive: () => boolean;
+    /** Get subscription options */
+    getOptions: () => CacheSubscriptionOptions<any, any, any, any, any, any>;
+}

package/dist/events/index.d.ts

@@ -0,0 +1,3 @@
+export * from './CacheEventTypes';
+export * from './CacheEventEmitter';
+export * from './CacheEventFactory';

package/dist/eviction/EvictionManager.d.ts

@@ -0,0 +1,57 @@
+import { CacheMapMetadataProvider, EvictionStrategy } from './EvictionStrategy';
+/**
+ * Manages eviction logic independently of CacheMap implementations.
+ * This class coordinates between eviction strategies and cache metadata.
+ */
+export declare class EvictionManager {
+    private evictionStrategy;
+    constructor(evictionStrategy?: EvictionStrategy);
+    /**
+     * Set or update the eviction strategy
+     * @param strategy - The eviction strategy to use
+     */
+    setEvictionStrategy(strategy: EvictionStrategy | null): void;
+    /**
+     * Get the current eviction strategy name
+     * @returns Strategy name or null if no eviction
+     */
+    getEvictionStrategyName(): string | null;
+    /**
+     * Handle item access - update metadata for eviction strategy
+     * @param key - Item key
+     * @param metadataProvider - Cache metadata provider
+     */
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    /**
+     * Handle item addition - update metadata and perform eviction if needed
+     * @param key - Item key
+     * @param value - Item value (for size estimation)
+     * @param metadataProvider - Cache metadata provider
+     * @returns Array of keys that were evicted
+     */
+    onItemAdded<T>(key: string, value: T, metadataProvider: CacheMapMetadataProvider): string[];
+    /**
+     * Handle item removal - clean up metadata
+     * @param key - Item key
+     * @param metadataProvider - Cache metadata provider
+     */
+    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    /**
+     * Perform manual eviction check
+     * @param metadataProvider - Cache metadata provider
+     * @returns Array of keys that were evicted
+     */
+    performEviction(metadataProvider: CacheMapMetadataProvider): string[];
+    /**
+     * Check if eviction is supported (i.e., strategy is set)
+     * @returns True if eviction is supported
+     */
+    isEvictionSupported(): boolean;
+    /**
+     * Create eviction context from current cache state
+     * @param metadataProvider - Cache metadata provider
+     * @param newItemSize - Size of item being added (optional)
+     * @returns Eviction context
+     */
+    private createEvictionContext;
+}

package/dist/eviction/EvictionStrategy.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Metadata for tracking cache item usage patterns
+ */
+export interface CacheItemMetadata {
+    /** When the item was first added to cache */
+    addedAt: number;
+    /** When the item was last accessed */
+    lastAccessedAt: number;
+    /** Number of times the item has been accessed */
+    accessCount: number;
+    /** Estimated size of the item in bytes */
+    estimatedSize: number;
+    /** Item key for identification */
+    key: string;
+    /** Frequency score with decay applied (for LFU with sketching) */
+    frequencyScore?: number;
+    /** Last time frequency was updated (for decay calculations) */
+    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): CacheItemMetadata | null;
+    /**
+     * Set metadata for a specific item
+     * @param key - Item key
+     * @param metadata - Metadata to store
+     */
+    setMetadata(key: string, metadata: CacheItemMetadata): void;
+    /**
+     * Delete metadata for a specific item
+     * @param key - Item key
+     */
+    deleteMetadata(key: string): void;
+    /**
+     * Get all metadata entries
+     * @returns Map of all metadata entries
+     */
+    getAllMetadata(): Map<string, CacheItemMetadata>;
+    /**
+     * Clear all metadata
+     */
+    clearMetadata(): void;
+    /**
+     * Get current cache size information
+     * @returns Object with current size metrics
+     */
+    getCurrentSize(): {
+        itemCount: number;
+        sizeBytes: number;
+    };
+    /**
+     * Get cache size limits
+     * @returns Object with size limits (null means unlimited)
+     */
+    getSizeLimits(): {
+        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 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(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    /**
+     * Update metadata when an item is accessed
+     * @param key - Item key
+     * @param metadataProvider - Provider for accessing cache metadata
+     */
+    abstract onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    /**
+     * Update metadata when an item is added
+     * @param key - Item key
+     * @param estimatedSize - Estimated size of the item in bytes
+     * @param metadataProvider - Provider for accessing cache metadata
+     */
+    abstract onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
+    /**
+     * Clean up when an item is removed
+     * @param key - Item key
+     * @param metadataProvider - Provider for accessing cache metadata
+     */
+    abstract onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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
+     */
+    protected calculateEvictionCount(context: EvictionContext): number;
+}

package/dist/eviction/EvictionStrategyConfig.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Base configuration interface for eviction strategies
+ */
+export interface EvictionStrategyConfig {
+    /** Strategy type identifier */
+    readonly type: string;
+}
+/**
+ * Configuration for LFU eviction strategy with frequency sketching
+ */
+export interface LFUConfig extends EvictionStrategyConfig {
+    readonly type: 'lfu';
+    /** Decay factor for aging frequency counts (0.0 to 1.0, default: 0.1) */
+    decayFactor?: number;
+    /** Frequency decay interval in milliseconds (default: 60000) */
+    decayInterval?: number;
+    /** Width of the Count-Min Sketch (default: 1024) */
+    sketchWidth?: number;
+    /** Depth of the Count-Min Sketch (default: 4) */
+    sketchDepth?: number;
+    /** Whether to use probabilistic counting (default: true) */
+    useProbabilisticCounting?: boolean;
+    /** Minimum frequency threshold before decay (default: 1) */
+    minFrequencyThreshold?: number;
+}
+/**
+ * Configuration for LRU eviction strategy
+ */
+export interface LRUConfig extends EvictionStrategyConfig {
+    readonly type: 'lru';
+}
+/**
+ * Configuration for FIFO eviction strategy
+ */
+export interface FIFOConfig extends EvictionStrategyConfig {
+    readonly type: 'fifo';
+}
+/**
+ * Configuration for MRU eviction strategy
+ */
+export interface MRUConfig extends EvictionStrategyConfig {
+    readonly type: 'mru';
+}
+/**
+ * Configuration for Random eviction strategy
+ */
+export interface RandomConfig extends EvictionStrategyConfig {
+    readonly type: 'random';
+}
+/**
+ * Configuration for ARC eviction strategy
+ */
+export interface ARCConfig extends EvictionStrategyConfig {
+    readonly type: 'arc';
+    /** Maximum cache size for ARC calculations */
+    maxCacheSize?: number;
+    /** Frequency threshold for classifying items as "frequent" vs "recent" (default: 2) */
+    frequencyThreshold?: number;
+    /** Use enhanced frequency tracking with decay (default: true) */
+    useEnhancedFrequency?: boolean;
+    /** Decay factor for aging frequency scores (default: 0.05) */
+    frequencyDecayFactor?: number;
+    /** Decay interval for frequency scores (default: 600000 - 10 minutes) */
+    frequencyDecayInterval?: number;
+    /** Use frequency-weighted selection within T1/T2 lists (default: true) */
+    useFrequencyWeightedSelection?: boolean;
+    /** Adaptive learning rate for target size adjustments (default: 1.0) */
+    adaptiveLearningRate?: number;
+}
+/**
+ * Configuration for 2Q eviction strategy
+ */
+export interface TwoQueueConfig extends EvictionStrategyConfig {
+    readonly type: '2q';
+    /** Maximum cache size for 2Q calculations */
+    maxCacheSize?: number;
+    /** Use frequency-based promotion from recent to hot queue (default: true) */
+    useFrequencyPromotion?: boolean;
+    /** Minimum access frequency required for promotion to hot queue (default: 2) */
+    promotionThreshold?: number;
+    /** Decay factor for aging frequency scores in hot queue (default: 0.05) */
+    hotQueueDecayFactor?: number;
+    /** Decay interval for hot queue frequency scores (default: 300000 - 5 minutes) */
+    hotQueueDecayInterval?: number;
+    /** Use frequency-weighted LRU in hot queue instead of pure LRU (default: true) */
+    useFrequencyWeightedLRU?: boolean;
+}
+/**
+ * Union type for all eviction strategy configurations
+ */
+export type EvictionStrategyConfigs = LFUConfig | LRUConfig | FIFOConfig | MRUConfig | RandomConfig | ARCConfig | TwoQueueConfig;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_LFU_CONFIG: LFUConfig;
+export declare const DEFAULT_ARC_CONFIG: ARCConfig;
+export declare const DEFAULT_TWO_QUEUE_CONFIG: TwoQueueConfig;