@fjell/cache 4.6.22 → 4.7.0

package/dist/CacheMap.d.ts

@@ -1,15 +1,90 @@
-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";
+/**
+ * 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> {
+    protected types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>;
+    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>): V | null;
+    /**
+     * Retrieve an item by its key with TTL awareness
+     * Returns null if item doesn't exist or has expired based on the provided TTL
+     */
+    abstract getWithTTL(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, ttl: number): 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>): 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> | []): V[];
+    /**
+     * Check if any items match the query in the specified locations
+     */
+    abstract contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): boolean;
+    /**
+     * Get all items that match the query in the specified locations
+     */
+    abstract queryIn(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    /**
+     * Create a clone of this cache map
+     */
+    abstract clone(): 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(): 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>)[], ttl?: number): 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;
+    /**
+     * 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> | []): void;
+    /**
+     * Clear all query result cache entries
+     */
+    abstract clearQueryResults(): 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,6 +2,7 @@ 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 { Options } from "./Options";
 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.
@@ -67,4 +68,4 @@ export interface Operations<V extends Item<S, L1, L2, L3, L4, L5>, S extends str
      */
     reset(): Promise<[CacheMap<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) => 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>) => Operations<V, S, L1, L2, L3, L4, L5>;

package/dist/Options.d.ts

@@ -0,0 +1,100 @@
+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;
+    /** Eviction policy to use when limits are exceeded (default: 'lru') */
+    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;
+    /** Time to live for cached items in milliseconds (default: unlimited) */
+    ttl?: 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>)[], ttl?: number): 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,54 @@
+import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheMap } from "../CacheMap";
+import { AsyncIndexDBCacheMap } from "./AsyncIndexDBCacheMap";
+/**
+ * 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> {
+    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;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, dbName?: string, storeName?: string, version?: number);
+    private initializeFromIndexedDB;
+    private startPeriodicSync;
+    private syncToIndexedDB;
+    private processPendingOperations;
+    private queueForSync;
+    private queueDeleteForSync;
+    private queueClearForSync;
+    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): V | null;
+    getWithTTL(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, ttl: number): V | null;
+    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): void;
+    includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): boolean;
+    delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): boolean;
+    queryIn(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    clone(): IndexDBCacheMap<V, S, L1, L2, L3, L4, L5>;
+    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    values(): V[];
+    clear(): void;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[], ttl?: number): void;
+    getQueryResult(queryHash: string): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null;
+    hasQueryResult(queryHash: string): boolean;
+    deleteQueryResult(queryHash: string): void;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): void;
+    clearQueryResults(): void;
+    /**
+     * Clean up resources when the cache is no longer needed
+     */
+    destroy(): void;
+}

package/dist/browser/LocalStorageCacheMap.d.ts

@@ -0,0 +1,43 @@
+import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheMap } from "../CacheMap";
+/**
+ * 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.
+ */
+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> {
+    private keyPrefix;
+    private normalizedHashFunction;
+    private fallbackCache;
+    private quotaExceeded;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, keyPrefix?: string);
+    private getStorageKey;
+    private initializeFallbackCache;
+    private isQuotaExceededError;
+    private tryCleanupOldEntries;
+    private collectCacheEntries;
+    private removeOldestEntries;
+    private getAllStorageKeys;
+    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): V | null;
+    getWithTTL(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, ttl: number): V | null;
+    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): void;
+    includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): boolean;
+    delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): boolean;
+    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    clone(): LocalStorageCacheMap<V, S, L1, L2, L3, L4, L5>;
+    private parseStorageEntry;
+    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    values(): V[];
+    clear(): void;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[], ttl?: number): void;
+    getQueryResult(queryHash: string): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null;
+    hasQueryResult(queryHash: string): boolean;
+    deleteQueryResult(queryHash: string): void;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): void;
+    clearQueryResults(): void;
+}

package/dist/browser/SessionStorageCacheMap.d.ts

@@ -0,0 +1,35 @@
+import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheMap } from "../CacheMap";
+/**
+ * SessionStorage implementation of CacheMap for browser environments.
+ * Data persists only for the current browser tab/session.
+ *
+ * Note: SessionStorage has a ~5MB limit and stores strings only.
+ * Data is synchronous but is lost when the tab is closed.
+ */
+export declare class SessionStorageCacheMap<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends CacheMap<V, S, L1, L2, L3, L4, L5> {
+    private keyPrefix;
+    private normalizedHashFunction;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, keyPrefix?: string);
+    private getStorageKey;
+    private getAllStorageKeys;
+    get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): V | null;
+    getWithTTL(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, ttl: number): V | null;
+    set(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, value: V): void;
+    includesKey(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): boolean;
+    delete(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): void;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): boolean;
+    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): V[];
+    clone(): SessionStorageCacheMap<V, S, L1, L2, L3, L4, L5>;
+    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    values(): V[];
+    clear(): void;
+    setQueryResult(queryHash: string, itemKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[], ttl?: number): void;
+    getQueryResult(queryHash: string): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[] | null;
+    hasQueryResult(queryHash: string): boolean;
+    deleteQueryResult(queryHash: string): void;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): void;
+    clearQueryResults(): void;
+}

