@fjell/cache 4.7.2 → 4.7.5

package/dist/CacheMap.d.ts

@@ -23,7 +23,7 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Store an item with its key
      */
-    abstract set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): void;
+    abstract set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): Promise<void>;
     /**
      * Check if a key exists in the cache
      */
@@ -31,7 +31,7 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Delete an item by its key
      */
-    abstract delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    abstract delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<void>;
     /**
      * Get all items in the specified locations
      */
@@ -51,7 +51,7 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Get all keys in the cache
      */
-    abstract keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    abstract keys(): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]>;
     /**
      * Get all values in the cache
      */
@@ -59,11 +59,11 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Clear all items from the cache
      */
-    abstract clear(): void;
+    abstract clear(): Promise<void>;
     /**
      * Set a query result as a collection of item keys
      */
-    abstract setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    abstract setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
     /**
      * Get a query result as a collection of item keys
      */
@@ -71,15 +71,15 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Check if a query result exists in cache
      */
-    abstract hasQueryResult(queryHash: string): boolean;
+    abstract hasQueryResult(queryHash: string): Promise<boolean>;
     /**
      * Delete a specific query result
      */
-    abstract deleteQueryResult(queryHash: string): void;
+    abstract deleteQueryResult(queryHash: string): Promise<void>;
     /**
      * Invalidate all cached items by their keys
      */
-    abstract invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    abstract invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
     /**
      * Invalidate all items in specified locations and clear related query results
      */
@@ -87,47 +87,47 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Clear all query result cache entries
      */
-    abstract clearQueryResults(): void;
+    abstract clearQueryResults(): Promise<void>;
     /**
      * Get metadata for a specific item
      * @param key - Item key
      * @returns Metadata if exists, null otherwise
      */
-    abstract getMetadata(key: string): CacheItemMetadata | null;
+    abstract getMetadata(key: string): Promise<CacheItemMetadata | null>;
     /**
      * Set metadata for a specific item
      * @param key - Item key
      * @param metadata - Metadata to store
      */
-    abstract setMetadata(key: string, metadata: CacheItemMetadata): void;
+    abstract setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
     /**
      * Delete metadata for a specific item
      * @param key - Item key
      */
-    abstract deleteMetadata(key: string): void;
+    abstract deleteMetadata(key: string): Promise<void>;
     /**
      * Get all metadata entries
      * @returns Map of all metadata entries
      */
-    abstract getAllMetadata(): Map<string, CacheItemMetadata>;
+    abstract getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
     /**
      * Clear all metadata
      */
-    abstract clearMetadata(): void;
+    abstract clearMetadata(): Promise<void>;
     /**
      * Get current cache size information
      * @returns Object with current size metrics
      */
-    abstract getCurrentSize(): {
+    abstract getCurrentSize(): Promise<{
         itemCount: number;
         sizeBytes: number;
-    };
+    }>;
     /**
      * Get cache size limits
      * @returns Object with size limits (null means unlimited)
      */
-    abstract getSizeLimits(): {
+    abstract getSizeLimits(): Promise<{
         maxItems: number | null;
         maxSizeBytes: number | null;
-    };
+    }>;
 }

package/dist/browser/AsyncIndexDBCacheMap.d.ts

@@ -1,4 +1,5 @@
 import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheItemMetadata } from "../eviction/EvictionStrategy";
 /**
  * IndexedDB implementation of CacheMap for browser environments.
  * Data persists long-term with much larger storage limits than localStorage/sessionStorage.
@@ -14,11 +15,23 @@ export declare class AsyncIndexDBCacheMap<V extends Item<S, L1, L2, L3, L4, L5>,
     private version;
     private normalizedHashFunction;
     private dbPromise;
+    private static readonly CURRENT_VERSION;
     constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, dbName?: string, storeName?: string, version?: number);
     private getDB;
     private getStorageKey;
     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>;
+    /**
+     * Get both the value and metadata for an item
+     */
+    getWithMetadata(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<{
+        value: V;
+        metadata?: CacheItemMetadata;
+    } | null>;
+    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V, metadata?: CacheItemMetadata): Promise<void>;
+    /**
+     * Update only the metadata for an existing item
+     */
+    setMetadata(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, metadata: CacheItemMetadata): 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[]>;
@@ -26,6 +39,10 @@ export declare class AsyncIndexDBCacheMap<V extends Item<S, L1, L2, L3, L4, L5>,
     queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
     clone(): AsyncIndexDBCacheMap<V, S, L1, L2, L3, L4, L5>;
     keys(): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]>;
