@fjell/cache 4.6.22 → 4.7.2

package/dist/CacheContext.d.ts

@@ -0,0 +1,35 @@
+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
+ * polluting operation signatures.
+ */
+export interface CacheContext<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> {
+    /** The client API for making requests */
+    api: ClientApi<V, S, L1, L2, L3, L4, L5>;
+    /** The cache map for storing and retrieving cached items */
+    cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>;
+    /** The primary key type */
+    pkType: S;
+    /** Cache options including TTL configuration */
+    options: Options<V, S, L1, L2, L3, L4, L5>;
+    /** 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>, 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,15 +1,133 @@
-import { AllItemTypeArrays, ComKey, Dictionary, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
-export declare 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> extends Dictionary<ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, V> {
-    private types;
-    private normalizedHashFunction;
-    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, map?: {
-        [key: string]: V;
-    });
-    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): V | null;
-    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(): CacheMap<V, S, L1, L2, L3, L4, L5>;
+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.
+ *
+ * @template V - The type of the data model item, extending Item
+ * @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> implements CacheMapMetadataProvider {
+    protected types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>;
+    /**
+     * The implementation type identifier in the format "<category>/<implementation>"
+     * Examples: "memory/memory", "memory/enhanced", "browser/localStorage"
+     */
+    abstract readonly implementationType: string;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>);
+    /**
+     * Retrieve an item by its key
+     */
+    abstract get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<V | null>;
+    /**
+     * Store an item with its key
+     */
+    abstract set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): void;
+    /**
+     * Check if a key exists in the cache
+     */
+    abstract includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<boolean>;
+    /**
+     * Delete an item by its key
+     */
+    abstract delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    /**
+     * Get all items in the specified locations
+     */
+    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> | []): Promise<boolean>;
+    /**
+     * Get all items that match the query in the specified locations
+     */
+    abstract queryIn(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    /**
+     * Create a clone of this cache map
+     */
+    abstract clone(): Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;
+    /**
+     * Get all keys in the cache
+     */
+    abstract keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    /**
+     * Get all values in the cache
+     */
+    abstract values(): Promise<V[]>;
+    /**
+     * Clear all items from the cache
+     */
+    abstract clear(): 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;
+    /**
+     * Get a query result as a collection of item keys
+     */
+    abstract getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
+    /**
+     * Check if a query result exists in cache
+     */
+    abstract hasQueryResult(queryHash: string): boolean;
+    /**
+     * Delete a specific query result
+     */
+    abstract deleteQueryResult(queryHash: string): void;
+    /**
+     * Invalidate all cached items by their keys
+     */
+    abstract invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    /**
+     * Invalidate all items in specified locations and clear related query results
+     */
+    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/Instance.d.ts

@@ -6,12 +6,14 @@ import { Cache } from "./Cache";
  * The Cache Instance interface represents a cache model instance that extends the base Instance
  * from @fjell/registry and adds cache operations for interacting with cached data.
  *
- * This is an alias for the Cache interface since Cache now extends Instance directly.
+ * This is a type alias for the Cache interface. Both Cache and Instance refer to the same
+ * cache interface - Instance exists for backward compatibility and consistency with other
+ * Fjell packages that export Instance types.
  *
  * @template V - The type of the data model item, extending Item
  * @template S - The string literal type representing the model's key type
  * @template L1-L5 - Optional string literal types for location hierarchy levels
  */
 export type Instance<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> = Cache<V, S, L1, L2, L3, L4, L5>;
-export declare const createInstance: <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>(registry: Registry, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, api: ClientApi<V, S, L1, L2, L3, L4, L5>) => Instance<V, S, L1, L2, L3, L4, L5>;
+export declare const createInstance: <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>(registry: Registry, coordinate: Coordinate<S, L1, L2, L3, L4, L5>, api: ClientApi<V, S, L1, L2, L3, L4, L5>, options?: Partial<import("./Options").Options<V, S, L1, L2, L3, L4, L5>>) => Instance<V, S, L1, L2, L3, L4, L5>;
 export declare const isInstance: (instance: any) => instance is Instance<any, any, any, any, any, any, any>;

package/dist/InstanceFactory.d.ts

@@ -1,8 +1,9 @@
 import { Item } from "@fjell/core";
 import { ClientApi } from "@fjell/client-api";
 import { InstanceFactory as BaseInstanceFactory } from "@fjell/registry";
-export type InstanceFactory<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>) => BaseInstanceFactory<S, L1, L2, L3, L4, L5>;
+import { Options } from "./Options";
+export type InstanceFactory<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>, options?: Partial<Options<V, S, L1, L2, L3, L4, L5>>) => BaseInstanceFactory<S, L1, L2, L3, L4, L5>;
 /**
  * Factory function for creating cache instances
  */