package/dist/eviction/EvictionStrategy.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Metadata for tracking cache item usage patterns
+ */
+export interface CacheItemMetadata {
+    /** When the item was first added to cache */
+    addedAt: number;
+    /** When the item was last accessed */
+    lastAccessedAt: number;
+    /** Number of times the item has been accessed */
+    accessCount: number;
+    /** Estimated size of the item in bytes */
+    estimatedSize: number;
+    /** Item key for identification */
+    key: string;
+    /** Frequency score with decay applied (for LFU with sketching) */
+    frequencyScore?: number;
+    /** Last time frequency was updated (for decay calculations) */
+    lastFrequencyUpdate?: number;
+    /** Raw frequency count before decay */
+    rawFrequency?: number;
+}
+/**
+ * Abstract base class for cache eviction strategies.
+ * Defines the core contract that all eviction policies must implement.
+ */
+export declare abstract class EvictionStrategy {
+    /**
+     * Select which item should be evicted based on the strategy
+     * @param items - Map of items with their metadata
+     * @returns Key of the item to evict, or null if no eviction needed
+     */
+    abstract selectForEviction(items: Map<string, CacheItemMetadata>): string | null;
+    /**
+     * Update metadata when an item is accessed
+     * @param key - Item key
+     * @param metadata - Current metadata
+     */
+    abstract onItemAccessed(key: string, metadata: CacheItemMetadata): void;
+    /**
+     * Update metadata when an item is added
+     * @param key - Item key
+     * @param metadata - Initial metadata
+     */
+    abstract onItemAdded(key: string, metadata: CacheItemMetadata): void;
+    /**
+     * Clean up when an item is removed
+     * @param key - Item key (optional for some strategies)
+     */
+    abstract onItemRemoved(key?: string): void;
+}

package/dist/eviction/EvictionStrategyConfig.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Base configuration interface for eviction strategies
+ */
+export interface EvictionStrategyConfig {
+    /** Strategy type identifier */
+    readonly type: string;
+}
+/**
+ * Configuration for LFU eviction strategy with frequency sketching
+ */
+export interface LFUConfig extends EvictionStrategyConfig {
+    readonly type: 'lfu';
+    /** Decay factor for aging frequency counts (0.0 to 1.0, default: 0.1) */
+    decayFactor?: number;
+    /** Frequency decay interval in milliseconds (default: 60000) */
+    decayInterval?: number;
+    /** Width of the Count-Min Sketch (default: 1024) */
+    sketchWidth?: number;
+    /** Depth of the Count-Min Sketch (default: 4) */
+    sketchDepth?: number;
+    /** Whether to use probabilistic counting (default: true) */
+    useProbabilisticCounting?: boolean;
+    /** Minimum frequency threshold before decay (default: 1) */
+    minFrequencyThreshold?: number;
+}
+/**
+ * Configuration for LRU eviction strategy
+ */
+export interface LRUConfig extends EvictionStrategyConfig {
+    readonly type: 'lru';
+}
+/**
+ * Configuration for FIFO eviction strategy
+ */
+export interface FIFOConfig extends EvictionStrategyConfig {
+    readonly type: 'fifo';
+}
+/**
+ * Configuration for MRU eviction strategy
+ */
+export interface MRUConfig extends EvictionStrategyConfig {
+    readonly type: 'mru';
+}
+/**
+ * Configuration for Random eviction strategy
+ */
+export interface RandomConfig extends EvictionStrategyConfig {
+    readonly type: 'random';
+}
+/**
+ * Configuration for ARC eviction strategy
+ */
+export interface ARCConfig extends EvictionStrategyConfig {
+    readonly type: 'arc';
+    /** Maximum cache size for ARC calculations */
+    maxCacheSize?: number;
+    /** Frequency threshold for classifying items as "frequent" vs "recent" (default: 2) */
+    frequencyThreshold?: number;
+    /** Use enhanced frequency tracking with decay (default: true) */
+    useEnhancedFrequency?: boolean;
+    /** Decay factor for aging frequency scores (default: 0.05) */
+    frequencyDecayFactor?: number;
+    /** Decay interval for frequency scores (default: 600000 - 10 minutes) */
+    frequencyDecayInterval?: number;
+    /** Use frequency-weighted selection within T1/T2 lists (default: true) */
+    useFrequencyWeightedSelection?: boolean;
+    /** Adaptive learning rate for target size adjustments (default: 1.0) */
+    adaptiveLearningRate?: number;
+}
+/**
+ * Configuration for 2Q eviction strategy
+ */
+export interface TwoQueueConfig extends EvictionStrategyConfig {
+    readonly type: '2q';
+    /** Maximum cache size for 2Q calculations */
+    maxCacheSize?: number;
+    /** Use frequency-based promotion from recent to hot queue (default: true) */
+    useFrequencyPromotion?: boolean;
+    /** Minimum access frequency required for promotion to hot queue (default: 2) */
+    promotionThreshold?: number;
+    /** Decay factor for aging frequency scores in hot queue (default: 0.05) */
+    hotQueueDecayFactor?: number;
+    /** Decay interval for hot queue frequency scores (default: 300000 - 5 minutes) */
+    hotQueueDecayInterval?: number;
+    /** Use frequency-weighted LRU in hot queue instead of pure LRU (default: true) */
+    useFrequencyWeightedLRU?: boolean;
+}
+/**
+ * Union type for all eviction strategy configurations
+ */
+export type EvictionStrategyConfigs = LFUConfig | LRUConfig | FIFOConfig | MRUConfig | RandomConfig | ARCConfig | TwoQueueConfig;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_LFU_CONFIG: LFUConfig;
+export declare const DEFAULT_ARC_CONFIG: ARCConfig;
+export declare const DEFAULT_TWO_QUEUE_CONFIG: TwoQueueConfig;

