@fjell/cache 4.6.22 → 4.7.2

package/dist/memory/EnhancedMemoryCacheMap.d.ts

@@ -0,0 +1,81 @@
+import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheMap } from "../CacheMap";
+import { CacheSizeConfig } from "../Options";
+import { CacheItemMetadata } from "../eviction";
+/**
+ * Enhanced in-memory implementation of CacheMap with size limits and eviction policies.
+ * Supports byte-based and item-count limits with configurable eviction strategies.
+ */
+export declare class EnhancedMemoryCacheMap<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 = "memory/enhanced";
+    private map;
+    private normalizedHashFunction;
+    private queryResultCache;
+    private currentSizeBytes;
+    private currentItemCount;
+    private queryResultsCacheSize;
+    private readonly maxSizeBytes?;
+    private readonly maxItems?;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, sizeConfig?: CacheSizeConfig, initialData?: {
+        [key: string]: V;
+    });
+    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;
+    private deleteInternal;
+    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    values(): Promise<V[]>;
+    clear(): 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<CacheMap<V, S, L1, L2, L3, L4, L5>>;
+    /**
+     * Get current cache statistics
+     */
+    getStats(): {
+        currentSizeBytes: number;
+        currentItemCount: number;
+        maxSizeBytes?: number;
+        maxItems?: number;
+        utilizationPercent: {
+            bytes?: number;
+            items?: number;
+        };
+    };
+    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;
+    clearQueryResults(): void;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
+    private filterQueriesReferencingKeys;
+    private invalidateQueriesReferencingKeys;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
+    /**
+     * Add query result to size tracking
+     */
+    private addQueryResultToSizeTracking;
+    /**
+     * Remove query result from size tracking
+     */
+    private removeQueryResultFromSizeTracking;
+    /**
+     * Get total cache size including query results
+     */
+    getTotalSizeBytes(): number;
+    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/memory/MemoryCacheMap.d.ts

@@ -0,0 +1,48 @@
+import { AllItemTypeArrays, ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { CacheMap } from "../CacheMap";
+import { CacheItemMetadata } from "../eviction/EvictionStrategy";
+/**
+ * In-memory implementation of CacheMap using a plain object as the underlying storage.
+ * This implementation stores all data in memory and will be lost when the application restarts.
+ */
+export declare class MemoryCacheMap<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 = "memory/memory";
+    private map;
+    private normalizedHashFunction;
+    private queryResultCache;
+    private metadataMap;
+    constructor(types: AllItemTypeArrays<S, L1, L2, L3, L4, L5>, initialData?: {
+        [key: string]: V;
+    });
+    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;
+    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
+    values(): Promise<V[]>;
+    clear(): 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<MemoryCacheMap<V, S, L1, L2, L3, L4, L5>>;
+    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;
+    };
+}

package/dist/normalization.d.ts

@@ -0,0 +1,19 @@
+import { ItemQuery, LocKeyArray } from "@fjell/core";
+export declare const normalizeKeyValue: (value: string | number) => string;
+export declare const createNormalizedHashFunction: <T>() => (key: T) => string;
+export declare const isLocKeyArrayEqual: (a: any[], b: any[]) => boolean;
+export declare const normalizeLocKeyItem: (item: any) => any;
+/**
+ * Interface for storing query results
+ */
+export interface QueryCacheEntry {
+    itemKeys: (any)[];
+}
+/**
+ * Generate a safe hash for all/one query parameters
+ */
+export declare const createQueryHash: <S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(pkType: S, query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []) => string;
+/**
+ * Generate a safe hash for find/findOne query parameters
+ */
+export declare const createFinderHash: <L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(finder: string, params: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations: LocKeyArray<L1, L2, L3, L4, L5> | []) => string;

package/dist/ops/action.d.ts

@@ -1,4 +1,3 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const action: <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, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body?: any) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+import { CacheContext } from "../CacheContext";
+export declare const action: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body: any | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V]>;

package/dist/ops/all.d.ts

@@ -1,4 +1,3 @@
 import { Item, ItemQuery, LocKeyArray } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const all: <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, query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
