@fjell/cache 4.7.60 → 4.7.62

package/dist/index.js

@@ -1,15 +1,5 @@
 // src/Operations.ts
-import {
-  createAllFacetWrapper as createAllFacetWrapper2,
-  createAllWrapper as createAllWrapper2,
-  createCreateWrapper as createCreateWrapper2,
-  createGetWrapper as createGetWrapper2,
-  createOneWrapper as createOneWrapper2,
-  createRemoveWrapper as createRemoveWrapper2,
-  createUpdateWrapper as createUpdateWrapper2,
-  isOperationComKey as isComKey7,
-  isOperationPriKey as isPriKey
-} from "@fjell/core";
+import { createAllFacetWrapper as createAllFacetWrapper2, createAllWrapper as createAllWrapper2, createCreateWrapper as createCreateWrapper2, createGetWrapper as createGetWrapper2, createOneWrapper as createOneWrapper2, createRemoveWrapper as createRemoveWrapper2, createUpdateWrapper as createUpdateWrapper2, isComKey as isComKey8, isPriKey } from "@fjell/core";
 
 // src/logger.ts
 import Logging from "@fjell/logging";
@@ -606,7 +596,20 @@ var createQueryHash = (pkType, query, locations) => {
   };
   const hash = deterministicStringify(hashInput);
   if (!hash || typeof hash !== "string" || hash.trim() === "") {
-    throw new Error(`Invalid query hash generated: hash is empty or invalid. Input: ${JSON.stringify({ pkType, query, locations })}`);
+    const errorContext = {
+      component: "cache",
+      subcomponent: "normalization",
+      operation: "createQueryHash",
+      pkType,
+      query: JSON.stringify(query),
+      locations: JSON.stringify(locations),
+      hashResult: hash,
+      suggestion: "This indicates a bug in query normalization. Check query and location structures."
+    };
+    console.error("Invalid query hash generated:", JSON.stringify(errorContext, null, 2));
+    throw new Error(
+      `Invalid query hash generated: hash is empty or invalid. Input: ${JSON.stringify({ pkType, query, locations })}. This indicates a bug in query normalization logic.`
+    );
   }
   return hash;
 };
@@ -866,10 +869,27 @@ async function executeAllLogic(query, locations, context, allOptions) {
     logger4.debug("Cache bypass enabled, fetching directly from API", { query, locations });
     try {
       const ret = await api.all(query, locations, allOptions);
-      logger4.debug("API response received (not cached due to bypass)", { query, locations, itemCount: ret.items.length });
+      logger4.debug("API response received (not cached due to bypass)", {
+        operation: "all",
+        mode: "bypass",
+        query,
+        locations,
+        itemCount: ret.items.length,
+        metadata: ret.metadata
+      });
       return ret;
     } catch (error) {
-      logger4.error("API request failed", { query, locations, error });
+      logger4.error("API request failed in bypass mode", {
+        operation: "all",
+        mode: "bypass",
+        query,
+        locations,
+        errorType: error.constructor?.name || typeof error,
+        errorMessage: error.message,
+        errorCode: error.code || error.errorInfo?.code,
+        suggestion: "Verify API endpoint is accessible, query syntax is correct, and locations are valid",
+        error
+      });
       throw error;
     }
   }