package/dist/eviction/EvictionStrategyFactory.d.ts

@@ -0,0 +1,12 @@
+import { EvictionPolicy } from '../Options';
+import { EvictionStrategy } from './EvictionStrategy';
+import { EvictionStrategyConfigs } from './EvictionStrategyConfig';
+/**
+ * Factory function to create eviction strategy instances with configuration
+ */
+export declare function createEvictionStrategy(policy: EvictionPolicy, maxCacheSize?: number, config?: EvictionStrategyConfigs): EvictionStrategy;
+/**
+ * Factory function for backwards compatibility
+ * @deprecated Use createEvictionStrategy with config parameter instead
+ */
+export declare function createEvictionStrategyLegacy(policy: EvictionPolicy, maxCacheSize?: number): EvictionStrategy;

package/dist/eviction/EvictionStrategyValidation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Validation functions for eviction strategy configurations
+ */
+import { ARCConfig, EvictionStrategyConfigs, LFUConfig, TwoQueueConfig } from './EvictionStrategyConfig';
+/**
+ * Sanitizes LFU configuration parameters, correcting invalid values
+ */
+export declare function sanitizeLFUConfig(config: Partial<LFUConfig>): Partial<LFUConfig>;
+/**
+ * Validates LFU configuration parameters (after sanitization)
+ */
+export declare function validateLFUConfig(config: Partial<LFUConfig>): void;
+/**
+ * Sanitizes ARC configuration parameters, correcting invalid values
+ */
+export declare function sanitizeARCConfig(config: Partial<ARCConfig>): Partial<ARCConfig>;
+/**
+ * Validates ARC configuration parameters (after sanitization)
+ */
+export declare function validateARCConfig(config: Partial<ARCConfig>): void;
+/**
+ * Sanitizes TwoQueue configuration parameters, correcting invalid values
+ */
+export declare function sanitizeTwoQueueConfig(config: Partial<TwoQueueConfig>): Partial<TwoQueueConfig>;
+/**
+ * Validates TwoQueue configuration parameters (after sanitization)
+ */
+export declare function validateTwoQueueConfig(config: Partial<TwoQueueConfig>): void;
+/**
+ * Validates any eviction strategy configuration
+ */
+export declare function validateEvictionStrategyConfig(config: Partial<EvictionStrategyConfigs>): void;
+/**
+ * Creates a validated configuration with defaults applied and invalid values sanitized
+ */
+export declare function createValidatedConfig<T extends EvictionStrategyConfigs>(baseConfig: T, userConfig: Partial<T>): T;

package/dist/eviction/index.d.ts

@@ -0,0 +1,9 @@
+export { EvictionStrategy, CacheItemMetadata } from './EvictionStrategy';
+export { createEvictionStrategy } from './EvictionStrategyFactory';
+export { LRUEvictionStrategy } from './strategies/LRUEvictionStrategy';
+export { LFUEvictionStrategy } from './strategies/LFUEvictionStrategy';
+export { FIFOEvictionStrategy } from './strategies/FIFOEvictionStrategy';
+export { MRUEvictionStrategy } from './strategies/MRUEvictionStrategy';
+export { RandomEvictionStrategy } from './strategies/RandomEvictionStrategy';
+export { ARCEvictionStrategy } from './strategies/ARCEvictionStrategy';
+export { TwoQueueEvictionStrategy } from './strategies/TwoQueueEvictionStrategy';