@fjell/cache 4.7.0 → 4.7.2

package/README.md

@@ -21,6 +21,7 @@ Fjell Cache provides intelligent caching capabilities for complex data models an
 - **Cache Size Limits**: Configure maximum cache size in bytes or item count with automatic eviction
 - **Advanced Eviction Policies**: LRU, LFU, FIFO, MRU, Random, ARC, and 2Q strategies for optimal performance
 - **Performance Monitoring**: Built-in cache statistics and utilization tracking
+- **Cache Introspection**: Runtime visibility into cache implementation type, eviction policies, and capabilities
 
 ## Installation
 
@@ -57,6 +58,12 @@ await userCache.operations.set(userKey, updatedUser);
 const memoryCache = new MemoryCacheMap<User>(['user']);
 memoryCache.set(userKey, user);
 const cachedUser = memoryCache.get(userKey);
+
+// Get cache information for debugging or monitoring
+const cacheInfo = userCache.getCacheInfo();
+console.log(`Using ${cacheInfo.implementationType} cache`);
+console.log(`TTL support: ${cacheInfo.supportsTTL}`);
+console.log(`Eviction support: ${cacheInfo.supportsEviction}`);
 ```
 
 ## Configuration Options

package/dist/Aggregator.d.ts

@@ -1,25 +1,36 @@
 import { ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
 import { Cache } from "./Cache";
-import { CacheMap } from "./CacheMap";
+import { CacheEventEmitter } from "./events/CacheEventEmitter";
+import { CacheEventListener, CacheSubscription, CacheSubscriptionOptions } from "./events/CacheEventTypes";
 export interface Aggregator<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 Cache<V, S, L1, L2, L3, L4, L5> {
-    all: (query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
-    one: (query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V | null]>;
-    action: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body?: any) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
-    allAction: (action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
-    allFacet: (facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, any]>;
-    create: (item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
-    get: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V | null]>;
-    retrieve: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5> | null, V | null]>;
-    remove: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;
-    update: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Partial<Item<S, L1, L2, L3, L4, L5>>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
-    facet: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, any]>;
-    find: (finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
-    findOne: (finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
-    set: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Item<S, L1, L2, L3, L4, L5>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
-    reset: () => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>]>;
+    all: (query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V[]>;
+    one: (query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V | null>;
+    action: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body?: any) => Promise<V>;
+    allAction: (action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V[]>;
+    allFacet: (facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<any>;
+    create: (item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V>;
+    get: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<V | null>;
+    retrieve: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<V | null>;
+    remove: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<void>;
+    update: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Partial<Item<S, L1, L2, L3, L4, L5>>) => Promise<V>;
+    facet: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<any>;
+    find: (finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V[]>;
+    findOne: (finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V>;
+    set: (key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Item<S, L1, L2, L3, L4, L5>) => Promise<V>;
+    reset: () => Promise<void>;
     populate: (item: V) => Promise<V>;
     populateAggregate: (key: string, item: V) => Promise<void>;
     populateEvent: (key: string, item: V) => Promise<void>;
+    /** Event emitter for cache events */
+    eventEmitter: CacheEventEmitter<V, S, L1, L2, L3, L4, L5>;
+    /**
+     * 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 cache events
+     */
+    unsubscribe(subscription: CacheSubscription): boolean;
 }
 export interface CacheConfig {
     cache: any;

package/dist/Cache.d.ts

@@ -4,6 +4,26 @@ import { ClientApi } from "@fjell/client-api";
 import { CacheMap } from "./CacheMap";
 import { Operations } from "./Operations";
 import { Options } from "./Options";
+import { EvictionManager } from "./eviction/EvictionManager";
+import { TTLManager } from "./ttl/TTLManager";
+import { CacheEventEmitter } from "./events/CacheEventEmitter";
+import { CacheEventListener, CacheSubscription, CacheSubscriptionOptions } from "./events/CacheEventTypes";
+import { CacheStats, CacheStatsManager } from "./CacheStats";
+/**
+ * Cache configuration information exposed to client applications
+ */
+export interface CacheInfo {
+    /** The implementation type in format "<category>/<implementation>" */
+    implementationType: string;
+    /** The eviction policy being used (if any) */
+    evictionPolicy?: string;
+    /** Default TTL in milliseconds (if configured) */
+    defaultTTL?: number;
+    /** Whether TTL is supported by this implementation */
+    supportsTTL: boolean;
+    /** Whether eviction is supported by this implementation */
+    supportsEviction: boolean;
+}
 /**
  * The Cache interface extends the base Instance from @fjell/registry and adds cache operations
  * for interacting with cached data.
@@ -26,6 +46,41 @@ export interface Cache<V extends Item<S, L1, L2, L3, L4, L5>, S extends string,
     operations: Operations<V, S, L1, L2, L3, L4, L5>;
     /** Cache configuration options */
     options?: Options<V, S, L1, L2, L3, L4, L5>;
+    /** Event emitter for cache events */
+    eventEmitter: CacheEventEmitter<V, S, L1, L2, L3, L4, L5>;
+    /** Eviction manager for handling cache eviction independently of storage */
+    evictionManager: EvictionManager;
+    /** TTL manager for handling time-to-live independently of storage */
+    ttlManager: TTLManager;
+    /** Statistics manager for tracking cache metrics */
+    statsManager: CacheStatsManager;
+    /**
+     * Get cache configuration information for client applications
+     * Provides visibility into implementation type, eviction policy, TTL settings, and capabilities
+     */
+    getCacheInfo(): CacheInfo;
+    /**
+     * Get current cache statistics
+     * @returns Current cache statistics including hits, misses, requests, and subscription counts
+     */
+    getStats(): CacheStats;
+    /**
+     * Subscribe to cache events
+     * @param listener Function to call when events occur
+     * @param options Optional filters for which events to receive
+     * @returns Subscription object with unsubscribe method
+     */
+    subscribe(listener: CacheEventListener<V, S, L1, L2, L3, L4, L5>, options?: CacheSubscriptionOptions<S, L1, L2, L3, L4, L5>): CacheSubscription;
+    /**
+     * Unsubscribe from cache events
+     * @param subscription Subscription to cancel
+     * @returns True if subscription was found and cancelled
+     */
+    unsubscribe(subscription: CacheSubscription): boolean;
+    /**
+     * Destroy the cache and clean up all resources
+     */
+    destroy(): void;
 }
 export declare const createCache: <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>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, registry: Registry, options?: Partial<Options<V, S, L1, L2, L3, L4, L5>>) => Cache<V, S, L1, L2, L3, L4, L5>;
 export declare const isCache: (cache: any) => cache is Cache<any, any, any, any, any, any, any>;

package/dist/CacheContext.d.ts

@@ -2,6 +2,10 @@ import { Item } from "@fjell/core";
 import { ClientApi } from "@fjell/client-api";
 import { CacheMap } from "./CacheMap";
 import { Options } from "./Options";
+import { CacheEventEmitter } from "./events/CacheEventEmitter";
+import { TTLManager } from "./ttl/TTLManager";
+import { EvictionManager } from "./eviction/EvictionManager";
+import { CacheStatsManager } from "./CacheStats";
 /**
  * Context object that consolidates all cache-related parameters
  * passed to cache operations. This prevents cache concerns from
@@ -16,12 +20,16 @@ export interface CacheContext<V extends Item<S, L1, L2, L3, L4, L5>, S extends s
     pkType: S;
     /** Cache options including TTL configuration */
     options: Options<V, S, L1, L2, L3, L4, L5>;
-    /** TTL for individual items (from memoryConfig.ttl or ttl) */
-    itemTtl?: number;
-    /** TTL for query results (from ttl) */
-    queryTtl?: number;
+    /** Event emitter for cache events */
+    eventEmitter: CacheEventEmitter<V, S, L1, L2, L3, L4, L5>;
+    /** TTL manager for handling time-to-live independently of storage */
+    ttlManager: TTLManager;
+    /** Eviction manager for handling cache eviction independently of storage */
+    evictionManager: EvictionManager;
+    /** Statistics manager for tracking cache metrics */
+    statsManager: CacheStatsManager;
 }
 /**
  * Creates a CacheContext from the individual cache-related parameters
  */
-export declare const createCacheContext: <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>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, options: Options<V, S, L1, L2, L3, L4, L5>) => CacheContext<V, S, L1, L2, L3, L4, L5>;
+export declare const createCacheContext: <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>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, options: Options<V, S, L1, L2, L3, L4, L5>, eventEmitter: CacheEventEmitter<V, S, L1, L2, L3, L4, L5>, ttlManager: TTLManager, evictionManager: EvictionManager, statsManager: CacheStatsManager) => CacheContext<V, S, L1, L2, L3, L4, L5>;

package/dist/CacheMap.d.ts

@@ -1,4 +1,5 @@
 import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheItemMetadata, CacheMapMetadataProvider } from "./eviction/EvictionStrategy";
 /**
  * Abstract base interface for cache map implementations.
  * Defines the contract that all cache map implementations must follow.
@@ -7,18 +8,18 @@ import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from
  * @template S - The string literal type representing the model's key type
  * @template L1-L5 - Optional string literal types for location hierarchy levels
  */
-export declare abstract class CacheMap<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> {
+export declare abstract class CacheMap<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> implements CacheMapMetadataProvider {
     protected types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>;
-    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>);
     /**
-     * Retrieve an item by its key
+     * The implementation type identifier in the format "<category>/<implementation>"
+     * Examples: "memory/memory", "memory/enhanced", "browser/localStorage"
      */
-    abstract get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): V | null;
+    abstract readonly implementationType: string;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>);
     /**
-     * Retrieve an item by its key with TTL awareness
-     * Returns null if item doesn't exist or has expired based on the provided TTL
+     * Retrieve an item by its key
      */
-    abstract getWithTTL(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, ttl: number): V | null;
+    abstract get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<V | null>;
     /**
      * Store an item with its key
      */
@@ -26,7 +27,7 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Check if a key exists in the cache
      */
-    abstract includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): boolean;
+    abstract includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<boolean>;
     /**
      * Delete an item by its key
      */
@@ -34,19 +35,19 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Get all items in the specified locations
      */
-    abstract allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    abstract allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
     /**
      * Check if any items match the query in the specified locations
      */
-    abstract contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): boolean;
+    abstract contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<boolean>;
     /**
      * Get all items that match the query in the specified locations
      */
-    abstract queryIn(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    abstract queryIn(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
     /**
      * Create a clone of this cache map
      */
-    abstract clone(): CacheMap<V, S, L1, L2, L3, L4, L5>;
+    abstract clone(): Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;
     /**
      * Get all keys in the cache
      */
@@ -54,7 +55,7 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Get all values in the cache
      */
-    abstract values(): V[];
+    abstract values(): Promise<V[]>;
     /**
      * Clear all items from the cache
      */
@@ -62,11 +63,11 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Set a query result as a collection of item keys
      */
-    abstract setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[], ttl?: number): void;
+    abstract setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
     /**
      * Get a query result as a collection of item keys
      */
-    abstract getQueryResult(queryHash: string): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null;
+    abstract getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
     /**
      * Check if a query result exists in cache
      */
@@ -82,9 +83,51 @@ export declare abstract class CacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S
     /**
      * Invalidate all items in specified locations and clear related query results
      */
-    abstract invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): void;
+    abstract invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
     /**
      * Clear all query result cache entries
      */
     abstract clearQueryResults(): void;
+    /**
+     * Get metadata for a specific item
+     * @param key - Item key
+     * @returns Metadata if exists, null otherwise
+     */
+    abstract getMetadata(key: string): CacheItemMetadata | null;
+    /**
+     * Set metadata for a specific item
+     * @param key - Item key
+     * @param metadata - Metadata to store
+     */
+    abstract setMetadata(key: string, metadata: CacheItemMetadata): void;
+    /**
+     * Delete metadata for a specific item
+     * @param key - Item key
+     */
+    abstract deleteMetadata(key: string): void;
+    /**
+     * Get all metadata entries
+     * @returns Map of all metadata entries
+     */
+    abstract getAllMetadata(): Map<string, CacheItemMetadata>;
+    /**
+     * Clear all metadata
+     */
+    abstract clearMetadata(): void;
+    /**
+     * Get current cache size information
+     * @returns Object with current size metrics
+     */
+    abstract getCurrentSize(): {
+        itemCount: number;
+        sizeBytes: number;
+    };
+    /**
+     * Get cache size limits
+     * @returns Object with size limits (null means unlimited)
+     */
+    abstract getSizeLimits(): {
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    };
 }

package/dist/CacheStats.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cache statistics tracking interface
+ */
+export interface CacheStats {
+    /** Total number of cache requests (get/retrieve operations) */
+    numRequests: number;
+    /** Total number of cache misses (items not found in cache) */
+    numMisses: number;
+    /** Total number of cache hits (items found in cache) */
+    numHits: number;
+    /** Total number of subscription requests */
+    numSubscriptions: number;
+    /** Total number of unsubscription requests */
+    numUnsubscriptions: number;
+    /** Current number of active subscriptions */
+    activeSubscriptions: number;
+}
+/**
+ * Cache statistics manager that tracks various cache metrics
+ */
+export declare class CacheStatsManager {
+    private stats;
+    /**
+     * Increment the request counter
+     */
+    incrementRequests(): void;
+    /**
+     * Increment the cache hit counter
+     */
+    incrementHits(): void;
+    /**
+     * Increment the cache miss counter
+     */
+    incrementMisses(): void;
+    /**
+     * Increment the subscription counter
+     */
+    incrementSubscriptions(): void;
+    /**
+     * Increment the unsubscription counter
+     */
+    incrementUnsubscriptions(): void;
+    /**
+     * Get a copy of the current statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset all statistics to zero
+     */
+    reset(): void;
+}

package/dist/Operations.d.ts

@@ -2,70 +2,73 @@ import { ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
 import { ClientApi } from "@fjell/client-api";
 import { Coordinate } from "@fjell/registry";
 import { CacheMap } from "./CacheMap";
+import { CacheEventEmitter } from "./events/CacheEventEmitter";
 import { Options } from "./Options";
+import { TTLManager } from "./ttl/TTLManager";
+import { EvictionManager } from "./eviction/EvictionManager";
+import { CacheStatsManager } from "./CacheStats";
 export interface Operations<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> {
     /**
      * Retrieves all the items that match the query from cache or API.
      * Items are cached automatically after retrieval.
      */
-    all(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
+    all(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
     /**
      * Retrieves the first item that matches the query from cache or API.
      * Item is cached automatically after retrieval.
      */
-    one(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V | null]>;
+    one(query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V | null>;
     /**
      * Creates a new item via API and caches it.
      */
-    create(item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+    create(item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V>;
     /**
      * Gets an item by key from cache or API and caches it.
      */
-    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V | null]>;
+    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<V | null>;
     /**
      * Retrieves an item from cache if available, otherwise from API.
-     * Returns null as first element if item was already in cache.
      */
-    retrieve(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5> | null, V | null]>;
+    retrieve(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<V | null>;
     /**
      * Removes an item via API and from cache.
      */
-    remove(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;
+    remove(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<void>;
     /**
      * Updates an item via API and caches the result.
      */
-    update(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+    update(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Partial<Item<S, L1, L2, L3, L4, L5>>): Promise<V>;
     /**
      * Executes an action on an item via API and caches the result.
      */
-    action(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body?: any): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+    action(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body?: any): Promise<V>;
     /**
      * Executes an action on all items matching criteria via API and caches results.
      */
-    allAction(action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
+    allAction(action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
     /**
      * Executes a facet query on an item via API (pass-through, no caching).
      */
-    facet(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, any]>;
+    facet(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>): Promise<any>;
     /**
      * Executes a facet query on all items matching criteria via API (pass-through, no caching).
      */
-    allFacet(facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, any]>;
+    allFacet(facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<any>;
     /**
      * Finds items using a finder method via API and caches results.
      */
-    find(finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
+    find(finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
     /**
      * Finds a single item using a finder method via API and caches result.
      */
-    findOne(finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+    findOne(finder: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V>;
     /**
      * Sets an item directly in cache without API call.
      */
-    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Item<S, L1, L2, L3, L4, L5>): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Item<S, L1, L2, L3, L4, L5>): Promise<V>;
     /**
      * Resets the cache, clearing all cached items.
      */
-    reset(): Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>]>;
+    reset(): Promise<void>;
 }
-export declare const createOperations: <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>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, options: Options<V, S, L1, L2, L3, L4, L5>) => Operations<V, S, L1, L2, L3, L4, L5>;
+export declare const createOperations: <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>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, options: Options<V, S, L1, L2, L3, L4, L5>, eventEmitter: CacheEventEmitter<V, S, L1, L2, L3, L4, L5>, ttlManager: TTLManager, evictionManager: EvictionManager, statsManager: CacheStatsManager) => Operations<V, S, L1, L2, L3, L4, L5>;

package/dist/Options.d.ts

@@ -17,7 +17,7 @@ export interface CacheSizeConfig {
     maxSizeBytes?: string;
     /** Maximum number of items in cache */
     maxItems?: number;
-    /** Eviction policy to use when limits are exceeded (default: 'lru') */
+    /** @deprecated Eviction policy is now handled by Cache-level EvictionManager via evictionConfig */
     evictionPolicy?: EvictionPolicy;
 }
 /**
@@ -50,8 +50,6 @@ export interface WebStorageConfig {
 export interface MemoryConfig {
     /** Maximum number of items to keep in memory (default: unlimited) */
     maxItems?: number;
-    /** Time to live for cached items in milliseconds (default: unlimited) */
-    ttl?: number;
     /** Size configuration for memory cache */
     size?: CacheSizeConfig;
 }

package/dist/browser/AsyncIndexDBCacheMap.d.ts

@@ -28,7 +28,7 @@ export declare class AsyncIndexDBCacheMap<V extends Item<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>)[], ttl?: number): 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>;

package/dist/browser/IndexDBCacheMap.d.ts

@@ -1,6 +1,7 @@
 import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
 import { CacheMap } from "../CacheMap";
 import { AsyncIndexDBCacheMap } from "./AsyncIndexDBCacheMap";
+import { CacheItemMetadata } from "../eviction/EvictionStrategy";
 /**
  * Synchronous wrapper for IndexedDB CacheMap implementation.
  *
@@ -12,6 +13,7 @@ import { AsyncIndexDBCacheMap } from "./AsyncIndexDBCacheMap";
  * persistent storage benefits of 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";
     asyncCache: AsyncIndexDBCacheMap<V, S, L1, L2, L3, L4, L5>;
     private memoryCache;
     private syncInterval;
@@ -20,6 +22,7 @@ export declare class IndexDBCacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S ex
     private initializationPromise;
     private isInitialized;
     private readonly MAX_RETRY_ATTEMPTS;
+    private operationSequence;
     constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, dbName?: string, storeName?: string, version?: number);
     private initializeFromIndexedDB;
     private startPeriodicSync;
@@ -28,27 +31,39 @@ export declare class IndexDBCacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S ex
     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;
+    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(): IndexDBCacheMap<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<IndexDBCacheMap<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;
     /**
      * 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(): {
+        itemCount: number;
+        sizeBytes: number;
+    };
+    getSizeLimits(): {
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    };
 }