+import { CacheContext } from "../CacheContext";
+export declare const all: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(query: ItemQuery | undefined, locations: (LocKeyArray<L1, L2, L3, L4, L5> | []) | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V[]]>;

package/dist/ops/allAction.d.ts

@@ -1,4 +1,3 @@
 import { Item, LocKeyArray } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const allAction: <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, action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V[]]>;
+import { CacheContext } from "../CacheContext";
+export declare const allAction: <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>(action: string, body: any | undefined, locations: (LocKeyArray<L1, L2, L3, L4, L5> | []) | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V[]]>;

package/dist/ops/allFacet.d.ts

@@ -1,4 +1,3 @@
 import { Item, LocKeyArray } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const allFacet: <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>, 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]>;
+import { CacheContext } from "../CacheContext";
+export declare const allFacet: <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>(facet: string, params: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>> | undefined, locations: (LocKeyArray<L1, L2, L3, L4, L5> | []) | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<any>;

package/dist/ops/create.d.ts

@@ -1,4 +1,3 @@
 import { Item, LocKeyArray } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const create: <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, v: 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]>;
+import { CacheContext } from "../CacheContext";
+export declare const create: <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>(v: Partial<Item<S, L1, L2, L3, L4, L5>>, locations: (LocKeyArray<L1, L2, L3, L4, L5> | []) | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V]>;

package/dist/ops/facet.d.ts

@@ -1,4 +1,3 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const facet: <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>, 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]>;
+import { CacheContext } from "../CacheContext";
+export declare const facet: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, facet: string, params: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>> | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<any>;

package/dist/ops/find.d.ts

@@ -1,4 +1,3 @@
 import { Item, LocKeyArray } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const find: <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, 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[]]>;
+import { CacheContext } from "../CacheContext";
+export declare const find: <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>(finder: string, params: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>> | undefined, locations: (LocKeyArray<L1, L2, L3, L4, L5> | []) | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V[]]>;

package/dist/ops/findOne.d.ts

@@ -1,4 +1,3 @@
 import { Item, LocKeyArray } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const findOne: <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, finder: string, finderParams?: 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]>;
+import { CacheContext } from "../CacheContext";
+export declare const findOne: <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>(finder: string, finderParams: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>> | undefined, locations: (LocKeyArray<L1, L2, L3, L4, L5> | []) | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V]>;

package/dist/ops/get.d.ts

@@ -1,4 +1,4 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const get: <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, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V | null]>;
+import { CacheContext } from "../CacheContext";
+export declare const cleanup: () => void;
+export declare const get: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V | null]>;

package/dist/ops/one.d.ts

@@ -1,4 +1,3 @@
 import { Item, ItemQuery, LocKeyArray } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const one: <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, query?: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V | null]>;
+import { CacheContext } from "../CacheContext";
+export declare const one: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(query: ItemQuery | undefined, locations: (LocKeyArray<L1, L2, L3, L4, L5> | []) | undefined, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V | null]>;

package/dist/ops/remove.d.ts

@@ -1,4 +1,3 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const remove: <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>, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;
+import { CacheContext } from "../CacheContext";
+export declare const remove: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<CacheContext<V, S, L1, L2, L3, L4, L5>>;

package/dist/ops/reset.d.ts

@@ -1,4 +1,5 @@
 import { Item } from "@fjell/core";
 import { CacheMap } from "../CacheMap";
+import { Options } from "../Options";
 import { Coordinate } from "@fjell/registry";
-export declare const reset: <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>(coordinate: Coordinate<S, L1, L2, L3, L4, L5>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>]>;
+export declare const reset: <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>(coordinate: Coordinate<S, L1, L2, L3, L4, L5>, options: Options<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>]>;

package/dist/ops/retrieve.d.ts

@@ -1,4 +1,3 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
-import { CacheMap } from "../CacheMap";
-import { ClientApi } from "@fjell/client-api";
-export declare const retrieve: <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, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5> | null, V | null]>;
+import { CacheContext } from "../CacheContext";
+export declare const retrieve: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5> | null, V | null]>;