+    /**
+     * Get all metadata entries from IndexedDB
+     */
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
     values(): Promise<V[]>;
     clear(): Promise<void>;
     setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;

package/dist/browser/IndexDBCacheMap.d.ts

@@ -1,69 +1,67 @@
 import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
-import { CacheMap } from "../CacheMap";
-import { AsyncIndexDBCacheMap } from "./AsyncIndexDBCacheMap";
 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 operationSequence;
+    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>): Promise<V | null>;
-    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): void;
+    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>): void;
+    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[]>;
-    clone(): Promise<IndexDBCacheMap<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;
+    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): boolean;
-    deleteQueryResult(queryHash: string): void;
-    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    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>;
-    clearQueryResults(): void;
-    /**
-     * Clean up resources when the cache is no longer needed
-     */
-    destroy(): void;
-    getMetadata(key: string): CacheItemMetadata | null;
-    setMetadata(key: string, metadata: CacheItemMetadata): void;
-    deleteMetadata(key: string): void;
-    getAllMetadata(): Map<string, CacheItemMetadata>;
-    clearMetadata(): void;
-    getCurrentSize(): {
+    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(): {
+    }>;
+    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
+     */
+    destroy(): void;
 }

package/dist/browser/LocalStorageCacheMap.d.ts

@@ -25,35 +25,35 @@ export declare class LocalStorageCacheMap<V extends Item<S, L1, L2, L3, L4, L5>,
     private removeOldestEntries;
     private getAllStorageKeys;
     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;
+    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>): void;
+    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>)[];
+    keys(): Promise<(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;
+    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): boolean;
-    deleteQueryResult(queryHash: string): void;
-    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    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(): void;
-    getMetadata(key: string): CacheItemMetadata | null;
-    setMetadata(key: string, metadata: CacheItemMetadata): void;
-    deleteMetadata(key: string): void;
-    getAllMetadata(): Map<string, CacheItemMetadata>;
-    clearMetadata(): void;
-    getCurrentSize(): {
+    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(): {
+    }>;
+    getSizeLimits(): Promise<{
         maxItems: number | null;
         maxSizeBytes: number | null;
-    };
+    }>;
 }

package/dist/browser/SessionStorageCacheMap.d.ts

@@ -18,34 +18,34 @@ export declare class SessionStorageCacheMap<V extends Item<S, L1, L2, L3, L4, L5
     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;
+    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>): void;
+    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(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    keys(): Promise<(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;
+    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): boolean;
-    deleteQueryResult(queryHash: string): void;
-    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    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(): void;
-    getMetadata(key: string): CacheItemMetadata | null;
-    setMetadata(key: string, metadata: CacheItemMetadata): void;
-    deleteMetadata(key: string): void;
-    getAllMetadata(): Map<string, CacheItemMetadata>;
-    clearMetadata(): void;
-    getCurrentSize(): {
+    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(): {
+    }>;
+    getSizeLimits(): Promise<{
         maxItems: number | null;
         maxSizeBytes: number | null;
-    };
+    }>;
 }

package/dist/events/CacheEventEmitter.d.ts

@@ -65,6 +65,7 @@ export declare class CacheEventEmitter<V extends Item<S, L1, L2, L3, L4, L5>, S
     private normalizeLocKey;
     /**
      * Check if two location arrays match
+     * Filter locations must be a prefix of event locations (in order)
      */
     private locationsMatch;
     /**

package/dist/eviction/EvictionManager.d.ts

@@ -21,7 +21,7 @@ export declare class EvictionManager {
      * @param key - Item key
      * @param metadataProvider - Cache metadata provider
      */
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
+    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
     /**
      * Handle item addition - update metadata and perform eviction if needed
      * @param key - Item key
@@ -29,7 +29,7 @@ export declare class EvictionManager {
      * @param metadataProvider - Cache metadata provider
      * @returns Array of keys that were evicted
      */
-    onItemAdded<T>(key: string, value: T, metadataProvider: CacheMapMetadataProvider): string[];
+    onItemAdded<T>(key: string, value: T, metadataProvider: CacheMapMetadataProvider): Promise<string[]>;
     /**
      * Handle item removal - clean up metadata
      * @param key - Item key
@@ -41,7 +41,7 @@ export declare class EvictionManager {
      * @param metadataProvider - Cache metadata provider
      * @returns Array of keys that were evicted
      */
