@fjell/cache 4.7.0 → 4.7.4

package/dist/browser/IndexDBCacheMap.d.ts

@@ -1,52 +1,65 @@
 import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
-import { CacheMap } from "../CacheMap";
+import { CacheItemMetadata } from "../eviction/EvictionStrategy";
 import { AsyncIndexDBCacheMap } from "./AsyncIndexDBCacheMap";
+import { CacheMap } from "../CacheMap";
 /**
- * Synchronous wrapper for IndexedDB CacheMap implementation.
+ * Synchronous IndexedDB CacheMap wrapper implementation.
  *
- * This implementation provides a synchronous interface over IndexedDB
- * by maintaining an in-memory cache that is periodically synchronized
- * with IndexedDB storage. For full async capabilities, use AsyncIndexDBCacheMap.
+ * This implementation provides synchronous memory operations with background IndexedDB persistence.
+ * Memory operations are immediate while IndexedDB operations happen asynchronously in the background.
  *
- * Note: This class maintains synchronous compatibility while providing
- * persistent storage benefits of IndexedDB.
+ * Benefits:
+ * - Fast memory access for immediate operations
+ * - Background persistence to IndexedDB for durability
+ * - Synchronous API compatible with other CacheMap implementations
+ * - Automatic sync between memory and IndexedDB
  */
 export declare class IndexDBCacheMap<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/indexedDB";
+    private memoryMap;
+    private queryResultCache;
+    private metadataMap;
+    private normalizedHashFunction;
+    protected types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>;
     asyncCache: AsyncIndexDBCacheMap<V, S, L1, L2, L3, L4, L5>;
-    private memoryCache;
     private syncInterval;
-    private readonly SYNC_INTERVAL_MS;
-    private pendingSyncOperations;
-    private initializationPromise;
-    private isInitialized;
-    private readonly MAX_RETRY_ATTEMPTS;
+    private pendingOperations;
+    private sequenceCounter;
     constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, dbName?: string, storeName?: string, version?: number);
     private initializeFromIndexedDB;
     private startPeriodicSync;
-    private syncToIndexedDB;
     private processPendingOperations;
-    private queueForSync;
-    private queueDeleteForSync;
-    private queueClearForSync;
-    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;
-    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;
-    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(): IndexDBCacheMap<V, S, L1, L2, L3, L4, L5>;
-    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
-    values(): 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;
-    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;
-    clearQueryResults(): void;
+    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): Promise<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>): Promise<void>;
+    keys(): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]>;
+    values(): Promise<V[]>;
+    clear(): Promise<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[]>;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
+    getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
+    hasQueryResult(queryHash: string): Promise<boolean>;
+    deleteQueryResult(queryHash: string): Promise<void>;
+    clearQueryResults(): Promise<void>;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
+    getMetadata(key: string): Promise<CacheItemMetadata | null>;
+    setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
+    deleteMetadata(key: string): Promise<void>;
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
+    clearMetadata(): Promise<void>;
+    getCurrentSize(): Promise<{
+        itemCount: number;
+        sizeBytes: number;
+    }>;
+    getSizeLimits(): Promise<{
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    }>;
+    clone(): Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;
     /**
      * Clean up resources when the cache is no longer needed
      */

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;
-    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;
-    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>;
+    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): Promise<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>): Promise<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<LocalStorageCacheMap<V, S, L1, L2, L3, L4, L5>>;
     private parseStorageEntry;
-    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
-    values(): 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;
-    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;
-    clearQueryResults(): void;
+    keys(): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]>;
+    values(): Promise<V[]>;
+    clear(): Promise<void>;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
+    getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
+    hasQueryResult(queryHash: string): Promise<boolean>;
+    deleteQueryResult(queryHash: string): Promise<void>;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
+    clearQueryResults(): Promise<void>;
+    getMetadata(key: string): Promise<CacheItemMetadata | null>;
+    setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
+    deleteMetadata(key: string): Promise<void>;
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
+    clearMetadata(): Promise<void>;
+    getCurrentSize(): Promise<{
+        itemCount: number;
+        sizeBytes: number;
+    }>;
+    getSizeLimits(): Promise<{
+        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;
-    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;
-    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>;
-    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
-    values(): 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;
-    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;
-    clearQueryResults(): void;
+    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): Promise<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>): Promise<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(): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]>;
+    values(): Promise<V[]>;
+    clear(): Promise<void>;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
+    getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
+    hasQueryResult(queryHash: string): Promise<boolean>;
+    deleteQueryResult(queryHash: string): Promise<void>;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
+    clearQueryResults(): Promise<void>;
+    getMetadata(key: string): Promise<CacheItemMetadata | null>;
+    setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
+    deleteMetadata(key: string): Promise<void>;
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
+    clearMetadata(): Promise<void>;
+    getCurrentSize(): Promise<{
+        itemCount: number;
+        sizeBytes: number;
+    }>;
+    getSizeLimits(): Promise<{
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    }>;
 }

package/dist/events/CacheEventEmitter.d.ts

@@ -0,0 +1,83 @@
+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
+     * Filter locations must be a prefix of event locations (in order)
+     */
+    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): Promise<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): Promise<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): Promise<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;
+}