@fjell/cache 4.7.0 → 4.7.4

package/dist/memory/EnhancedMemoryCacheMap.d.ts

@@ -1,36 +1,36 @@
 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 ttlOperationsInProgress;
     private currentSizeBytes;
     private currentItemCount;
     private queryResultsCacheSize;
     private readonly maxSizeBytes?;
     private readonly maxItems?;
-    private readonly evictionStrategy;
     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>): 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;
-    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
-    values(): V[];
-    clear(): 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(): EnhancedMemoryCacheMap<V, S, L1, L2, L3, L4, L5>;
+    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>;
+    private deleteInternal;
+    keys(): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]>;
+    values(): Promise<V[]>;
+    clear(): Promise<void>;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<boolean>;
+    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    clone(): Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;
     /**
      * Get current cache statistics
      */
@@ -44,22 +44,15 @@ export declare class EnhancedMemoryCacheMap<V extends Item<S, L1, L2, L3, L4, L5
             items?: number;
         };
     };
-    /**
-     * Ensure there's space available for a new item of the given size
-     * Evicts items if necessary based on the configured eviction policy
-     */
-    private ensureSpaceAvailable;
-    /**
-     * Evict a specific item and update metadata tracking
-     */
-    private evictItem;
-    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;
-    clearQueryResults(): void;
-    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): void;
-    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): 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>;
+    clearQueryResults(): Promise<void>;
+    invalidateItemKeys(keys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]): Promise<void>;
+    private filterQueriesReferencingKeys;
+    private invalidateQueriesReferencingKeys;
+    invalidateLocation(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<void>;
     /**
      * Add query result to size tracking
      */
@@ -72,4 +65,17 @@ export declare class EnhancedMemoryCacheMap<V extends Item<S, L1, L2, L3, L4, L5
      * Get total cache size including query results
      */
     getTotalSizeBytes(): number;
+    getMetadata(key: string): Promise<CacheItemMetadata | null>;
+    setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
+    deleteMetadata(_key: string): Promise<void>;
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
+    clearMetadata(): Promise<void>;
+    getCurrentSize(): Promise<{
+        itemCount: number;
+        sizeBytes: number;
+    }>;
+    getSizeLimits(): Promise<{
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    }>;
 }

package/dist/memory/MemoryCacheMap.d.ts

@@ -1,33 +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>): 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;
-    keys(): (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
-    values(): V[];
-    clear(): 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(): MemoryCacheMap<V, S, L1, L2, L3, L4, L5>;
-    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;
+    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>;
+    keys(): Promise<(ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[]>;
+    values(): Promise<V[]>;
+    clear(): Promise<void>;
+    allIn(locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    contains(query: ItemQuery, locations: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<boolean>;
+    queryIn(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []): Promise<V[]>;
+    clone(): Promise<MemoryCacheMap<V, S, L1, L2, L3, L4, L5>>;
+    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>;
+    getMetadata(key: string): Promise<CacheItemMetadata | null>;
+    setMetadata(key: string, metadata: CacheItemMetadata): Promise<void>;
+    deleteMetadata(key: string): Promise<void>;
+    getAllMetadata(): Promise<Map<string, CacheItemMetadata>>;
+    clearMetadata(): Promise<void>;
+    getCurrentSize(): Promise<{
+        itemCount: number;
+        sizeBytes: number;
+    }>;
+    getSizeLimits(): Promise<{
+        maxItems: number | null;
+        maxSizeBytes: number | null;
+    }>;
 }

package/dist/normalization.d.ts

@@ -4,11 +4,10 @@ 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 with expiration
+ * Interface for storing query results
  */
 export interface QueryCacheEntry {
     itemKeys: (any)[];
-    expiresAt?: number;
 }
 /**
  * Generate a safe hash for all/one query parameters

package/dist/ops/get.d.ts

@@ -1,3 +1,4 @@
 import { ComKey, Item, PriKey } from "@fjell/core";
 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/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): Promise<void>;
+    /**
+     * Check if an item has expired
+     */
+    isExpired(key: string, metadataProvider: CacheMapMetadataProvider): Promise<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): Promise<boolean>;
+    /**
+     * Get TTL information for an item
+     */
+    getItemTTLInfo(key: string, metadataProvider: CacheMapMetadataProvider): Promise<{
+        hasTTL: boolean;
+        ttl?: number;
+        expiresAt?: number;
+        remainingTTL?: number;
+        isExpired: boolean;
+    }>;
+    /**
+     * Find all expired items
+     */
+    findExpiredItems(metadataProvider: CacheMapMetadataProvider): Promise<string[]>;
+    /**
+     * Manually clean up expired items
+     * Returns the keys of items that were expired
+     */
+    cleanupExpiredItems(metadataProvider: CacheMapMetadataProvider): Promise<string[]>;
+    /**
+     * Get remaining TTL for an item in milliseconds
+     */
+    getRemainingTTL(key: string, metadataProvider: CacheMapMetadataProvider): Promise<number | null>;
+    /**
+     * Extend TTL for an item
+     */
+    extendTTL(key: string, metadataProvider: CacheMapMetadataProvider, additionalTTL: number): Promise<boolean>;
+    /**
+     * Reset TTL for an item (refresh expiration)
+     */
+    refreshTTL(key: string, metadataProvider: CacheMapMetadataProvider, newTTL?: number): Promise<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

@@ -17,13 +17,6 @@ export declare function parseSizeString(sizeStr: string): number;
  * @returns Formatted size string
  */
 export declare function formatBytes(bytes: number, binary?: boolean): string;
-/**
- * Estimate the serialized size of a value in bytes
- * This is an approximation for cache size calculations
- *
- * @param value - The value to estimate size for
- * @returns Estimated size in bytes
- */
 export declare function estimateValueSize(value: any): number;
 /**
  * Check if a size configuration is valid

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.7.0",
+  "version": "4.7.4",
   "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/core": "^4.4.29",
-    "@fjell/http-api": "^4.4.26",
-    "@fjell/logging": "^4.4.36",
-    "@fjell/registry": "^4.4.24"
+    "@fjell/client-api": "^4.4.24",
+    "@fjell/core": "^4.4.34",
+    "@fjell/http-api": "^4.4.33",
+    "@fjell/logging": "^4.4.40",
+    "@fjell/registry": "^4.4.28",
+    "fast-safe-stringify": "^2.1.1",
+    "flatted": "^3.3.3"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.32.0",
-    "@fjell/eslint-config": "^1.1.11",
-    "@swc/core": "^1.13.2",
+    "@eslint/js": "^9.33.0",
+    "@fjell/eslint-config": "^1.1.19",
+    "@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": {