-export declare const createInstanceFactory: <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>) => BaseInstanceFactory<S, L1, L2, L3, L4, L5>;
+export declare const createInstanceFactory: <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>, options?: Partial<Options<V, S, L1, L2, L3, L4, L5>>) => BaseInstanceFactory<S, L1, L2, L3, L4, L5>;

package/dist/Operations.d.ts

@@ -2,69 +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) => 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

@@ -0,0 +1,98 @@
+import { Item } from '@fjell/core';
+import { CacheMap } from './CacheMap';
+import { EvictionStrategyConfigs } from './eviction/EvictionStrategyConfig';
+/**
+ * Available cache types for the cache instance
+ */
+export type CacheType = 'memory' | 'localStorage' | 'sessionStorage' | 'indexedDB' | 'asyncIndexedDB' | 'custom';
+/**
+ * Cache eviction policies for when cache size limits are reached
+ */
+export type EvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'mru' | 'random' | 'arc' | '2q';
+/**
+ * Cache size configuration supporting bytes and item count limits
+ */
+export interface CacheSizeConfig {
+    /** Maximum cache size in bytes (e.g., '100', '5KB', '10MB', '2GB', '1KiB', '512MiB') */
+    maxSizeBytes?: string;
+    /** Maximum number of items in cache */
+    maxItems?: number;
+    /** @deprecated Eviction policy is now handled by Cache-level EvictionManager via evictionConfig */
+    evictionPolicy?: EvictionPolicy;
+}
+/**
+ * Configuration for IndexedDB-based cache maps
+ */
+export interface IndexedDBConfig {
+    /** Database name (default: 'fjell-cache') */
+    dbName?: string;
+    /** Database version (default: 1) */
+    version?: number;
+    /** Object store name (default: 'cache') */
+    storeName?: string;
+    /** Size configuration for IndexedDB cache */
+    size?: CacheSizeConfig;
+}
+/**
+ * Configuration for localStorage/sessionStorage-based cache maps
+ */
+export interface WebStorageConfig {
+    /** Key prefix for storage items (default: 'fjell-cache:') */
+    keyPrefix?: string;
+    /** Whether to compress stored data (default: false) */
+    compress?: boolean;
+    /** Size configuration for web storage cache */
+    size?: CacheSizeConfig;
+}
+/**
+ * Configuration for memory-based cache maps
+ */
+export interface MemoryConfig {
+    /** Maximum number of items to keep in memory (default: unlimited) */
+    maxItems?: number;
+    /** Size configuration for memory cache */
+    size?: CacheSizeConfig;
+}
+/**
+ * Factory function for creating custom cache map instances
+ */
+export type CacheMapFactory<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> = (kta: [S, ...string[]]) => CacheMap<V, S, L1, L2, L3, L4, L5>;
+/**
+ * Cache options interface for configuring cache instances
+ */
+export interface Options<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> {
+    /** The type of cache to use */
+    cacheType: CacheType;
+    /** Configuration for IndexedDB cache types */
+    indexedDBConfig?: IndexedDBConfig;
+    /** Configuration for web storage cache types */
+    webStorageConfig?: WebStorageConfig;
+    /** Configuration for memory cache type */
+    memoryConfig?: MemoryConfig;
+    /** Custom cache map factory for 'custom' cache type */
+    customCacheMapFactory?: CacheMapFactory<V, S, L1, L2, L3, L4, L5>;
+    /** Eviction strategy configuration - independent of cache implementation */
+    evictionConfig?: EvictionStrategyConfigs;
+    /** Whether to enable debug logging for cache operations */
+    enableDebugLogging?: boolean;
+    /** Whether to automatically sync with the API on cache misses */
+    autoSync?: boolean;
+    /** Cache expiration time in milliseconds (default: unlimited) */
+    ttl?: number;
+    /** Maximum number of retry attempts for failed operations */
+    maxRetries?: number;
+    /** Delay between retry attempts in milliseconds */
+    retryDelay?: number;
+}
+/**
+ * Create cache options with defaults
+ */
+export declare const createOptions: <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>(cacheOptions?: Partial<Options<V, S, L1, L2, L3, L4, L5>>) => Options<V, S, L1, L2, L3, L4, L5>;
+/**
+ * Create a cache map instance based on the provided options
+ */
+export declare const createCacheMap: <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>(kta: [S, ...string[]], options: Options<V, S, L1, L2, L3, L4, L5>) => CacheMap<V, S, L1, L2, L3, L4, L5>;
+/**
+ * Validate cache options
+ */
+export declare const validateOptions: <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>(options: Options<V, S, L1, L2, L3, L4, L5>) => void;