-    performEviction(metadataProvider: CacheMapMetadataProvider): string[];
+    performEviction(metadataProvider: CacheMapMetadataProvider): Promise<string[]>;
     /**
      * Check if eviction is supported (i.e., strategy is set)
      * @returns True if eviction is supported

package/dist/eviction/EvictionStrategy.d.ts

@@ -33,43 +33,43 @@ export interface CacheMapMetadataProvider {
      * @param key - Item key
      * @returns Metadata if exists, null otherwise
      */
-    getMetadata(key: string): CacheItemMetadata | null;
+    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): void;
+    setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
     /**
      * Delete metadata for a specific item
      * @param key - Item key
      */
-    deleteMetadata(key: string): void;
+    deleteMetadata(key: string): Promise<void>;
     /**
      * Get all metadata entries
      * @returns Map of all metadata entries
      */
-    getAllMetadata(): Map<string, CacheItemMetadata>;
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
     /**
      * Clear all metadata
      */
-    clearMetadata(): void;
+    clearMetadata(): Promise<void>;
     /**
      * Get current cache size information
      * @returns Object with current size metrics
      */
-    getCurrentSize(): {
+    getCurrentSize(): Promise<{
         itemCount: number;
         sizeBytes: number;
-    };
+    }>;
     /**
      * Get cache size limits
      * @returns Object with size limits (null means unlimited)
      */
-    getSizeLimits(): {
+    getSizeLimits(): Promise<{
         maxItems: number | null;
         maxSizeBytes: number | null;
-    };
+    }>;
 }
 /**
  * Context provided to eviction strategies for decision making
@@ -102,26 +102,26 @@ export declare abstract class EvictionStrategy {
      * @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[];
+    abstract selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<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;
+    abstract onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): Promise<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;
+    abstract onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): Promise<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;
+    abstract onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): Promise<void>;
     /**
      * Get the name/identifier of this eviction strategy
      * @returns String identifier for the strategy

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

@@ -13,11 +13,11 @@ export declare class ARCEvictionStrategy extends EvictionStrategy {
     private readonly maxGhostSize;
     private lastDecayTime;
     constructor(maxCacheSize?: number, config?: Partial<ARCConfig>);
-    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
     private selectLRUFromItems;
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
-    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
-    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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
      */

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

@@ -4,9 +4,9 @@ import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../
  * Removes the oldest added item regardless of usage
  */
 export declare class FIFOEvictionStrategy extends EvictionStrategy {
-    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
-    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
-    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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

@@ -11,10 +11,10 @@ export declare class LFUEvictionStrategy extends EvictionStrategy {
     private readonly sketch;
     private lastDecayTime;
     constructor(config?: Partial<LFUConfig>);
-    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
-    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
-    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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

@@ -4,9 +4,9 @@ import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../
  * Removes the item that was accessed longest ago
  */
 export declare class LRUEvictionStrategy extends EvictionStrategy {
-    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
-    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
-    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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

@@ -5,8 +5,8 @@ import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../
  */
 export declare class MRUEvictionStrategy extends EvictionStrategy {
     getStrategyName(): string;
-    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
-    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
-    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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>;
 }

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

@@ -4,9 +4,9 @@ import { CacheMapMetadataProvider, EvictionContext, EvictionStrategy } from '../
  * Removes a random item from the cache
  */
 export declare class RandomEvictionStrategy extends EvictionStrategy {
-    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
-    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
-    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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

@@ -15,7 +15,7 @@ export declare class TwoQueueEvictionStrategy extends EvictionStrategy {
     private readonly maxGhostSize;
     private lastDecayTime;
     constructor(maxCacheSize?: number, config?: Partial<TwoQueueConfig>);
-    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): string[];
+    selectForEviction(metadataProvider: CacheMapMetadataProvider, context: EvictionContext): Promise<string[]>;
     /**
      * Select eviction candidate from hot queue using traditional LRU
      */
@@ -24,9 +24,9 @@ export declare class TwoQueueEvictionStrategy extends EvictionStrategy {
      * Select eviction candidate from hot queue using frequency-weighted LRU
      */
     private selectFromHotQueueFrequencyWeighted;
-    onItemAccessed(key: string, metadataProvider: CacheMapMetadataProvider): void;
-    onItemAdded(key: string, estimatedSize: number, metadataProvider: CacheMapMetadataProvider): void;
-    onItemRemoved(key: string, metadataProvider: CacheMapMetadataProvider): 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
      */