package/dist/ops/set.d.ts

@@ -1,3 +1,3 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
-import { CacheMap } from "../CacheMap";
-export declare const set: <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>(cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, v: Item<S, L1, L2, L3, L4, L5>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+import { CacheContext } from "../CacheContext";
+export declare const set: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, v: Item<S, L1, L2, L3, L4, L5>, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V]>;

package/dist/ops/update.d.ts

@@ -1,4 +1,3 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
-import { ClientApi } from "@fjell/client-api";
-import { CacheMap } from "../CacheMap";
-export declare const update: <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, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, v: Partial<Item<S, L1, L2, L3, L4, L5>>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;
+import { CacheContext } from "../CacheContext";
+export declare const update: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, v: Partial<Item<S, L1, L2, L3, L4, L5>>, context: CacheContext<V, S, L1, L2, L3, L4, L5>) => Promise<[CacheContext<V, S, L1, L2, L3, L4, L5>, V]>;

package/dist/ttl/TTLManager.d.ts

@@ -0,0 +1,100 @@
+import { CacheItemMetadata, CacheMapMetadataProvider } from '../eviction/EvictionStrategy';
+/**
+ * Configuration for TTL behavior
+ */
+export interface TTLConfig {
+    /** Default TTL in milliseconds for all items */
+    defaultTTL?: number;
+    /** Whether to automatically clean up expired items */
+    autoCleanup?: boolean;
+    /** Interval for automatic cleanup in milliseconds */
+    cleanupInterval?: number;
+    /** Whether to validate TTL on access */
+    validateOnAccess?: boolean;
+}
+/**
+ * TTL-aware item wrapper that extends cache metadata
+ */
+export interface TTLItemMetadata extends CacheItemMetadata {
+    /** Expiration timestamp (addedAt + TTL) */
+    expiresAt?: number;
+    /** TTL value used for this specific item */
+    ttl?: number;
+}
+/**
+ * Manages TTL (Time To Live) logic independently of CacheMap implementations.
+ * This allows any CacheMap to support TTL without implementing TTL-specific logic.
+ */
+export declare class TTLManager {
+    private config;
+    private cleanupTimer?;
+    constructor(config?: TTLConfig);
+    /**
+     * Check if TTL is enabled
+     */
+    isTTLEnabled(): boolean;
+    /**
+     * Get the default TTL value
+     */
+    getDefaultTTL(): number | undefined;
+    /**
+     * Update TTL configuration
+     */
+    updateConfig(config: Partial<TTLConfig>): void;
+    /**
+     * Set TTL metadata for an item when it's added
+     */
+    onItemAdded(key: string, metadataProvider: CacheMapMetadataProvider, itemTTL?: number): void;
+    /**
+     * Check if an item has expired
+     */
+    isExpired(key: string, metadataProvider: CacheMapMetadataProvider): boolean;
+    /**
+     * Check if an item is valid (not expired) before returning it
+     * Returns true if item is valid, false if expired
+     */
+    validateItem(key: string, metadataProvider: CacheMapMetadataProvider): boolean;
+    /**
+     * Get TTL information for an item
+     */
+    getItemTTLInfo(key: string, metadataProvider: CacheMapMetadataProvider): {
+        hasTTL: boolean;
+        ttl?: number;
+        expiresAt?: number;
+        remainingTTL?: number;
+        isExpired: boolean;
+    };
+    /**
+     * Find all expired items
+     */
+    findExpiredItems(metadataProvider: CacheMapMetadataProvider): string[];
+    /**
+     * Manually clean up expired items
+     * Returns the keys of items that were expired
+     */
+    cleanupExpiredItems(metadataProvider: CacheMapMetadataProvider): string[];
+    /**
+     * Get remaining TTL for an item in milliseconds
+     */
+    getRemainingTTL(key: string, metadataProvider: CacheMapMetadataProvider): number | null;
+    /**
+     * Extend TTL for an item
+     */
+    extendTTL(key: string, metadataProvider: CacheMapMetadataProvider, additionalTTL: number): boolean;
+    /**
+     * Reset TTL for an item (refresh expiration)
+     */
+    refreshTTL(key: string, metadataProvider: CacheMapMetadataProvider, newTTL?: number): boolean;
+    /**
+     * Start automatic cleanup of expired items
+     */
+    private startAutoCleanup;
+    /**
+     * Stop automatic cleanup
+     */
+    private stopAutoCleanup;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}