package/dist/browser/AsyncIndexDBCacheMap.d.ts

@@ -0,0 +1,38 @@
+import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+/**
+ * IndexedDB implementation of CacheMap for browser environments.
+ * Data persists long-term with much larger storage limits than localStorage/sessionStorage.
+ *
+ * Note: IndexedDB is asynchronous and can store structured data.
+ * Storage limit is hundreds of MB or more depending on browser and user.
+ * This implementation uses promises for all operations.
+ */
+export declare class AsyncIndexDBCacheMap<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> {
+    protected types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>;
+    private dbName;
+    private storeName;
+    private version;
+    private normalizedHashFunction;
+    private dbPromise;
+    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>;
+    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(): AsyncIndexDBCacheMap<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>;
+}

package/dist/browser/IndexDBCacheMap.d.ts

@@ -0,0 +1,69 @@
+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.
+ *
+ * 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.
+ *
+ * Note: This class maintains synchronous compatibility while providing
+ * 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;
+    private readonly SYNC_INTERVAL_MS;
+    private pendingSyncOperations;
+    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;
+    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;
+    includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<boolean>;
+    delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<boolean>;
+    queryIn(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    clone(): Promise<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;
+    getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
+    hasQueryResult(queryHash: string): boolean;
+    deleteQueryResult(queryHash: string): void;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
+    clearQueryResults(): void;
+    /**
+     * 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;
+    };
+}

package/dist/browser/LocalStorageCacheMap.d.ts

@@ -0,0 +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 readonly MAX_RETRY_ATTEMPTS;
+    private readonly AGGRESSIVE_CLEANUP_PERCENTAGE;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, keyPrefix?: string);
+    private getStorageKey;
+    private isQuotaExceededError;
+    private getAllKeysStartingWith;
+    private tryCleanupOldEntries;
+    private collectCacheEntries;
+    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;
+    includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<boolean>;
+    delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<boolean>;
+    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    clone(): Promise<LocalStorageCacheMap<V, S, L1, L2, L3, L4, L5>>;
+    private parseStorageEntry;
+    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    values(): Promise<V[]>;
+    clear(): void;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    getQueryResult(queryHash: string): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null>;
+    hasQueryResult(queryHash: string): boolean;
+    deleteQueryResult(queryHash: string): void;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
+    clearQueryResults(): void;
+    getMetadata(key: string): CacheItemMetadata | null;
+    setMetadata(key: string, metadata: CacheItemMetadata): void;
+    deleteMetadata(key: string): void;
+    getAllMetadata(): Map<string, CacheItemMetadata>;
+    clearMetadata(): void;
+    getCurrentSize(): {
+        itemCount: number;
+        sizeBytes: number;
+    };
+    getSizeLimits(): {
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    };
+}