@fjell/cache 4.7.0 → 4.7.2

package/dist/browser/LocalStorageCacheMap.d.ts

@@ -1,43 +1,59 @@
 import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
 import { CacheMap } from "../CacheMap";
+import { CacheItemMetadata } from "../eviction/EvictionStrategy";
 /**
  * LocalStorage implementation of CacheMap for browser environments.
  * Data persists across browser sessions and page reloads.
  *
  * Note: LocalStorage has a ~5-10MB limit and stores strings only.
  * Data is synchronous and survives browser restarts.
+ * Will throw errors if storage quota is exceeded, though it attempts
+ * to clean up old entries first.
  */
 export declare class LocalStorageCacheMap<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/localStorage";
     private keyPrefix;
     private normalizedHashFunction;
-    private fallbackCache;
-    private quotaExceeded;
+    private readonly MAX_RETRY_ATTEMPTS;
+    private readonly AGGRESSIVE_CLEANUP_PERCENTAGE;
     constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, keyPrefix?: string);
     private getStorageKey;
-    private initializeFallbackCache;
     private isQuotaExceededError;
+    private getAllKeysStartingWith;
     private tryCleanupOldEntries;
     private collectCacheEntries;
     private removeOldestEntries;
     private getAllStorageKeys;
-    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): V | null;
-    getWithTTL(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, ttl: number): V | null;
+    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>): boolean;
+    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> | []): V[];
-    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): boolean;
-    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
-    clone(): LocalStorageCacheMap<V, S, L1, L2, L3, L4, L5>;
+    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<LocalStorageCacheMap<V, S, L1, L2, L3, L4, L5>>;
     private parseStorageEntry;
     keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
-    values(): V[];
+    values(): Promise<V[]>;
     clear(): void;
-    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[], ttl?: number): void;
-    getQueryResult(queryHash: string): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null;
+    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> | []): 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/browser/SessionStorageCacheMap.d.ts

@@ -1,5 +1,6 @@
 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.
@@ -8,28 +9,43 @@ import { CacheMap } from "../CacheMap";
  * 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;
-    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): V | null;
-    getWithTTL(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, ttl: number): V | null;
+    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>): boolean;
+    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> | []): V[];
-    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): boolean;
-    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
-    clone(): SessionStorageCacheMap<V, S, L1, L2, L3, L4, L5>;
+    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(): V[];
+    values(): Promise<V[]>;
     clear(): void;
-    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[], ttl?: number): void;
-    getQueryResult(queryHash: string): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null;
+    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> | []): 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

@@ -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): 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 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): 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): 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): 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): 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;
 }