package/dist/ttl/index.d.ts

@@ -0,0 +1,2 @@
+export { TTLManager } from './TTLManager';
+export type { TTLConfig, TTLItemMetadata } from './TTLManager';

package/dist/utils/CacheSize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Utility functions for parsing and managing cache sizes
+ */
+/**
+ * Parse a size string and return the size in bytes
+ *
+ * @param sizeStr - Size string (e.g., '300', '3kb', '5MB', '2GiB')
+ * @returns Size in bytes
+ * @throws Error if the size string is invalid
+ */
+export declare function parseSizeString(sizeStr: string): number;
+/**
+ * Format bytes as a human-readable string
+ *
+ * @param bytes - Size in bytes
+ * @param binary - Use binary units (1024) instead of decimal (1000)
+ * @returns Formatted size string
+ */
+export declare function formatBytes(bytes: number, binary?: boolean): string;
+export declare function estimateValueSize(value: any): number;
+/**
+ * Check if a size configuration is valid
+ *
+ * @param config - Size configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export declare function validateSizeConfig(config: {
+    maxSizeBytes?: string;
+    maxItems?: number;
+}): void;

package/fix-async-tests.js

@@ -0,0 +1,116 @@
+import fs from 'fs';
+import path from 'path';
+
+// List of async methods that need await
+const asyncMethods = [
+  'get',
+  'includesKey',
+  'values',
+  'allIn',
+  'contains',
+  'queryIn',
+  'clone',
+  'getQueryResult',
+  'invalidateLocation'
+];
+
+// Function to fix async calls in a file
+function fixAsyncCalls(content) {
+  let updatedContent = content;
+
+  // First pass: Add await to all async method calls
+  asyncMethods.forEach(method => {
+    // Fix direct method calls that need await (but don't already have it)
+    // Match cache variable names (cache, locCache, containedCache, cacheMap, etc.) but avoid things like mockLocalStorage.store
+    const methodCallRegex = new RegExp(`(?<!await\\s)((cache|locCache|containedCache|cacheMap|cache1|cache2|complexCacheMap)\\s*\\.\\s*${method}\\s*\\([^)]*\\))`, 'g');
+    updatedContent = updatedContent.replace(methodCallRegex, (match, methodCall) => {
+      // Don't add await if it's already there
+      return `await ${methodCall}`;
+    });
+
+    // Fix method calls in expect statements
+    const expectRegex = new RegExp(`expect\\((?!await\\s)((cache|locCache|containedCache|cacheMap|cache1|cache2|complexCacheMap)\\s*\\.\\s*${method}\\s*\\([^)]*\\))\\)`, 'g');
+    updatedContent = updatedContent.replace(expectRegex, 'expect(await $1)');
+  });
+
+  // Second pass: Find all it() functions that contain await and make them async
+  const lines = updatedContent.split('\n');
+  const updatedLines = [];
+  let inTestFunction = false;
+  let testFunctionStart = -1;
+  let braceCount = 0;
+  let hasAwait = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Check if this line starts a test function
+    const testMatch = line.match(/(\s*)(it\s*\(\s*['"][^'"]*['"],\s*)(\(\)\s*=>\s*\{)/);
+    if (testMatch) {
+      inTestFunction = true;
+      testFunctionStart = i;
+      braceCount = 1;
+      hasAwait = false;
+      updatedLines.push(line);
+      continue;
+    }
+
+    if (inTestFunction) {
+      // Count braces to track when we're out of the test function
+      const openBraces = (line.match(/\{/g) || []).length;
+      const closeBraces = (line.match(/\}/g) || []).length;
+      braceCount += openBraces - closeBraces;
+
+      // Check if this line contains await
+      if (line.includes('await ')) {
+        hasAwait = true;
+      }
+
+      // If we've closed all braces, we're done with this test function
+      if (braceCount === 0) {
+        inTestFunction = false;
+
+        // If this test function contains await, make it async
+        if (hasAwait) {
+          const testLine = updatedLines[testFunctionStart];
+          const testMatch = testLine.match(/(\s*)(it\s*\(\s*['"][^'"]*['"],\s*)(\(\)\s*=>\s*\{)/);
+          if (testMatch && !testMatch[3].includes('async')) {
+            updatedLines[testFunctionStart] = testMatch[1] + testMatch[2] + 'async () => {';
+          }
+        }
+      }
+    }
+
+    updatedLines.push(line);
+  }
+
+  return updatedLines.join('\n');
+}
+
+// Process all browser cache test files
+const testFiles = [
+  '/Users/tobrien/gitw/getfjell/fjell-cache/tests/browser/LocalStorageCacheMap.test.ts',
+  '/Users/tobrien/gitw/getfjell/fjell-cache/tests/browser/SessionStorageCacheMap.test.ts',
+  '/Users/tobrien/gitw/getfjell/fjell-cache/tests/browser/IndexDBCacheMap.test.ts',
+  '/Users/tobrien/gitw/getfjell/fjell-cache/tests/browser/AsyncIndexDBCacheMap.test.ts'
+];
+
+testFiles.forEach(testFile => {
+  try {
+    if (fs.existsSync(testFile)) {
+      const content = fs.readFileSync(testFile, 'utf8');
+      const fixedContent = fixAsyncCalls(content);
+
+      if (content !== fixedContent) {
+        fs.writeFileSync(testFile, fixedContent, 'utf8');
+        console.log(`Fixed async calls in ${path.basename(testFile)}`);
+      } else {
+        console.log(`No changes needed in ${path.basename(testFile)}`);
+      }
+    } else {
+      console.log(`File not found: ${testFile}`);
+    }
+  } catch (error) {
+    console.error(`Error fixing file ${path.basename(testFile)}: ${error.message}`);
+  }
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/cache",
   "description": "Cache for Fjell",
-  "version": "4.6.22",
+  "version": "4.7.2",
   "keywords": [
     "cache",
     "fjell"
@@ -13,7 +13,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
@@ -22,7 +23,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --ext .ts --fix",
     "clean": "rm -rf dist",
-    "test": "npm run lint && vitest run --coverage",
+    "test": "vitest run --coverage",
     "prepublishOnly": "npm run clean && npm run build",
     "docs:dev": "cd docs && npm run dev",
     "docs:build": "cd docs && npm run build",
@@ -30,31 +31,33 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/client-api": "^4.4.20",
+    "@fjell/client-api": "^4.4.22",
     "@fjell/core": "^4.4.29",
-    "@fjell/http-api": "^4.4.26",
+    "@fjell/http-api": "^4.4.29",
     "@fjell/logging": "^4.4.36",
-    "@fjell/registry": "^4.4.24"
+    "@fjell/registry": "^4.4.24",
+    "fast-safe-stringify": "^2.1.1",
+    "flatted": "^3.3.3"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.32.0",
+    "@eslint/js": "^9.33.0",
     "@fjell/eslint-config": "^1.1.11",
-    "@swc/core": "^1.13.2",
+    "@swc/core": "^1.13.3",
     "@tsconfig/recommended": "^1.0.10",
     "@types/multer": "^2.0.0",
-    "@types/node": "^24.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.38.0",
-    "@typescript-eslint/parser": "^8.38.0",
+    "@types/node": "^24.2.1",
+    "@typescript-eslint/eslint-plugin": "^8.39.0",
+    "@typescript-eslint/parser": "^8.39.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "concurrently": "^9.2.0",
     "esbuild": "^0.25.8",
-    "eslint": "^9.32.0",
+    "eslint": "^9.33.0",
     "nodemon": "^3.1.10",
     "ts-node": "^10.9.2",
     "tsc-alias": "^1.8.16",
-    "typescript": "^5.8.3",
+    "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
   "repository": {