@@ -955,8 +975,15 @@ async function executeAllLogic(query, locations, context, allOptions) {
       }
     } catch (error) {
       logger4.debug("QUERY_CACHE: Error querying cache directly, proceeding to API", {
+        operation: "all",
+        phase: "cache-query",
         queryHash,
-        error: error instanceof Error ? error.message : String(error)
+        query: JSON.stringify(query),
+        locations: JSON.stringify(locations),
+        errorType: error.constructor?.name || typeof error,
+        errorMessage: error instanceof Error ? error.message : String(error),
+        cacheType: cacheMap.implementationType,
+        note: "This is expected behavior - falling back to API when cache query fails"
       });
     }
   } else {
@@ -1031,9 +1058,19 @@ async function executeAllLogic(query, locations, context, allOptions) {
       await cacheMap.setQueryResult(queryHash, []);
       logger4.debug("QUERY_CACHE: Cached empty query result for not found", { queryHash });
     } else {
-      logger4.debug("QUERY_CACHE: API error occurred", {
+      logger4.error("QUERY_CACHE: API error occurred during all() operation", {
+        operation: "all",
+        phase: "api-fetch",
         queryHash,
-        error: e instanceof Error ? e.message : String(e)
+        query: JSON.stringify(query),
+        locations: JSON.stringify(locations),
+        errorType: e instanceof Error ? e.constructor.name : typeof e,
+        errorMessage: e instanceof Error ? e.message : String(e),
+        errorCode: e.code || e.errorInfo?.code,
+        cacheType: cacheMap.implementationType,
+        inFlightRequestsCount: inFlightRequests.size,
+        suggestion: "Check API connectivity, query syntax, location keys, and network connectivity",
+        error: e
       });
       throw e;
     }
@@ -1405,27 +1442,63 @@ var create = async (v, locations = [], context) => {
   return [context, result];
 };
 async function executeCreateLogic(v, locations, context) {
+  const startTime = Date.now();
   const { api, cacheMap, pkType, eventEmitter, ttlManager, evictionManager } = context;
-  const created = await api.create(v, locations.length > 0 ? { locations } : void 0);
-  cacheMap.set(created.key, created);
-  const keyStr = JSON.stringify(created.key);
-  ttlManager.onItemAdded(keyStr, cacheMap);
-  const evictedKeys = await evictionManager.onItemAdded(keyStr, created, cacheMap);
-  for (const evictedKey of evictedKeys) {
-    const parsedKey = JSON.parse(evictedKey);
-    await cacheMap.delete(parsedKey);
+  try {
+    logger6.debug("CACHE_OP: create() started", {
+      operation: "create",
+      itemType: pkType,
+      hasLocations: locations.length > 0,
+      locationCount: locations.length,
+      itemData: JSON.stringify(v)
+    });
+    const created = await api.create(v, locations.length > 0 ? { locations } : void 0);
+    const apiDuration = Date.now() - startTime;
+    cacheMap.set(created.key, created);
+    const keyStr = JSON.stringify(created.key);
+    ttlManager.onItemAdded(keyStr, cacheMap);
+    const evictedKeys = await evictionManager.onItemAdded(keyStr, created, cacheMap);
+    for (const evictedKey of evictedKeys) {
+      const parsedKey = JSON.parse(evictedKey);
+      await cacheMap.delete(parsedKey);
+    }
+    await cacheMap.clearQueryResults();
+    const itemEvent = CacheEventFactory.itemCreated(created.key, created, "api");
+    eventEmitter.emit(itemEvent);
+    const queryInvalidatedEvent = CacheEventFactory.createQueryInvalidatedEvent(
+      [],
+      // We don't track which specific queries were invalidated
+      "item_changed",
+      { source: "operation", context: { operation: "create" } }
+    );
+    eventEmitter.emit(queryInvalidatedEvent);
+    const totalDuration = Date.now() - startTime;
+    logger6.debug("CACHE_OP: create() completed successfully", {
+      operation: "create",
+      itemType: pkType,
+      key: keyStr,
+      evictedCount: evictedKeys.length,
+      apiDuration,
+      totalDuration
+    });
+    return created;
+  } catch (e) {
+    const duration = Date.now() - startTime;
+    logger6.error("CACHE_OP: create() operation failed", {
+      operation: "create",
+      itemType: pkType,
+      itemData: JSON.stringify(v),
+      locations: JSON.stringify(locations),
+      duration,
+      errorType: e.constructor?.name || typeof e,
+      errorMessage: e.message,
+      errorCode: e.code || e.errorInfo?.code,
+      cacheType: cacheMap.implementationType,
+      suggestion: "Check validation errors, duplicate constraints, required fields, and API connectivity",
+      stack: e.stack
+    });
+    throw e;
   }
-  await cacheMap.clearQueryResults();
-  const itemEvent = CacheEventFactory.itemCreated(created.key, created, "api");
-  eventEmitter.emit(itemEvent);
-  const queryInvalidatedEvent = CacheEventFactory.createQueryInvalidatedEvent(
-    [],
-    // We don't track which specific queries were invalidated
-    "item_changed",
-    { source: "operation", context: { operation: "create" } }
-  );
-  eventEmitter.emit(queryInvalidatedEvent);
-  return created;
 }
 
 // src/ops/get.ts
@@ -1474,9 +1547,19 @@ async function executeGetLogic(key, context) {
     cacheType: cacheMap.implementationType
   });
   statsManager.incrementRequests();
+  if (key === null) {
+    throw new Error("Key cannot be null");
+  }
   if (!isValidItemKey(key)) {
-    logger7.error("CACHE_OP: Invalid key for get", { key: keyStr });
-    throw new Error("Key for Get is not a valid ItemKey");
+    logger7.error("CACHE_OP: Invalid key for get operation", {
+      key: keyStr,
+      keyType: typeof key,
+      reason: "Key validation failed - must be a valid PriKey or ComKey",
+      suggestion: "Ensure the key has the correct structure: PriKey { kt, pk } or ComKey { kt, sk, lk }",
+      itemType: pkType,
+      coordinate: JSON.stringify(context.coordinate)
+    });
+    throw new Error(`Invalid key for get operation: ${keyStr}. Expected valid PriKey or ComKey structure.`);
   }
   if (context.options?.bypassCache) {
     logger7.debug("CACHE_OP: Cache bypass enabled, fetching directly from API", { key: keyStr });
@@ -1501,8 +1584,15 @@ async function executeGetLogic(key, context) {
       }
     } catch (error) {
       logger7.error("CACHE_OP: API request failed in bypass mode", {
+        operation: "get",
+        mode: "bypass",
         key: keyStr,
+        itemType: pkType,
         duration: Date.now() - startTime,
+        errorType: error.constructor?.name || typeof error,
+        errorMessage: error.message,
+        errorCode: error.code || error.errorInfo?.code,
+        suggestion: "Verify API endpoint is accessible and key exists. Cache bypass mode does not retry.",
         error
       });
       throw error;
@@ -1671,10 +1761,19 @@ async function executeGetLogic(key, context) {
   } catch (e) {
     inFlightRequests2.delete(requestKeyStr);
     const duration = Date.now() - startTime;
-    logger7.error("CACHE_OP: Error in get() operation", {
+    logger7.error("CACHE_OP: get() operation failed", {
+      operation: "get",
       key: keyStr,
+      itemType: pkType,
       duration,
-      message: e.message,
+      errorType: e.constructor?.name || typeof e,
+      errorMessage: e.message,
+      errorCode: e.code || e.errorInfo?.code,
+      cacheType: cacheMap.implementationType,
+      ttlEnabled: ttlManager.isTTLEnabled(),
+      bypassMode: context.options?.bypassCache || false,
+      inFlightRequestsCount: inFlightRequests2.size,
+      suggestion: "Check API connectivity, key validity, and cache configuration",
       stack: e.stack
     });
     throw e;
@@ -1698,6 +1797,9 @@ var retrieve = async (key, context) => {
     bypassEnabled: !!context.options?.bypassCache
   });
   statsManager.incrementRequests();
+  if (key === null) {
+    throw new Error("Key cannot be null");
+  }
   if (!isValidItemKey2(key)) {
     logger8.error("CACHE_OP: Invalid key for retrieve", { key: keyStr });
     throw new Error("Key for Retrieve is not a valid ItemKey");
@@ -1798,13 +1900,30 @@ var remove = async (key, context) => {
 };
 async function executeRemoveLogic(key, context) {
   const { api, cacheMap } = context;
+  const keyStr = JSON.stringify(key);
+  if (key === null) {
+    throw new Error("Key cannot be null");
+  }
   if (!isValidItemKey3(key)) {
-    logger9.error("Key for Remove is not a valid ItemKey: %j", key);
-    throw new Error("Key for Remove is not a valid ItemKey");
+    logger9.error("CACHE_OP: Invalid key for remove operation", {
+      operation: "remove",
+      key: keyStr,
+      keyType: typeof key,
+      reason: "Key validation failed - must be a valid PriKey or ComKey",
+      suggestion: "Ensure the key has the correct structure: PriKey { kt, pk } or ComKey { kt, sk, lk }"
+    });
+    throw new Error(`Invalid key for remove operation: ${keyStr}. Expected valid PriKey or ComKey structure.`);
   }
+  const startTime = Date.now();
   try {
+    logger9.debug("CACHE_OP: remove() started", {
+      operation: "remove",
+      key: keyStr,
+      cacheType: cacheMap.implementationType
+    });
     const previousItem = await cacheMap.get(key);
     await api.remove(key);
+    const apiDuration = Date.now() - startTime;
     cacheMap.delete(key);
     await cacheMap.clearQueryResults();
     if (previousItem) {
@@ -1817,9 +1936,27 @@ async function executeRemoveLogic(key, context) {
       { source: "operation", context: { operation: "remove" } }
     );
     context.eventEmitter.emit(queryInvalidatedEvent);
-    logger9.debug("Successfully removed item from API and cache", { key });
+    const totalDuration = Date.now() - startTime;
+    logger9.debug("CACHE_OP: remove() completed successfully", {
+      operation: "remove",
+      key: keyStr,
+      hadCachedItem: !!previousItem,
+      apiDuration,
+      totalDuration
+    });
   } catch (e) {
-    logger9.error("Error deleting item", { error: e });
+    const duration = Date.now() - startTime;
+    logger9.error("CACHE_OP: remove() operation failed", {
+      operation: "remove",
+      key: keyStr,
+      duration,
+      errorType: e.constructor?.name || typeof e,
+      errorMessage: e.message,
+      errorCode: e.code || e.errorInfo?.code,
+      cacheType: cacheMap.implementationType,
+      suggestion: "Check item exists, delete permissions, referential integrity constraints, and API connectivity",
+      stack: e.stack
+    });
     throw e;
   }
 }
@@ -1844,34 +1981,56 @@ var update = async (key, v, context) => {
 };
 async function executeUpdateLogic(key, v, context) {
   const { api, cacheMap, pkType } = context;
+  if (key === null) {
+    throw new Error("Key cannot be null");
+  }
   if (!isValidItemKey4(key)) {
-    logger10.error("Key for Update is not a valid ItemKey: %j", key);
-    throw new Error("Key for Update is not a valid ItemKey");
+    logger10.error("CACHE_OP: Invalid key for update operation", {
+      operation: "update",
+      key: JSON.stringify(key),
+      keyType: typeof key,
+      itemType: pkType,
+      reason: "Key validation failed - must be a valid PriKey or ComKey",
+      suggestion: "Ensure the key has the correct structure: PriKey { kt, pk } or ComKey { kt, sk, lk }"
+    });
+    throw new Error(`Invalid key for update operation: ${JSON.stringify(key)}. Expected valid PriKey or ComKey structure.`);
   }
   logger10.debug("Invalidating item key before update", { key });
   cacheMap.invalidateItemKeys([key]);
   await cacheMap.clearQueryResults();
+  const startTime = Date.now();
+  const keyStr = JSON.stringify(key);
   try {
+    logger10.debug("CACHE_OP: update() started", {
+      operation: "update",
+      key: keyStr,
+      itemType: pkType,
+      updateData: JSON.stringify(v)
+    });
     const previousItem = await cacheMap.get(key);
     const updated = await api.update(key, v);
-    logger10.debug("Caching update result", { updatedKey: updated.key });
+    const apiDuration = Date.now() - startTime;
+    logger10.debug("CACHE_OP: Caching update result", {
+      operation: "update",
+      updatedKey: JSON.stringify(updated.key)
+    });
     await cacheMap.set(updated.key, updated);
     const cachedItem = await cacheMap.get(updated.key);
-    const keyStr = JSON.stringify(updated.key);
-    const metadata = await cacheMap.getMetadata(keyStr);
+    const updatedKeyStr = JSON.stringify(updated.key);
+    const metadata = await cacheMap.getMetadata(updatedKeyStr);
     if (!metadata) {
       const now = Date.now();
       const baseMetadata = {
-        key: keyStr,
+        key: updatedKeyStr,
         addedAt: now,
         lastAccessedAt: now,
         accessCount: 1,
         estimatedSize: estimateValueSize(updated)
       };
-      await cacheMap.setMetadata(keyStr, baseMetadata);
+      await cacheMap.setMetadata(updatedKeyStr, baseMetadata);
     }
-    await context.ttlManager.onItemAdded(keyStr, cacheMap);
-    const evictedKeys = await context.evictionManager.onItemAdded(keyStr, updated, cacheMap);
+    await context.ttlManager.onItemAdded(updatedKeyStr, cacheMap);
+    const evictedKeys = await context.evictionManager.onItemAdded(updatedKeyStr, updated, cacheMap);
     for (const evictedKey of evictedKeys) {
       const parsedKey = JSON.parse(evictedKey);
       await cacheMap.delete(parsedKey);
@@ -1885,9 +2044,31 @@ async function executeUpdateLogic(key, v, context) {
       { source: "operation", context: { operation: "update" } }
     );
     context.eventEmitter.emit(queryInvalidatedEvent);
+    const totalDuration = Date.now() - startTime;
+    logger10.debug("CACHE_OP: update() completed successfully", {
+      operation: "update",
+      key: updatedKeyStr,
+      itemType: pkType,
+      evictedCount: evictedKeys.length,
+      apiDuration,
+      totalDuration
+    });
     return updated;
   } catch (e) {
-    logger10.error("Error updating item", { error: e });
+    const duration = Date.now() - startTime;
+    logger10.error("CACHE_OP: update() operation failed", {
+      operation: "update",
+      key: keyStr,
+      itemType: pkType,
+      updateData: JSON.stringify(v),
+      duration,
+      errorType: e.constructor?.name || typeof e,
+      errorMessage: e.message,
+      errorCode: e.code || e.errorInfo?.code,
+      cacheType: cacheMap.implementationType,
+      suggestion: "Check item exists, validation rules, update permissions, and API connectivity",
+      stack: e.stack
+    });
     throw e;
   }
 }
@@ -1899,7 +2080,7 @@ import {
 } from "@fjell/core";
 
 // src/utils/cacheInvalidation.ts
-import { toKeyTypeArray } from "@fjell/core";
+import { isComKey, toKeyTypeArray } from "@fjell/core";
 var logger11 = logger_default.get("cache", "utils", "cacheInvalidation");
 var extractKeysAndKeyTypesFromActionResult = (affectedItems) => {
   const keys = [];
@@ -1923,7 +2104,7 @@ var invalidateCachesByKeysAndKeyTypes = async (registry, keys, keyTypeArrays) =>
   });
   const keysByKeyTypes = /* @__PURE__ */ new Map();
   for (const key of keys) {
-    const keyTypes = "loc" in key ? [key.kt, ...key.loc.map((locKey) => locKey.kt)] : [key.kt];
+    const keyTypes = isComKey(key) ? [key.kt, ...key.loc.map((locKey) => locKey.kt)] : [key.kt];
     const keyTypesKey = keyTypes.join("|");
     if (!keysByKeyTypes.has(keyTypesKey)) {
       keysByKeyTypes.set(keyTypesKey, []);
@@ -1999,6 +2180,9 @@ var action = async (key, action2, body = {}, context) => {
 };
 async function executeActionLogic(key, action2, body, context) {
   const { api, cacheMap, pkType, registry } = context;
+  if (key === null) {
+    throw new Error("Key cannot be null");
+  }
   if (!isValidItemKey5(key)) {
     logger12.error("Key for Action is not a valid ItemKey: %j", key);
     throw new Error("Key for Action is not a valid ItemKey");
@@ -2585,14 +2769,19 @@ var normalizeKey = (key) => {
   return key;
 };
 var set = async (key, v, context) => {
+  if (key === null) {
+    throw new Error("Key cannot be null");
+  }
+  if (typeof key === "undefined") {
+    throw new Error("Key for Set is not a valid ItemKey");
+  }
   const startTime = Date.now();
   const { cacheMap, pkType, ttlManager, evictionManager, eventEmitter } = context;
   const keyStr = JSON.stringify(key);
+  if (v === null || typeof v === "undefined") {
+    throw new Error("Item cannot be null");
+  }
   logger18.default("set", { key, v });
-  logger18.debug("CACHE_OP: set() started", {
-    key: keyStr,
-    cacheType: cacheMap.implementationType
-  });
   if (!isValidItemKey6(key)) {
     logger18.error("CACHE_OP: Invalid key for set", { key: keyStr });
     throw new Error("Key for Set is not a valid ItemKey");
@@ -2677,7 +2866,7 @@ var set = async (key, v, context) => {
 
 // src/memory/MemoryCacheMap.ts
 import {
-  isComKey,
+  isComKey as isComKey2,
   isQueryMatch
 } from "@fjell/core";
 var logger19 = logger_default.get("MemoryCacheMap");
@@ -2781,7 +2970,7 @@ var MemoryCacheMap = class _MemoryCacheMap extends CacheMap {
       logger19.debug("allIn", { locations, count: allValues.length });
       return allValues.filter((item) => {
         const key = item.key;
-        if (key && isComKey(key)) {
+        if (key && isComKey2(key)) {
           const comKey = key;
           return isLocKeyArrayEqual(locations, comKey.loc);
         }
@@ -2897,7 +3086,7 @@ var MemoryCacheMap = class _MemoryCacheMap extends CacheMap {
     let keysToInvalidate = [];
     if (locations.length === 0) {
       const allKeys = await this.keys();
-      const primaryKeys = allKeys.filter((key) => !isComKey(key));
+      const primaryKeys = allKeys.filter((key) => !isComKey2(key));
       keysToInvalidate = primaryKeys;
     } else {
       const itemsInLocation = await this.allIn(locations);
@@ -2945,7 +3134,7 @@ var MemoryCacheMap = class _MemoryCacheMap extends CacheMap {
 
 // src/memory/EnhancedMemoryCacheMap.ts
 import {
-  isComKey as isComKey2,
+  isComKey as isComKey3,
   isQueryMatch as isQueryMatch2
 } from "@fjell/core";
 var logger20 = logger_default.get("EnhancedMemoryCacheMap");
@@ -3089,7 +3278,7 @@ var EnhancedMemoryCacheMap = class _EnhancedMemoryCacheMap extends CacheMap {
       logger20.debug("allIn", { locations, count: allValues.length });
       return allValues.filter((item) => {
         const key = item.key;
-        if (key && isComKey2(key)) {
+        if (key && isComKey3(key)) {
           return isLocKeyArrayEqual(locations, key.loc);
         }
         return false;
@@ -3249,7 +3438,7 @@ var EnhancedMemoryCacheMap = class _EnhancedMemoryCacheMap extends CacheMap {
     let keysToInvalidate = [];
     if (locations.length === 0) {
       const allKeys = await this.keys();
-      const primaryKeys = allKeys.filter((key) => !isComKey2(key));
+      const primaryKeys = allKeys.filter((key) => !isComKey3(key));
       keysToInvalidate = primaryKeys;
     } else {
       const itemsInLocation = await this.allIn(locations);
@@ -3363,7 +3552,7 @@ var EnhancedMemoryCacheMap = class _EnhancedMemoryCacheMap extends CacheMap {
 
 // src/browser/LocalStorageCacheMap.ts
 import {
-  isComKey as isComKey3,
+  isComKey as isComKey4,
   isQueryMatch as isQueryMatch3
 } from "@fjell/core";
 var logger21 = logger_default.get("LocalStorageCacheMap");
@@ -3524,7 +3713,17 @@ var LocalStorageCacheMap = class _LocalStorageCacheMap extends CacheMap {
           const useAggressiveCleanup = attempt > 0;
           this.tryCleanupOldEntries(useAggressiveCleanup);
           if (isLastAttempt) {
-            throw new Error("Failed to store item in localStorage: storage quota exceeded even after multiple cleanup attempts");
+            logger21.error("LocalStorage quota exceeded after all cleanup attempts", {
+              component: "cache",
+              subcomponent: "LocalStorageCacheMap",
+              operation: "set",
+              key: JSON.stringify(key),
+              retryAttempts: attempt + 1,
+              suggestion: "Reduce cache size limits, clear more data, or use IndexedDB for larger storage needs"
+            });
+            throw new Error(
+              "Failed to store item in localStorage: storage quota exceeded even after multiple cleanup attempts. Suggestion: Reduce maxItems in memoryConfig, clear old data, or switch to IndexedDB for larger storage."
+            );
           }
           continue;
         }
@@ -3577,13 +3776,13 @@ var LocalStorageCacheMap = class _LocalStorageCacheMap extends CacheMap {
       const locKeys = locations;
       const resolvedKeys = await allKeys;
       logger21.debug("allIn", { locKeys, keys: resolvedKeys.length });
-      const filteredKeys = resolvedKeys.filter((key) => key && isComKey3(key)).filter((key) => {
-        const ComKey16 = key;
+      const filteredKeys = resolvedKeys.filter((key) => key && isComKey4(key)).filter((key) => {
+        const ComKey = key;
         logger21.debug("Comparing Location Keys", {
           locKeys,
-          ComKey: ComKey16
+          ComKey
         });
-        return isLocKeyArrayEqual(locKeys, ComKey16.loc);
+        return isLocKeyArrayEqual(locKeys, ComKey.loc);
       });
       const items = [];
       for (const key of filteredKeys) {
@@ -3665,8 +3864,18 @@ var LocalStorageCacheMap = class _LocalStorageCacheMap extends CacheMap {
   async setQueryResult(queryHash, itemKeys, metadata) {
     logger21.trace("setQueryResult", { queryHash, itemKeys, hasMetadata: !!metadata });
     if (!queryHash || typeof queryHash !== "string" || queryHash.trim() === "") {
-      logger21.error("Invalid queryHash provided to setQueryResult", { queryHash, itemKeys });
-      throw new Error(`Invalid queryHash: ${JSON.stringify(queryHash)}`);
+      logger21.error("Invalid queryHash provided to setQueryResult", {
+        component: "cache",
+        subcomponent: "LocalStorageCacheMap",
+        operation: "setQueryResult",
+        queryHash,
+        queryHashType: typeof queryHash,
+        itemKeys,
+        suggestion: "Ensure queryHash is a non-empty string generated from query normalization"
+      });
+      throw new Error(
+        `Invalid queryHash provided to setQueryResult: ${JSON.stringify(queryHash)}. Expected non-empty string, got ${typeof queryHash}. This usually indicates a bug in query hash generation.`
+      );
     }
     const queryKey = `${this.keyPrefix}:query:${queryHash}`;
     const entry = {
@@ -3820,7 +4029,7 @@ var LocalStorageCacheMap = class _LocalStorageCacheMap extends CacheMap {
     let keysToInvalidate = [];
     if (locations.length === 0) {
       const allKeys = await this.keys();
-      const primaryKeys = allKeys.filter((key) => !isComKey3(key));
+      const primaryKeys = allKeys.filter((key) => !isComKey4(key));
       keysToInvalidate = primaryKeys;
     } else {
       const itemsInLocation = await this.allIn(locations);
@@ -3985,7 +4194,7 @@ var LocalStorageCacheMap = class _LocalStorageCacheMap extends CacheMap {
 
 // src/browser/SessionStorageCacheMap.ts
 import {
-  isComKey as isComKey4,
+  isComKey as isComKey5,
   isQueryMatch as isQueryMatch4
 } from "@fjell/core";
 import safeStringify2 from "fast-safe-stringify";
@@ -4081,8 +4290,19 @@ var SessionStorageCacheMap = class _SessionStorageCacheMap extends CacheMap {
       const jsonString = safeStringify2(toStore);
       sessionStorage.setItem(storageKey, jsonString);
     } catch (error) {
-      logger22.error("Error storing to sessionStorage", { errorMessage: error?.message });
-      throw new Error(`Failed to store item in sessionStorage: ${error}`);
+      const isQuotaError = error?.name === "QuotaExceededError" || error?.message?.includes("quota") || error?.code === 22;
+      logger22.error("Error storing to sessionStorage", {
+        component: "cache",
+        subcomponent: "SessionStorageCacheMap",
+        operation: "set",
+        key: JSON.stringify(key),
+        errorType: error?.name,
+        errorMessage: error?.message,
+        isQuotaError,
+        suggestion: isQuotaError ? "SessionStorage quota exceeded. Clear old data, reduce cache size, or use IndexedDB instead." : "Check browser sessionStorage support and data serializability."
+      });
+      const errorMsg = isQuotaError ? "SessionStorage quota exceeded. Try clearing old cache data or reducing cache size." : `Failed to store item in sessionStorage: ${error?.message || error}`;
+      throw new Error(errorMsg);
     }
   }
   async includesKey(key) {
@@ -4131,13 +4351,13 @@ var SessionStorageCacheMap = class _SessionStorageCacheMap extends CacheMap {
       const locKeys = locations;
       const resolvedKeys = await allKeys;
       logger22.debug("allIn", { locKeys, keys: resolvedKeys.length });
-      const filteredKeys = resolvedKeys.filter((key) => key && isComKey4(key)).filter((key) => {
-        const ComKey16 = key;
+      const filteredKeys = resolvedKeys.filter((key) => key && isComKey5(key)).filter((key) => {
+        const ComKey = key;
         logger22.debug("Comparing Location Keys", {
           locKeys,
-          ComKey: ComKey16
+          ComKey
         });
-        return isLocKeyArrayEqual(locKeys, ComKey16.loc);
+        return isLocKeyArrayEqual(locKeys, ComKey.loc);
       });
       const items = [];
       for (const key of filteredKeys) {
@@ -4460,7 +4680,7 @@ var SessionStorageCacheMap = class _SessionStorageCacheMap extends CacheMap {
     let keysToInvalidate = [];
     if (locations.length === 0) {
       const allKeys = await this.keys();
-      const primaryKeys = allKeys.filter((key) => !isComKey4(key));
+      const primaryKeys = allKeys.filter((key) => !isComKey5(key));
       keysToInvalidate = primaryKeys;
     } else {
       const itemsInLocation = await this.allIn(locations);
@@ -4512,13 +4732,13 @@ var SessionStorageCacheMap = class _SessionStorageCacheMap extends CacheMap {
 
 // src/browser/IndexDBCacheMap.ts
 import {
-  isComKey as isComKey6,
+  isComKey as isComKey7,
   isQueryMatch as isQueryMatch6
 } from "@fjell/core";
 
 // src/browser/AsyncIndexDBCacheMap.ts
 import {
-  isComKey as isComKey5,
+  isComKey as isComKey6,
   isQueryMatch as isQueryMatch5
 } from "@fjell/core";
 import safeStringify3 from "fast-safe-stringify";
@@ -4667,8 +4887,18 @@ var AsyncIndexDBCacheMap = class _AsyncIndexDBCacheMap {
       try {
         storageKey = this.getStorageKey(key);
       } catch (keyError) {
-        logger23.debug("Storage key generation failed during set, throwing error", { key, error: keyError });
-        throw new Error(`Failed to generate storage key: ${keyError}`);
+        logger23.error("Storage key generation failed", {
+          component: "cache",
+          subcomponent: "AsyncIndexDBCacheMap",
+          operation: "set",
+          key: JSON.stringify(key),
+          errorType: keyError?.constructor?.name,
+          errorMessage: keyError?.message,
+          suggestion: "Check key structure and normalization logic"
+        });
+        throw new Error(
+          `Failed to generate storage key for IndexedDB: ${keyError?.message || keyError}. Key: ${JSON.stringify(key)}. This indicates a key normalization issue.`
+        );
       }
       const storedItem = {
         originalKey: key,
@@ -4692,8 +4922,19 @@ var AsyncIndexDBCacheMap = class _AsyncIndexDBCacheMap {
         }
       });
     } catch (error) {
-      logger23.error("Error in IndexedDB set operation", { key, value, error });
-      throw new Error(`Failed to store item in IndexedDB: ${error}`);
+      const isQuotaError = error?.name === "QuotaExceededError" || error?.message?.includes("quota");
+      logger23.error("Error in IndexedDB set operation", {
+        component: "cache",
+        subcomponent: "AsyncIndexDBCacheMap",
+        operation: "set",
+        key: JSON.stringify(key),
+        errorType: error?.name,
+        errorMessage: error?.message,
+        isQuotaError,
+        suggestion: isQuotaError ? "IndexedDB quota exceeded. Clear old data, reduce cache size, or request more storage quota." : "Check IndexedDB support, permissions, and data serializability."
+      });
+      const errorMsg = isQuotaError ? "IndexedDB quota exceeded. Try clearing old cache data or reducing cache size." : `Failed to store item in IndexedDB: ${error?.message || error}`;
+      throw new Error(errorMsg);
     }
   }
   /**
@@ -4793,13 +5034,13 @@ var AsyncIndexDBCacheMap = class _AsyncIndexDBCacheMap {
     } else {
       const locKeys = locations;
       logger23.debug("allIn", { locKeys, keys: allKeys.length });
-      const filteredKeys = allKeys.filter((key) => key && isComKey5(key)).filter((key) => {
-        const ComKey16 = key;
+      const filteredKeys = allKeys.filter((key) => key && isComKey6(key)).filter((key) => {
+        const ComKey = key;
         logger23.debug("Comparing Location Keys", {
           locKeys,
-          ComKey: ComKey16
+          ComKey
         });
-        return isLocKeyArrayEqual(locKeys, ComKey16.loc);
+        return isLocKeyArrayEqual(locKeys, ComKey.loc);
       });
       const promises = filteredKeys.map((key) => this.get(key));
       const results = await Promise.all(promises);
@@ -5412,7 +5653,7 @@ var IndexDBCacheMap = class _IndexDBCacheMap extends CacheMap {
       const key = entry.originalKey;
       if (locations.length === 0) {
         result.push(entry.value);
-      } else if (isComKey6(key)) {
+      } else if (isComKey7(key)) {
         if (isLocKeyArrayEqual(key.loc, locations)) {
           result.push(entry.value);
         }
@@ -5514,7 +5755,7 @@ var IndexDBCacheMap = class _IndexDBCacheMap extends CacheMap {
     const itemsToDelete = [];
     for (const entry of Object.values(this.memoryMap)) {
       const key = entry.originalKey;
-      if (isComKey6(key) && isLocKeyArrayEqual(key.loc, locations)) {
+      if (isComKey7(key) && isLocKeyArrayEqual(key.loc, locations)) {
         itemsToDelete.push(key);
       }
     }
@@ -5573,6 +5814,7 @@ var IndexDBCacheMap = class _IndexDBCacheMap extends CacheMap {
 };
 
 // src/Options.ts
+var logger25 = logger_default.get("Options");
 var DEFAULT_CACHE_OPTIONS = {
   cacheType: "memory",
   enableDebugLogging: false,
@@ -5676,12 +5918,29 @@ var createCacheMap = (kta, options) => {
       break;
     case "custom":
       if (!options.customCacheMapFactory) {
-        throw new Error('Custom cache map factory is required when cacheType is "custom"');
+        logger25.error("Custom cache map factory missing", {
+          component: "cache",
+          operation: "createCacheMap",
+          cacheType: "custom",
+          suggestion: 'Provide customCacheMapFactory function in cache options when using cacheType: "custom"'
+        });
+        throw new Error(
+          'Custom cache map factory is required when cacheType is "custom". Provide customCacheMapFactory in cache options.'
+        );
       }
       underlyingCache = options.customCacheMapFactory(kta);
       break;
     default:
-      throw new Error(`Unsupported cache type: ${options.cacheType}`);
+      logger25.error("Unsupported cache type", {
+        component: "cache",
+        operation: "createCacheMap",
+        cacheType: options.cacheType,
+        validTypes: ["memory", "localStorage", "sessionStorage", "indexedDB", "asyncIndexedDB", "custom"],
+        suggestion: "Use one of: memory, localStorage, sessionStorage, indexedDB, asyncIndexedDB, or custom"
+      });
+      throw new Error(
+        `Unsupported cache type: ${options.cacheType}. Valid types: memory, localStorage, sessionStorage, indexedDB, asyncIndexedDB, custom.`
+      );
   }
   if (options.twoLayer && Object.keys(options.twoLayer).length > 0) {
     return new TwoLayerCacheMap(underlyingCache, options.twoLayer);
@@ -5762,19 +6021,29 @@ Did you mean: ${suggestions.join(", ")}?`;
     throw new Error(errorMessage);
   }
   if (options.cacheType === "custom" && !options.customCacheMapFactory) {
-    throw new Error('customCacheMapFactory is required when cacheType is "custom"');
+    throw new Error(
+      'customCacheMapFactory is required when cacheType is "custom". Provide a factory function that creates your custom CacheMap implementation.'
+    );
   }
   if (typeof options.maxRetries === "number" && options.maxRetries < 0) {
-    throw new Error("maxRetries must be non-negative");
+    throw new Error(
+      `maxRetries must be non-negative, got ${options.maxRetries}. Suggestion: Use 0 or positive integer for retry attempts.`
+    );
   }
   if (typeof options.retryDelay === "number" && options.retryDelay < 0) {
-    throw new Error("retryDelay must be non-negative");
+    throw new Error(
+      `retryDelay must be non-negative, got ${options.retryDelay}ms. Suggestion: Use 0 or positive number for delay in milliseconds.`
+    );
   }
   if (typeof options.ttl === "number" && options.ttl <= 0) {
-    throw new Error("ttl must be positive");
+    throw new Error(
+      `ttl must be positive, got ${options.ttl}. Suggestion: Use positive number for TTL in seconds, or 0 to disable TTL.`
+    );
   }
   if (typeof options.memoryConfig?.maxItems === "number" && options.memoryConfig.maxItems <= 0) {
-    throw new Error("memoryConfig.maxItems must be positive");
+    throw new Error(
+      `memoryConfig.maxItems must be positive, got ${options.memoryConfig.maxItems}. Suggestion: Use positive integer for maximum cache items.`
+    );
   }
   if (options.memoryConfig?.size) {
     validateSizeConfig(options.memoryConfig.size);
@@ -5874,16 +6143,43 @@ Did you mean: ${suggestions.join(", ")}?`);
   if (["localStorage", "sessionStorage"].includes(options.cacheType)) {
     const isRealBrowser = typeof window !== "undefined" && typeof window.document !== "undefined" && typeof window.document.createElement === "function";
     if (!isRealBrowser) {
-      throw new Error(`${options.cacheType} is not available in non-browser environments`);
+      logger25.error("Browser cache type used in non-browser environment", {
+        component: "cache",
+        operation: "validateOptions",
+        cacheType: options.cacheType,
+        environment: typeof window === "undefined" ? "node" : "unknown",
+        suggestion: 'Use cacheType: "memory" for Node.js/server environments, or ensure code runs in browser'
+      });
+      throw new Error(
+        `${options.cacheType} is not available in non-browser environments. Detected environment: ${typeof window === "undefined" ? "Node.js/server" : "non-browser"}. Suggestion: Use cacheType: "memory" for server-side caching.`
+      );
     }
   }
   if (options.cacheType === "indexedDB") {
     if (typeof window === "undefined" || !window.indexedDB) {
-      throw new Error(`${options.cacheType} is not available in this environment`);
+      logger25.error("IndexedDB not available", {
+        component: "cache",
+        operation: "validateOptions",
+        cacheType: "indexedDB",
+        hasWindow: typeof window !== "undefined",
+        hasIndexedDB: typeof window !== "undefined" && !!window.indexedDB,
+        suggestion: "Use memory cache for Node.js, or check browser IndexedDB support"
+      });
+      throw new Error(
+        `IndexedDB is not available in this environment. Browser support required. Suggestion: Use cacheType: "memory" for server-side or unsupported browsers.`
+      );
     }
   }
   if (options.cacheType === "asyncIndexedDB") {
-    throw new Error("asyncIndexedDB cannot be used with synchronous cache factory. Use AsyncIndexDBCacheMap directly for async operations.");
+    logger25.error("AsyncIndexedDB cannot be used with sync factory", {
+      component: "cache",
+      operation: "validateOptions",
+      cacheType: "asyncIndexedDB",
+      suggestion: 'Use AsyncIndexDBCacheMap directly for async operations, or use cacheType: "indexedDB" for sync wrapper'
+    });
+    throw new Error(
+      'asyncIndexedDB cannot be used with synchronous cache factory. Use AsyncIndexDBCacheMap directly for async operations, or use cacheType: "indexedDB" for the sync wrapper.'
+    );
   }
 };
 
@@ -5898,7 +6194,11 @@ var reset = async (coordinate, options) => {
   }
 };
 
+// src/ttl/TTLCalculator.ts
+var logger26 = logger_default.get("TTLCalculator");
+
 // src/ttl/TTLConfig.ts
+var logger27 = logger_default.get("TTLConfig");
 var defaultTTLConfig = {
   item: {
     default: 3600,
@@ -5997,10 +6297,10 @@ var highTrafficTTLConfig = {
 };
 
 // src/cache/warming/CacheWarmer.ts
-var logger25 = logger_default.get("CacheWarmer");
+var logger28 = logger_default.get("CacheWarmer");
 
 // src/Operations.ts
-var logger26 = logger_default.get("Operations");
+var logger29 = logger_default.get("Operations");
 var CacheMapOperations = class {
   constructor(api, coordinate, cacheMap, pkType, options, eventEmitter, ttlManager, evictionManager, statsManager, registry) {
     this.api = api;
@@ -6014,7 +6314,7 @@ var CacheMapOperations = class {
     this.statsManager = statsManager;
     this.registry = registry;
     if (this.options.enableDebugLogging) {
-      logger26.debug("CacheMapOperations initialized", {
+      logger29.debug("CacheMapOperations initialized", {
         cacheType: this.cacheMap.implementationType,
         isTwoLayer: this.cacheMap instanceof TwoLayerCacheMap
       });
@@ -6107,7 +6407,7 @@ var createOperations = (api, coordinate, cacheMap, pkType, options, eventEmitter
 };
 
 // src/eviction/EvictionManager.ts
-var logger27 = logger_default.get("EvictionManager");
+var logger30 = logger_default.get("EvictionManager");
 var EvictionManager = class {
   evictionStrategy;
   constructor(evictionStrategy) {
@@ -6119,7 +6419,7 @@ var EvictionManager = class {
    */
   setEvictionStrategy(strategy) {
     this.evictionStrategy = strategy;
-    logger27.debug("Eviction strategy updated", {
+    logger30.debug("Eviction strategy updated", {
       strategy: strategy?.getStrategyName() || "none"
     });
   }
@@ -6140,13 +6440,13 @@ var EvictionManager = class {
       return;
     }
     try {
-      logger27.debug("EVICTION: Item accessed, updating metadata", {
+      logger30.debug("EVICTION: Item accessed, updating metadata", {
         key,
         strategy: this.evictionStrategy.getStrategyName()
       });
       await this.evictionStrategy.onItemAccessed(key, metadataProvider);
     } catch (error) {
-      logger27.error("EVICTION: Error in eviction strategy onItemAccessed", {
+      logger30.error("EVICTION: Error in eviction strategy onItemAccessed", {
         key,
         error,
         strategy: this.evictionStrategy?.getStrategyName()
@@ -6164,12 +6464,12 @@ var EvictionManager = class {
     const startTime = Date.now();
     const evictedKeys = [];
     if (!this.evictionStrategy) {
-      logger27.debug("EVICTION: No eviction strategy configured", { key });
+      logger30.debug("EVICTION: No eviction strategy configured", { key });
       return evictedKeys;
     }
     try {
       const estimatedSize = estimateValueSize(value);
-      logger27.debug("EVICTION: Item addition started", {
+      logger30.debug("EVICTION: Item addition started", {
         key,
         estimatedSize,
         strategy: this.evictionStrategy.getStrategyName()
@@ -6177,7 +6477,7 @@ var EvictionManager = class {
       const contextStartTime = Date.now();
       const context = await this.createEvictionContext(metadataProvider, estimatedSize);
       const contextDuration = Date.now() - contextStartTime;
-      logger27.debug("EVICTION: Current cache state", {
+      logger30.debug("EVICTION: Current cache state", {
         key,
         currentItemCount: context.currentSize.itemCount,
         currentSizeBytes: context.currentSize.sizeBytes,
@@ -6190,7 +6490,7 @@ var EvictionManager = class {
       const keysToEvict = await this.evictionStrategy.selectForEviction(metadataProvider, context);
       const selectionDuration = Date.now() - selectionStartTime;
       if (keysToEvict.length > 0) {
-        logger27.debug("EVICTION: Items selected for eviction", {
+        logger30.debug("EVICTION: Items selected for eviction", {
           key,
           evictCount: keysToEvict.length,
           keysToEvict,
@@ -6202,7 +6502,7 @@ var EvictionManager = class {
       for (const evictKey of keysToEvict) {
         await this.evictionStrategy.onItemRemoved(evictKey, metadataProvider);
         evictedKeys.push(evictKey);
-        logger27.debug("EVICTION: Marked item for eviction", {
+        logger30.debug("EVICTION: Marked item for eviction", {
           evictedKey: evictKey,
           newKey: key
         });
@@ -6213,7 +6513,7 @@ var EvictionManager = class {
       const addMetadataDuration = Date.now() - addMetadataStart;
       const totalDuration = Date.now() - startTime;
       if (evictedKeys.length > 0) {
-        logger27.debug("EVICTION: Eviction completed", {
+        logger30.debug("EVICTION: Eviction completed", {
           newKey: key,
           evictedCount: evictedKeys.length,
           evictedKeys,
@@ -6224,14 +6524,14 @@ var EvictionManager = class {
           totalDuration
         });
       } else {
-        logger27.debug("EVICTION: No eviction needed", {
+        logger30.debug("EVICTION: No eviction needed", {
           newKey: key,
           estimatedSize,
           totalDuration
         });
       }
     } catch (error) {
-      logger27.error("EVICTION: Error in eviction strategy onItemAdded", {
+      logger30.error("EVICTION: Error in eviction strategy onItemAdded", {
         key,
         error,
         strategy: this.evictionStrategy?.getStrategyName()
@@ -6251,7 +6551,7 @@ var EvictionManager = class {
     try {
       this.evictionStrategy.onItemRemoved(key, metadataProvider);
     } catch (error) {
-      logger27.error("Error in eviction strategy onItemRemoved", { key, error });
+      logger30.error("Error in eviction strategy onItemRemoved", { key, error });
     }
   }
   /**
@@ -6263,15 +6563,15 @@ var EvictionManager = class {
     const startTime = Date.now();
     const evictedKeys = [];
     if (!this.evictionStrategy) {
-      logger27.debug("EVICTION: No eviction strategy configured for manual eviction");
+      logger30.debug("EVICTION: No eviction strategy configured for manual eviction");
       return evictedKeys;
     }
     try {
-      logger27.debug("EVICTION: Manual eviction started", {
+      logger30.debug("EVICTION: Manual eviction started", {
         strategy: this.evictionStrategy.getStrategyName()
       });
       const context = await this.createEvictionContext(metadataProvider);
-      logger27.debug("EVICTION: Manual eviction - current cache state", {
+      logger30.debug("EVICTION: Manual eviction - current cache state", {
         currentItemCount: context.currentSize.itemCount,
         currentSizeBytes: context.currentSize.sizeBytes,
         maxItems: context.limits.maxItems,
@@ -6284,20 +6584,20 @@ var EvictionManager = class {
       }
       const duration = Date.now() - startTime;
       if (evictedKeys.length > 0) {
-        logger27.debug("EVICTION: Manual eviction completed", {
+        logger30.debug("EVICTION: Manual eviction completed", {
           evictedCount: evictedKeys.length,
           evictedKeys,
           strategy: this.evictionStrategy.getStrategyName(),
           duration
         });
       } else {
-        logger27.debug("EVICTION: Manual eviction - no items to evict", {
+        logger30.debug("EVICTION: Manual eviction - no items to evict", {
           strategy: this.evictionStrategy.getStrategyName(),
           duration
         });
       }
     } catch (error) {
-      logger27.error("EVICTION: Error in manual eviction", {
+      logger30.error("EVICTION: Error in manual eviction", {
         error,
         strategy: this.evictionStrategy?.getStrategyName()
       });
@@ -6320,7 +6620,7 @@ var EvictionManager = class {
         this.evictionStrategy.reset();
       }
     }
-    logger27.debug("Eviction manager cleared");
+    logger30.debug("Eviction manager cleared");
   }
   /**
    * Create eviction context from current cache state
@@ -6458,61 +6758,149 @@ var LRUEvictionStrategy = class extends EvictionStrategy {
 // src/eviction/EvictionStrategyValidation.ts
 function validateNumberRange(value, min, max, fieldName) {
   if (typeof value !== "number" || isNaN(value) || !isFinite(value)) {
-    throw new Error(`${fieldName} must be a finite number`);
+    throw new Error(
+      `${fieldName} must be a finite number, got ${typeof value} (${value}). Suggestion: Provide a valid numeric value for ${fieldName}.`
+    );
   }
   if (value < min || value > max) {
-    throw new Error(`${fieldName} must be between ${min} and ${max}, got ${value}`);
+    throw new Error(
+      `${fieldName} must be between ${min} and ${max}, got ${value}. Suggestion: Adjust ${fieldName} to be within the valid range.`
+    );
   }
 }
 function validatePositiveInteger(value, fieldName) {
   if (typeof value !== "number" || isNaN(value) || !isFinite(value)) {
-    throw new Error(`${fieldName} must be a finite number`);
+    throw new Error(
+      `${fieldName} must be a finite number, got ${typeof value} (${value}). Suggestion: Provide a valid numeric value for ${fieldName}.`
+    );
   }
   if (!Number.isInteger(value) || value <= 0) {
-    throw new Error(`${fieldName} must be a positive integer, got ${value}`);
+    throw new Error(
+      `${fieldName} must be a positive integer, got ${value}. Suggestion: Use a positive whole number (1, 2, 3, ...) for ${fieldName}.`
+    );
   }
 }
 function sanitizeLFUConfig(config) {
   const sanitized = { ...config };
   if (typeof sanitized.decayFactor === "number") {
     if (sanitized.decayFactor < 0) {
-      console.warn(`decayFactor must be between 0 and 1, got ${sanitized.decayFactor}. Correcting to 0.`);
+      const warning = {
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeLFUConfig",
+        field: "decayFactor",
+        invalidValue: sanitized.decayFactor,
+        correctedValue: 0,
+        validRange: "0-1",
+        note: "Auto-correcting invalid configuration value"
+      };
+      console.warn("Invalid decayFactor corrected:", JSON.stringify(warning, null, 2));
       sanitized.decayFactor = 0;
     } else if (sanitized.decayFactor > 1) {
-      console.warn(`decayFactor must be between 0 and 1, got ${sanitized.decayFactor}. Correcting to 1.`);
+      const warning = {
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeLFUConfig",
+        field: "decayFactor",
+        invalidValue: sanitized.decayFactor,
+        correctedValue: 1,
+        validRange: "0-1",
+        note: "Auto-correcting invalid configuration value"
+      };
+      console.warn("Invalid decayFactor corrected:", JSON.stringify(warning, null, 2));
       sanitized.decayFactor = 1;
     }
   }
   if (typeof sanitized.decayInterval === "number" && sanitized.decayInterval <= 0) {
-    console.warn(`decayInterval must be positive, got ${sanitized.decayInterval}. Correcting to 300000.`);
+    const warning = {
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      operation: "sanitizeLFUConfig",
+      field: "decayInterval",
+      invalidValue: sanitized.decayInterval,
+      correctedValue: 3e5,
+      minimumValue: 1,
+      note: "Auto-correcting to 5 minutes (300000ms) default"
+    };
+    console.warn("Invalid decayInterval corrected:", JSON.stringify(warning, null, 2));
     sanitized.decayInterval = 3e5;
   }
   if (typeof sanitized.sketchWidth === "number") {
     if (sanitized.sketchWidth <= 0) {
-      console.warn(`sketchWidth must be positive, got ${sanitized.sketchWidth}. Correcting to 1024.`);
+      console.warn("Invalid sketchWidth corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        field: "sketchWidth",
+        invalidValue: sanitized.sketchWidth,
+        correctedValue: 1024,
+        note: "Auto-correcting invalid configuration"
+      }, null, 2));
       sanitized.sketchWidth = 1024;
     } else if (sanitized.sketchWidth < 16) {
-      console.warn(`sketchWidth should be at least 16 for optimal performance, got ${sanitized.sketchWidth}. Correcting to 16.`);
+      console.warn("Suboptimal sketchWidth corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        field: "sketchWidth",
+        invalidValue: sanitized.sketchWidth,
+        correctedValue: 16,
+        minimumRecommended: 16,
+        note: "Correcting for optimal performance"
+      }, null, 2));
       sanitized.sketchWidth = 16;
     } else if (sanitized.sketchWidth > 65536) {
-      console.warn(`sketchWidth should not exceed 65536 for optimal performance, got ${sanitized.sketchWidth}. Correcting to 65536.`);
+      console.warn("Excessive sketchWidth corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        field: "sketchWidth",
+        invalidValue: sanitized.sketchWidth,
+        correctedValue: 65536,
+        maximumRecommended: 65536,
+        note: "Correcting for optimal performance"
+      }, null, 2));
       sanitized.sketchWidth = 65536;
     }
   }
   if (typeof sanitized.sketchDepth === "number") {
     if (sanitized.sketchDepth <= 0) {
-      console.warn(`sketchDepth must be positive, got ${sanitized.sketchDepth}. Correcting to 4.`);
+      console.warn("Invalid sketchDepth corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        field: "sketchDepth",
+        invalidValue: sanitized.sketchDepth,
+        correctedValue: 4
+      }, null, 2));
       sanitized.sketchDepth = 4;
     } else if (sanitized.sketchDepth < 1) {
-      console.warn(`sketchDepth should be at least 1 for optimal accuracy, got ${sanitized.sketchDepth}. Correcting to 1.`);
+      console.warn("Suboptimal sketchDepth corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        field: "sketchDepth",
+        invalidValue: sanitized.sketchDepth,
+        correctedValue: 1,
+        minimumRecommended: 1
+      }, null, 2));
       sanitized.sketchDepth = 1;
     } else if (sanitized.sketchDepth > 16) {
-      console.warn(`sketchDepth should not exceed 16 for optimal accuracy, got ${sanitized.sketchDepth}. Correcting to 16.`);
+      console.warn("Excessive sketchDepth corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        field: "sketchDepth",
+        invalidValue: sanitized.sketchDepth,
+        correctedValue: 16,
+        maximumRecommended: 16
+      }, null, 2));
       sanitized.sketchDepth = 16;
     }
   }
   if (typeof sanitized.minFrequencyThreshold === "number" && sanitized.minFrequencyThreshold <= 0) {
-    console.warn(`minFrequencyThreshold must be positive, got ${sanitized.minFrequencyThreshold}. Correcting to 1.`);
+    console.warn("Invalid minFrequencyThreshold corrected:", JSON.stringify({
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      field: "minFrequencyThreshold",
+      invalidValue: sanitized.minFrequencyThreshold,
+      correctedValue: 1,
+      minimumValue: 1
+    }, null, 2));
     sanitized.minFrequencyThreshold = 1;
   }
   return sanitized;
@@ -6543,32 +6931,86 @@ function validateLFUConfig(config) {
 function sanitizeARCConfig(config) {
   const sanitized = { ...config };
   if (typeof sanitized.maxCacheSize === "number" && sanitized.maxCacheSize <= 0) {
-    console.warn(`maxCacheSize must be positive, got ${sanitized.maxCacheSize}. Correcting to 1000.`);
+    console.warn("Invalid maxCacheSize corrected:", JSON.stringify({
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      operation: "sanitizeARCConfig",
+      field: "maxCacheSize",
+      invalidValue: sanitized.maxCacheSize,
+      correctedValue: 1e3
+    }, null, 2));
     sanitized.maxCacheSize = 1e3;
   }
   if (typeof sanitized.frequencyThreshold === "number" && sanitized.frequencyThreshold <= 0) {
-    console.warn(`frequencyThreshold must be positive, got ${sanitized.frequencyThreshold}. Correcting to 2.`);
+    console.warn("Invalid frequencyThreshold corrected:", JSON.stringify({
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      operation: "sanitizeARCConfig",
+      field: "frequencyThreshold",
+      invalidValue: sanitized.frequencyThreshold,
+      correctedValue: 2
+    }, null, 2));
     sanitized.frequencyThreshold = 2;
   }
   if (typeof sanitized.frequencyDecayFactor === "number") {
     if (sanitized.frequencyDecayFactor < 0) {
-      console.warn(`frequencyDecayFactor must be between 0 and 1, got ${sanitized.frequencyDecayFactor}. Correcting to 0.`);
+      console.warn("Invalid frequencyDecayFactor corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeARCConfig",
+        field: "frequencyDecayFactor",
+        invalidValue: sanitized.frequencyDecayFactor,
+        correctedValue: 0,
+        validRange: "0-1"
+      }, null, 2));
       sanitized.frequencyDecayFactor = 0;
     } else if (sanitized.frequencyDecayFactor > 1) {
-      console.warn(`frequencyDecayFactor must be between 0 and 1, got ${sanitized.frequencyDecayFactor}. Correcting to 1.`);
+      console.warn("Invalid frequencyDecayFactor corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeARCConfig",
+        field: "frequencyDecayFactor",
+        invalidValue: sanitized.frequencyDecayFactor,
+        correctedValue: 1,
+        validRange: "0-1"
+      }, null, 2));
       sanitized.frequencyDecayFactor = 1;
     }
   }
   if (typeof sanitized.frequencyDecayInterval === "number" && sanitized.frequencyDecayInterval <= 0) {
-    console.warn(`frequencyDecayInterval must be positive, got ${sanitized.frequencyDecayInterval}. Correcting to 60000.`);
+    console.warn("Invalid frequencyDecayInterval corrected:", JSON.stringify({
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      operation: "sanitizeARCConfig",
+      field: "frequencyDecayInterval",
+      invalidValue: sanitized.frequencyDecayInterval,
+      correctedValue: 6e4,
+      note: "Corrected to 1 minute default"
+    }, null, 2));
     sanitized.frequencyDecayInterval = 6e4;
   }
   if (typeof sanitized.adaptiveLearningRate === "number") {
     if (sanitized.adaptiveLearningRate < 0) {
-      console.warn(`adaptiveLearningRate must be between 0 and 10, got ${sanitized.adaptiveLearningRate}. Correcting to 0.`);
+      console.warn("Invalid adaptiveLearningRate corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeARCConfig",
+        field: "adaptiveLearningRate",
+        invalidValue: sanitized.adaptiveLearningRate,
+        correctedValue: 0,
+        validRange: "0-10"
+      }, null, 2));
       sanitized.adaptiveLearningRate = 0;
     } else if (sanitized.adaptiveLearningRate > 10) {
-      console.warn(`adaptiveLearningRate must be between 0 and 10, got ${sanitized.adaptiveLearningRate}. Correcting to 10.`);
+      console.warn("Invalid adaptiveLearningRate corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeARCConfig",
+        field: "adaptiveLearningRate",
+        invalidValue: sanitized.adaptiveLearningRate,
+        correctedValue: 10,
+        validRange: "0-10"
+      }, null, 2));
       sanitized.adaptiveLearningRate = 10;
     }
   }
@@ -6594,24 +7036,62 @@ function validateARCConfig(config) {
 function sanitizeTwoQueueConfig(config) {
   const sanitized = { ...config };
   if (typeof sanitized.maxCacheSize === "number" && sanitized.maxCacheSize <= 0) {
-    console.warn(`maxCacheSize must be positive, got ${sanitized.maxCacheSize}. Correcting to 1000.`);
+    console.warn("Invalid maxCacheSize corrected:", JSON.stringify({
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      operation: "sanitizeTwoQueueConfig",
+      field: "maxCacheSize",
+      invalidValue: sanitized.maxCacheSize,
+      correctedValue: 1e3
+    }, null, 2));
     sanitized.maxCacheSize = 1e3;
   }
   if (typeof sanitized.promotionThreshold === "number" && sanitized.promotionThreshold <= 0) {
-    console.warn(`promotionThreshold must be positive, got ${sanitized.promotionThreshold}. Correcting to 2.`);
+    console.warn("Invalid promotionThreshold corrected:", JSON.stringify({
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      operation: "sanitizeTwoQueueConfig",
+      field: "promotionThreshold",
+      invalidValue: sanitized.promotionThreshold,
+      correctedValue: 2
+    }, null, 2));
     sanitized.promotionThreshold = 2;
   }
   if (typeof sanitized.hotQueueDecayFactor === "number") {
     if (sanitized.hotQueueDecayFactor < 0) {
-      console.warn(`hotQueueDecayFactor must be between 0 and 1, got ${sanitized.hotQueueDecayFactor}. Correcting to 0.`);
+      console.warn("Invalid hotQueueDecayFactor corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeTwoQueueConfig",
+        field: "hotQueueDecayFactor",
+        invalidValue: sanitized.hotQueueDecayFactor,
+        correctedValue: 0,
+        validRange: "0-1"
+      }, null, 2));
       sanitized.hotQueueDecayFactor = 0;
     } else if (sanitized.hotQueueDecayFactor > 1) {
-      console.warn(`hotQueueDecayFactor must be between 0 and 1, got ${sanitized.hotQueueDecayFactor}. Correcting to 1.`);
+      console.warn("Invalid hotQueueDecayFactor corrected:", JSON.stringify({
+        component: "cache",
+        subcomponent: "EvictionStrategyValidation",
+        operation: "sanitizeTwoQueueConfig",
+        field: "hotQueueDecayFactor",
+        invalidValue: sanitized.hotQueueDecayFactor,
+        correctedValue: 1,
+        validRange: "0-1"
+      }, null, 2));
       sanitized.hotQueueDecayFactor = 1;
     }
   }
   if (typeof sanitized.hotQueueDecayInterval === "number" && sanitized.hotQueueDecayInterval <= 0) {
-    console.warn(`hotQueueDecayInterval must be positive, got ${sanitized.hotQueueDecayInterval}. Correcting to 300000.`);
+    console.warn("Invalid hotQueueDecayInterval corrected:", JSON.stringify({
+      component: "cache",
+      subcomponent: "EvictionStrategyValidation",
+      operation: "sanitizeTwoQueueConfig",
+      field: "hotQueueDecayInterval",
+      invalidValue: sanitized.hotQueueDecayInterval,
+      correctedValue: 3e5,
+      note: "Corrected to 5 minutes default"
+    }, null, 2));
     sanitized.hotQueueDecayInterval = 3e5;
   }
   return sanitized;
@@ -7658,7 +8138,7 @@ function createEvictionStrategy(policy, maxCacheSize, config) {
 }
 
 // src/ttl/TTLManager.ts
-var logger28 = logger_default.get("TTLManager");
+var logger31 = logger_default.get("TTLManager");
 var TTLManager = class {
   config;
   cleanupTimer;
@@ -7670,7 +8150,7 @@ var TTLManager = class {
       validateOnAccess: true,
       ...config
     };
-    logger28.debug("TTL_DEBUG: TTLManager created", {
+    logger31.debug("TTL_DEBUG: TTLManager created", {
       config: this.config,
       isTTLEnabled: this.isTTLEnabled(),
       defaultTTL: this.config.defaultTTL
@@ -7703,13 +8183,13 @@ var TTLManager = class {
         this.startAutoCleanup();
       }
     }
-    logger28.debug("TTL configuration updated", { config: this.config });
+    logger31.debug("TTL configuration updated", { config: this.config });
   }
   /**
    * Set TTL metadata for an item when it's added
    */
   async onItemAdded(key, metadataProvider, itemTTL) {
-    logger28.debug("TTL_DEBUG: onItemAdded called", {
+    logger31.debug("TTL_DEBUG: onItemAdded called", {
       key,
       itemTTL,
       isTTLEnabled: this.isTTLEnabled(),
@@ -7717,19 +8197,19 @@ var TTLManager = class {
       metadataProviderType: metadataProvider?.constructor?.name
     });
     if (!this.isTTLEnabled() && !itemTTL) {
-      logger28.debug("TTL_DEBUG: No TTL configured for item - returning early", { key });
+      logger31.debug("TTL_DEBUG: No TTL configured for item - returning early", { key });
       return;
     }
-    logger28.debug("TTL_DEBUG: Getting metadata for key", { key });
+    logger31.debug("TTL_DEBUG: Getting metadata for key", { key });
     const metadata = await metadataProvider.getMetadata(key);
-    logger28.debug("TTL_DEBUG: Retrieved metadata", {
+    logger31.debug("TTL_DEBUG: Retrieved metadata", {
       key,
       hasMetadata: !!metadata,
       metadataKeys: metadata ? Object.keys(metadata) : null,
       metadata
     });
     if (!metadata) {
-      logger28.debug("TTL_DEBUG: No metadata found for item when setting TTL", {
+      logger31.debug("TTL_DEBUG: No metadata found for item when setting TTL", {
         key,
         metadataProviderType: metadataProvider?.constructor?.name,
         metadataProviderMethods: metadataProvider ? Object.getOwnPropertyNames(Object.getPrototypeOf(metadataProvider)) : null
@@ -7737,7 +8217,7 @@ var TTLManager = class {
       return;
     }
     const ttl = itemTTL || this.config.defaultTTL;
-    logger28.debug("TTL_DEBUG: Calculated TTL value", {
+    logger31.debug("TTL_DEBUG: Calculated TTL value", {
       key,
       itemTTL,
       defaultTTL: this.config.defaultTTL,
@@ -7750,7 +8230,7 @@ var TTLManager = class {
         expiresAt: metadata.addedAt + ttl,
         ttl
       };
-      logger28.debug("TTL_DEBUG: Setting TTL metadata", {
+      logger31.debug("TTL_DEBUG: Setting TTL metadata", {
         key,
         ttl,
         addedAt: metadata.addedAt,
@@ -7758,9 +8238,9 @@ var TTLManager = class {
         ttlMetadata
       });
       await metadataProvider.setMetadata(key, ttlMetadata);
-      logger28.trace("TTL_DEBUG: TTL set for item", { key, ttl, expiresAt: ttlMetadata.expiresAt });
+      logger31.trace("TTL_DEBUG: TTL set for item", { key, ttl, expiresAt: ttlMetadata.expiresAt });
     } else {
-      logger28.debug("TTL_DEBUG: No TTL set - invalid TTL value", { key, ttl });
+      logger31.debug("TTL_DEBUG: No TTL set - invalid TTL value", { key, ttl });
     }
   }
   /**
@@ -7769,14 +8249,14 @@ var TTLManager = class {
   async isExpired(key, metadataProvider) {
     const metadata = await metadataProvider.getMetadata(key);
     if (!metadata || !metadata.expiresAt) {
-      logger28.debug("TTL_CHECK: No TTL set for item", { key, hasMetadata: !!metadata });
+      logger31.debug("TTL_CHECK: No TTL set for item", { key, hasMetadata: !!metadata });
       return false;
     }
     const now = Date.now();
     const expired = now >= metadata.expiresAt;
     const remainingMs = metadata.expiresAt - now;
     if (expired) {
-      logger28.debug("TTL_CHECK: Item EXPIRED", {
+      logger31.debug("TTL_CHECK: Item EXPIRED", {
         key,
         expiresAt: new Date(metadata.expiresAt).toISOString(),
         now: new Date(now).toISOString(),
@@ -7784,7 +8264,7 @@ var TTLManager = class {
         ttl: metadata.ttl
       });
     } else {
-      logger28.debug("TTL_CHECK: Item still valid", {
+      logger31.debug("TTL_CHECK: Item still valid", {
         key,
         expiresAt: new Date(metadata.expiresAt).toISOString(),
         remainingMs,
@@ -7800,17 +8280,17 @@ var TTLManager = class {
    */
   async validateItem(key, metadataProvider) {
     if (!this.config.validateOnAccess) {
-      logger28.debug("TTL_VALIDATE: Validation disabled, skipping check", { key });
+      logger31.debug("TTL_VALIDATE: Validation disabled, skipping check", { key });
       return true;
     }
-    logger28.debug("TTL_VALIDATE: Validating item", {
+    logger31.debug("TTL_VALIDATE: Validating item", {
       key,
       ttlEnabled: this.isTTLEnabled(),
       defaultTTL: this.config.defaultTTL
     });
     const isExpired = await this.isExpired(key, metadataProvider);
     const isValid = !isExpired;
-    logger28.debug("TTL_VALIDATE: Validation result", {
+    logger31.debug("TTL_VALIDATE: Validation result", {
       key,
       isValid,
       isExpired
@@ -7844,7 +8324,7 @@ var TTLManager = class {
     const expiredKeys = [];
     const allMetadata = await metadataProvider.getAllMetadata();
     const now = Date.now();
-    logger28.debug("TTL_CLEANUP: Scanning for expired items", {
+    logger31.debug("TTL_CLEANUP: Scanning for expired items", {
       totalItems: allMetadata.size,
       now: new Date(now).toISOString()
     });
@@ -7855,7 +8335,7 @@ var TTLManager = class {
         itemsWithTTL++;
         if (now >= ttlMetadata.expiresAt) {
           expiredKeys.push(key);
-          logger28.debug("TTL_CLEANUP: Found expired item", {
+          logger31.debug("TTL_CLEANUP: Found expired item", {
             key,
             expiresAt: new Date(ttlMetadata.expiresAt).toISOString(),
             expiredByMs: now - ttlMetadata.expiresAt
@@ -7865,7 +8345,7 @@ var TTLManager = class {
     }
     const duration = Date.now() - startTime;
     if (expiredKeys.length > 0) {
-      logger28.debug("TTL_CLEANUP: Expired items found", {
+      logger31.debug("TTL_CLEANUP: Expired items found", {
         expiredCount: expiredKeys.length,
         totalItems: allMetadata.size,
         itemsWithTTL,
@@ -7873,7 +8353,7 @@ var TTLManager = class {
         duration
       });
     } else {
-      logger28.debug("TTL_CLEANUP: No expired items found", {
+      logger31.debug("TTL_CLEANUP: No expired items found", {
         totalItems: allMetadata.size,
         itemsWithTTL,
         duration
@@ -7905,7 +8385,7 @@ var TTLManager = class {
     }
     metadata.expiresAt += additionalTTL;
     await metadataProvider.setMetadata(key, metadata);
-    logger28.trace("TTL extended for item", { key, additionalTTL, newExpiresAt: metadata.expiresAt });
+    logger31.trace("TTL extended for item", { key, additionalTTL, newExpiresAt: metadata.expiresAt });
     return true;
   }
   /**
@@ -7927,7 +8407,7 @@ var TTLManager = class {
       ttl
     };
     await metadataProvider.setMetadata(key, ttlMetadata);
-    logger28.trace("TTL refreshed for item", { key, ttl, expiresAt: ttlMetadata.expiresAt });
+    logger31.trace("TTL refreshed for item", { key, ttl, expiresAt: ttlMetadata.expiresAt });
     return true;
   }
   /**
@@ -7939,9 +8419,9 @@ var TTLManager = class {
     }
     if (this.config.cleanupInterval) {
       this.cleanupTimer = setInterval(() => {
-        logger28.trace("Auto cleanup timer triggered");
+        logger31.trace("Auto cleanup timer triggered");
       }, this.config.cleanupInterval);
-      logger28.debug("Auto cleanup started", { interval: this.config.cleanupInterval });
+      logger31.debug("Auto cleanup started", { interval: this.config.cleanupInterval });
     }
   }
   /**
@@ -7951,7 +8431,7 @@ var TTLManager = class {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = null;
-      logger28.debug("Auto cleanup stopped");
+      logger31.debug("Auto cleanup stopped");
     }
   }
   /**
@@ -7959,18 +8439,31 @@ var TTLManager = class {
    */
   clear() {
     this.stopAutoCleanup();
-    logger28.debug("TTL manager cleared");
+    logger31.debug("TTL manager cleared");
   }
   /**
    * Cleanup resources
    */
   destroy() {
+    logger31.debug("TTL manager destroy started", {
+      component: "cache",
+      subcomponent: "TTLManager",
+      operation: "destroy",
+      autoCleanupEnabled: !!this.config.cleanupInterval,
+      note: "Stopping auto-cleanup and clearing TTL data"
+    });
     this.stopAutoCleanup();
-    logger28.debug("TTL manager destroyed");
+    logger31.debug("TTL manager destroyed", {
+      component: "cache",
+      subcomponent: "TTLManager",
+      operation: "destroy",
+      note: "All TTL tracking data cleared"
+    });
   }
 };
 
 // src/events/CacheEventEmitter.ts
+var logger32 = logger_default.get("CacheEventEmitter");
 var CacheEventEmitter = class {
   subscriptions = /* @__PURE__ */ new Map();
   nextSubscriptionId = 1;
@@ -8071,9 +8564,17 @@ var CacheEventEmitter = class {
    */
   emit(event) {
     if (this.isDestroyed) {
+      logger32.debug("Event emission skipped - emitter is destroyed", {
+        component: "cache",
+        subcomponent: "CacheEventEmitter",
+        eventType: event.type,
+        suggestion: "This is expected during cleanup. Ensure emitter is not used after destroy()."
+      });
       return;
     }
     let emittedCount = 0;
+    const totalSubscriptions = this.subscriptions.size;
+    const activeSubscriptions = Array.from(this.subscriptions.values()).filter((s) => s.isActive).length;
     for (const subscription of this.subscriptions.values()) {
       if (!subscription.isActive) {
         continue;
@@ -8083,6 +8584,17 @@ var CacheEventEmitter = class {
         emittedCount++;
       }
     }
+    logger32.trace("Event emitted to subscriptions", {
+      component: "cache",
+      subcomponent: "CacheEventEmitter",
+      eventType: event.type,
+      eventSource: event.source,
+      eventKey: "key" in event ? JSON.stringify(event.key) : void 0,
+      totalSubscriptions,
+      activeSubscriptions,
+      emittedCount,
+      note: emittedCount === 0 ? "No subscriptions matched this event" : void 0
+    });
   }
   /**
    * Get count of active subscriptions
@@ -8287,20 +8799,36 @@ var CacheEventEmitter = class {
    */
   handleListenerError(error, event, subscription) {
     const errorObj = error instanceof Error ? error : new Error(String(error));
+    const errorContext = {
+      component: "CacheEventEmitter",
+      operation: "event-listener",
+      eventType: event.type,
+      eventKey: "key" in event ? JSON.stringify(event.key) : void 0,
+      subscriptionId: subscription.id,
+      errorType: errorObj.constructor.name,
+      errorMessage: errorObj.message,
+      suggestion: "Review event listener implementation for errors. Consider adding error handling in the listener.",
+      stack: errorObj.stack
+    };
     if (subscription.options.onError) {
       try {
         subscription.options.onError(errorObj, event);
       } catch (handlerError) {
-        console.error("Error in cache event listener:", errorObj);
+        console.error("Error in cache event listener:", JSON.stringify(errorContext, null, 2));
+        console.error("Original error:", errorObj);
         console.error("Error in error handler:", handlerError);
+        console.error("Critical: Both the event listener and its error handler failed. Review error handling logic.");
       }
     } else {
-      console.error("Error in cache event listener:", errorObj);
+      console.error("Error in cache event listener (no error handler configured):", JSON.stringify(errorContext, null, 2));
+      console.error("Original error:", errorObj);
+      console.error("Suggestion: Add an onError handler to your subscription to handle listener errors gracefully.");
     }
   }
 };
 
 // src/CacheStats.ts
+var logger33 = logger_default.get("CacheStats");
 var CacheStatsManager = class {
   stats = {
     numRequests: 0,
@@ -8310,11 +8838,22 @@ var CacheStatsManager = class {
     numUnsubscriptions: 0,
     activeSubscriptions: 0
   };
+  lastLoggedStats = {
+    numRequests: 0,
+    numMisses: 0,
+    numHits: 0,
+    numSubscriptions: 0,
+    numUnsubscriptions: 0,
+    activeSubscriptions: 0
+  };
+  LOG_THRESHOLD = 100;
+  // Log every 100 requests
   /**
    * Increment the request counter
    */
   incrementRequests() {
     this.stats.numRequests++;
+    this.maybeLogStats();
   }
   /**
    * Increment the cache hit counter
@@ -8328,6 +8867,27 @@ var CacheStatsManager = class {
   incrementMisses() {
     this.stats.numMisses++;
   }
+  /**
+   * Log statistics periodically for monitoring
+   */
+  maybeLogStats() {
+    const requestsSinceLastLog = this.stats.numRequests - this.lastLoggedStats.numRequests;
+    if (requestsSinceLastLog >= this.LOG_THRESHOLD) {
+      const hitRate = this.stats.numRequests > 0 ? (this.stats.numHits / this.stats.numRequests * 100).toFixed(2) : "0.00";
+      logger33.debug("Cache statistics update", {
+        component: "cache",
+        subcomponent: "CacheStatsManager",
+        totalRequests: this.stats.numRequests,
+        hits: this.stats.numHits,
+        misses: this.stats.numMisses,
+        hitRate: `${hitRate}%`,
+        activeSubscriptions: this.stats.activeSubscriptions,
+        requestsSinceLastLog,
+        note: `Statistics logged every ${this.LOG_THRESHOLD} requests for monitoring`
+      });
+      this.lastLoggedStats = { ...this.stats };
+    }
+  }
   /**
    * Increment the subscription counter
    */
@@ -8366,9 +8926,17 @@ var CacheStatsManager = class {
 };
 
 // src/Cache.ts
-var logger29 = logger_default.get("Cache");
+var logger34 = logger_default.get("Cache");
 var createCache = (api, coordinate, registry, options) => {
-  logger29.debug("createCache", { coordinate, registry, options });
+  logger34.debug("createCache", {
+    component: "cache",
+    operation: "createCache",
+    itemType: coordinate.kta[0],
+    hierarchy: coordinate.kta,
+    cacheType: options?.cacheType,
+    hasRegistry: !!registry,
+    note: "Cache creation started"
+  });
   const completeOptions = createOptions(options);
   const cacheMap = createCacheMap(coordinate.kta, completeOptions);
   const pkType = coordinate.kta[0];
@@ -8448,18 +9016,24 @@ var isCache2 = (cache) => {
 };
 
 // src/InstanceFactory.ts
-var logger30 = logger_default.get("InstanceFactory");
+var logger35 = logger_default.get("InstanceFactory");
 var createInstanceFactory = (api, options) => {
   const templateOptions = createOptions(options);
   validateOptions(templateOptions);
   return (coordinate, context) => {
     const instanceOptions = createOptions(options);
-    logger30.debug("Creating cache instance", {
-      coordinate,
-      registry: context.registry,
-      api,
+    logger35.debug("Creating cache instance", {
+      component: "cache",
+      operation: "createInstance",
+      itemType: coordinate.kta[0],
+      hierarchy: coordinate.kta,
       cacheType: instanceOptions.cacheType,
-      options: instanceOptions
+      ttlEnabled: !!instanceOptions.ttl,
+      ttlValue: instanceOptions.ttl,
+      evictionEnabled: !!instanceOptions.evictionConfig,
+      evictionStrategy: instanceOptions.evictionConfig?.type,
+      twoLayerEnabled: !!instanceOptions.twoLayer,
+      note: "Cache instance initialization started"
     });
     const cacheMap = createCacheMap(coordinate.kta, instanceOptions);
     const pkType = coordinate.kta[0];
@@ -8521,9 +9095,9 @@ var createInstanceFactory = (api, options) => {
 };
 
 // src/Instance.ts
-var logger31 = logger_default.get("Instance");
+var logger36 = logger_default.get("Instance");
 var createInstance = (registry, coordinate, api, options) => {
-  logger31.debug("createInstance", { coordinate, api, registry, options });
+  logger36.debug("createInstance", { coordinate, api, registry, options });
   return createCache(api, coordinate, registry, options);
 };
 var isInstance = (instance) => {
@@ -8531,7 +9105,7 @@ var isInstance = (instance) => {
 };
 
 // src/Aggregator.ts
-var logger32 = logger_default.get("ItemAggregator");
+var logger37 = logger_default.get("ItemAggregator");
 var toCacheConfig = (config) => {
   let cacheConfig;
   if (config.optional === void 0) {
@@ -8543,23 +9117,32 @@ var toCacheConfig = (config) => {
 };
 var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
   const populate = async (item) => {
-    logger32.default("populate", { item });
+    logger37.default("populate", { item });
     for (const key in aggregates) {
       await populateAggregate(key, item);
     }
     for (const key in events) {
       await populateEvent(key, item);
     }
-    logger32.default("populate done", { item });
+    logger37.default("populate done", { item });
     return item;
   };
   const populateAggregate = async (key, item) => {
-    logger32.default("populate aggregate key", { key });
+    logger37.default("populate aggregate key", { key });
     const cacheConfig = toCacheConfig(aggregates[key]);
     if (item.refs === void 0) {
       if (cacheConfig.optional === false) {
-        logger32.error("Item does not have refs an is not optional ", { item });
-        throw new Error("Item does not have refs an is not optional " + JSON.stringify(item));
+        logger37.error("Item missing required refs property", {
+          component: "cache",
+          subcomponent: "Aggregator",
+          operation: "populateRef",
+          refKey: key,
+          item: JSON.stringify(item),
+          suggestion: "Ensure the item has a refs property or mark this reference as optional in cache configuration"
+        });
+        throw new Error(
+          `Item missing required refs property for reference '${key}'. Item: ${JSON.stringify(item)}. Suggestion: Add refs property to item or set optional: true in cache config.`
+        );
       } else {
         if (item.events && Object.prototype.hasOwnProperty.call(item.events, key)) {
           delete item.events[key];
@@ -8567,8 +9150,18 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
       }
     } else if (item.refs[key] === void 0) {
       if (cacheConfig.optional === false) {
-        logger32.error("Item does not have mandatory ref with key, not optional ", { key, item });
-        throw new Error("Item does not have mandatory ref with key, not optional " + key + " " + JSON.stringify(item));
+        logger37.error("Item missing required reference", {
+          component: "cache",
+          subcomponent: "Aggregator",
+          operation: "populateRef",
+          refKey: key,
+          availableRefs: Object.keys(item.refs || {}),
+          item: JSON.stringify(item),
+          suggestion: `Ensure the item has refs.${key} property or mark this reference as optional in cache configuration`
+        });
+        throw new Error(
+          `Item missing required reference '${key}'. Available refs: [${Object.keys(item.refs || {}).join(", ")}]. Item: ${JSON.stringify(item)}. Suggestion: Add refs.${key} to item or set optional: true in cache config.`
+        );
       } else {
         if (item.events && Object.prototype.hasOwnProperty.call(item.events, key)) {
           delete item.events[key];
@@ -8576,7 +9169,7 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
       }
     } else {
       const ref = item.refs[key];
-      logger32.default("AGG Retrieving Item in Populate", { key: ref });
+      logger37.default("AGG Retrieving Item in Populate", { key: ref });
       const newItem = await cacheConfig.cache.operations.retrieve(ref);
       if (newItem) {
         if (item.aggs === void 0) {
@@ -8593,25 +9186,52 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
     }
   };
   const populateEvent = async (key, item) => {
-    logger32.default("populate event key", { key });
+    logger37.default("populate event key", { key });
     const cacheConfig = toCacheConfig(events[key]);
     if (item.events === void 0) {
-      throw new Error("Item does not have events " + JSON.stringify(item));
+      logger37.error("Item missing events property", {
+        component: "cache",
+        subcomponent: "Aggregator",
+        operation: "populateEvent",
+        eventKey: key,
+        item: JSON.stringify(item),
+        suggestion: "Ensure the item has an events property with event data"
+      });
+      throw new Error(
+        `Item missing events property for event '${key}'. Item: ${JSON.stringify(item)}. Suggestion: Ensure events are properly tracked on this item type.`
+      );
     } else if (item.events[key] === void 0) {
       if (cacheConfig.optional === false) {
-        logger32.error("Item does not have mandatory event with key", { key, item });
-        throw new Error("Item does not have mandatory event with key " + key + " " + JSON.stringify(item));
+        logger37.error("Item missing required event", {
+          component: "cache",
+          subcomponent: "Aggregator",
+          operation: "populateEvent",
+          eventKey: key,
+          availableEvents: Object.keys(item.events || {}),
+          item: JSON.stringify(item),
+          suggestion: `Ensure the item has events.${key} property or mark this event as optional`
+        });
+        throw new Error(
+          `Item missing required event '${key}'. Available events: [${Object.keys(item.events || {}).join(", ")}]. Item: ${JSON.stringify(item)}. Suggestion: Add events.${key} to item or set optional: true in cache config.`
+        );
       }
     } else {
       const event = item.events[key];
       if (event.by === void 0) {
-        logger32.error(
-          "populateEvent with an Event that does not have by",
-          { event, ik: item.key, eventKey: key }
+        logger37.error('Event missing required "by" field', {
+          component: "cache",
+          subcomponent: "Aggregator",
+          operation: "populateEvent",
+          eventKey: key,
+          event,
+          itemKey: item.key,
+          suggestion: 'Ensure event has a "by" field with the user/actor who triggered the event'
+        });
+        throw new Error(
+          `Event '${key}' missing required "by" field. Event: ${JSON.stringify(event)}. Item: ${JSON.stringify(item.key)}. Suggestion: Events must include a "by" field to track who performed the action.`
         );
-        throw new Error("populateEvent with an Event that does not have by: " + JSON.stringify({ key }));
       }
-      logger32.default("EVENT Retrieving Item in Populate", { key: event.by });
+      logger37.default("EVENT Retrieving Item in Populate", { key: event.by });
       const newItem = await cacheConfig.cache.operations.retrieve(event.by);
       if (newItem) {
         event.agg = newItem;
@@ -8619,13 +9239,13 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
     }
   };
   const all2 = async (query = {}, locations = []) => {
-    logger32.default("all", { query, locations });
+    logger37.default("all", { query, locations });
     const result = await cache.operations.all(query, locations);
     const populatedItems = await Promise.all(result.items.map(async (item) => populate(item)));
     return populatedItems;
   };
   const one2 = async (query = {}, locations = []) => {
-    logger32.default("one", { query, locations });
+    logger37.default("one", { query, locations });
     const item = await cache.operations.one(query, locations);
     let populatedItem = null;
     if (item) {
@@ -8634,30 +9254,30 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
     return populatedItem;
   };
   const action2 = async (key, action3, body = {}) => {
-    logger32.default("action", { key, action: action3, body });
+    logger37.default("action", { key, action: action3, body });
     const [item, affectedItems] = await cache.operations.action(key, action3, body);
     const populatedItem = await populate(item);
     return [populatedItem, affectedItems];
   };
   const allAction2 = async (action3, body = {}, locations = []) => {
-    logger32.default("action", { action: action3, body, locations });
+    logger37.default("action", { action: action3, body, locations });
     const [items, affectedItems] = await cache.operations.allAction(action3, body, locations);
     const populatedItems = await Promise.all(items.map(async (item) => populate(item)));
     return [populatedItems, affectedItems];
   };
   const allFacet2 = async (facet3, params = {}, locations = []) => {
-    logger32.default("allFacet", { facet: facet3, params, locations });
+    logger37.default("allFacet", { facet: facet3, params, locations });
     const response = await cache.operations.allFacet(facet3, params, locations);
     return response;
   };
   const create2 = async (v, locations = []) => {
-    logger32.default("create", { v, locations });
+    logger37.default("create", { v, locations });
     const item = locations.length === 0 ? await cache.operations.create(v) : await cache.operations.create(v, { locations });
     const populatedItem = await populate(item);
     return populatedItem;
   };
   const get2 = async (key) => {
-    logger32.default("get", { key });
+    logger37.default("get", { key });
     const item = await cache.operations.get(key);
     let populatedItem = null;
     if (item) {
@@ -8666,7 +9286,7 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
     return populatedItem;
   };
   const retrieve2 = async (key) => {
-    logger32.default("retrieve", { key });
+    logger37.default("retrieve", { key });
     const item = await cache.operations.retrieve(key);
     let populatedItem = null;
     if (item) {
@@ -8675,22 +9295,22 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
     return populatedItem;
   };
   const remove2 = async (key) => {
-    logger32.default("remove", { key });
+    logger37.default("remove", { key });
     await cache.operations.remove(key);
   };
   const update2 = async (key, v) => {
-    logger32.default("update", { key, v });
+    logger37.default("update", { key, v });
     const item = await cache.operations.update(key, v);
     const populatedItem = await populate(item);
     return populatedItem;
   };
   const facet2 = async (key, facet3) => {
-    logger32.default("facet", { key, facet: facet3 });
+    logger37.default("facet", { key, facet: facet3 });
     const response = await cache.operations.facet(key, facet3);
     return response;
   };
   const find2 = async (finder, finderParams = {}, locations = [], findOptions) => {
-    logger32.default("find", { finder, finderParams, locations, findOptions });
+    logger37.default("find", { finder, finderParams, locations, findOptions });
     const result = await cache.operations.find(finder, finderParams, locations, findOptions);
     const populatedItems = await Promise.all(result.items.map(async (item) => populate(item)));
     return {
@@ -8699,7 +9319,7 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
     };
   };
   const findOne2 = async (finder, finderParams = {}, locations = []) => {
-    logger32.default("find", { finder, finderParams, locations });
+    logger37.default("find", { finder, finderParams, locations });
     const item = await cache.operations.findOne(finder, finderParams, locations);
     if (!item) {
       return null;
@@ -8708,7 +9328,7 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
     return populatedItem;
   };
   const set2 = async (key, v) => {
-    logger32.default("set", { key, v });
+    logger37.default("set", { key, v });
     const item = await cache.operations.set(key, v);
     const populatedItem = await populate(item);
     return populatedItem;
@@ -8760,13 +9380,13 @@ var createAggregator = async (cache, { aggregates = {}, events = {} }) => {
 import {
   createRegistry as createBaseRegistry
 } from "@fjell/registry";
-var logger33 = logger_default.get("Registry");
+var logger38 = logger_default.get("Registry");
 var createRegistryFactory = () => {
   return (type, registryHub) => {
     if (type !== "cache") {
       throw new Error(`Cache registry factory can only create 'cache' type registries, got: ${type}`);
     }
-    logger33.debug("Creating cache registry", { type, registryHub });
+    logger38.debug("Creating cache registry", { type, registryHub });
     const baseRegistry = createBaseRegistry(type, registryHub);
     return baseRegistry;
   };