@asaidimu/utils-cache 3.0.6 → 3.1.0

package/README.md

@@ -48,27 +48,27 @@ An intelligent, configurable in-memory cache library for Node.js and browser env
 
 ### Detailed Description
 
-`@asaidimu/utils-cache` provides a robust, in-memory caching solution designed for applications that require efficient data retrieval, resilience against network failures, and state persistence across sessions or processes. It implements common caching patterns like *stale-while-revalidate* and *Least Recently Used (LRU)* eviction, along with advanced features such as automatic retries for failed fetches, an extensible persistence mechanism, and a comprehensive event system for real-time monitoring.
+`@asaidimu/utils-cache` provides a robust, in-memory caching solution designed for applications that require efficient data retrieval, resilience against network failures, and state persistence across sessions or processes. It implements common caching patterns like _stale-while-revalidate_ and _Least Recently Used (LRU)_ eviction, along with advanced features such as automatic retries for failed fetches, an extensible persistence mechanism, and a comprehensive event system for real-time monitoring.
 
 Unlike simpler caches, `Cache` manages data freshness intelligently, allowing you to serve stale data immediately while a fresh copy is being fetched in the background. Its pluggable persistence layer enables you to save and restore the cache state, making it ideal for client-side applications that need to maintain state offline or server-side applications that need rapid startup with pre-populated data. With built-in metrics and events, `@asaidimu/utils-cache` offers deep insights into cache performance and lifecycle, ensuring both speed and data integrity.
 
 ### Key Features
 
-*   **Configurable In-Memory Store**: Provides fast access to cached data with an underlying `Map` structure.
-*   **Stale-While-Revalidate (SWR)**: Serve existing data immediately while fetching new data in the background, minimizing perceived latency and improving user experience.
-*   **Automatic Retries with Exponential Backoff**: Configurable retry attempts and an exponentially increasing delay between retries for `fetchFunction` failures, enhancing resilience to transient network issues.
-*   **Pluggable Persistence**: Seamlessly integrates with any `SimplePersistence` implementation (e.g., LocalStorage, IndexedDB via `@asaidimu/utils-persistence`, or custom backend) to save and restore cache state across application restarts or sessions.
-    *   **Debounced Persistence Writes**: Optimizes write frequency to the underlying persistence layer, reducing I/O operations and improving performance.
-    *   **Remote Update Handling**: Automatically synchronizes cache state when the persistence layer is updated externally by other instances or processes.
-    *   **Custom Serialization/Deserialization**: Provides options to serialize and deserialize complex data types (e.g., `Date`, `Map`, custom classes) for proper storage and retrieval.
-*   **Configurable Eviction Policies**:
-    *   **Time-Based (TTL)**: Automatically evicts entries that haven't been accessed for a specified `cacheTime`, managing memory efficiently.
-    *   **Size-Based (LRU)**: Evicts least recently used items when the `maxSize` limit is exceeded, preventing unbounded memory growth.
-*   **Comprehensive Event System**: Subscribe to granular, scoped cache events (e.g., `'cache:read:hit'`, `'cache:fetch:start'`, `'cache:data:set'`) for real-time logging, debugging, analytics, and advanced reactivity. Wildcard subscriptions (e.g., `'cache:read:*'`) are supported for capturing related events.
-*   **Performance Metrics**: Built-in tracking for `hits`, `misses`, `fetches`, `errors`, `evictions`, and `staleHits`, providing insights into cache efficiency with calculated hit rates.
-*   **Flexible Query Management**: Register asynchronous `fetchFunction`s for specific keys, allowing the `Cache` instance to intelligently manage their data lifecycle, including fetching, caching, and invalidation.
-*   **Imperative Control**: Offers direct methods for `invalidate` (making data stale), `prefetch` (loading data proactively), `refresh` (forcing a re-fetch), `setData` (manual data injection), and `remove` operations.
-*   **TypeScript Support**: Fully typed API for enhanced developer experience, compile-time safety, and autocompletion.
+- **Configurable In-Memory Store**: Provides fast access to cached data with an underlying `Map` structure.
+- **Stale-While-Revalidate (SWR)**: Serve existing data immediately while fetching new data in the background, minimizing perceived latency and improving user experience.
+- **Automatic Retries with Exponential Backoff**: Configurable retry attempts and an exponentially increasing delay between retries for `fetchFunction` failures, enhancing resilience to transient network issues.
+- **Pluggable Persistence**: Seamlessly integrates with any `SimplePersistence` implementation (e.g., LocalStorage, IndexedDB via `@asaidimu/utils-persistence`, or custom backend) to save and restore cache state across application restarts or sessions.
+  - **Debounced Persistence Writes**: Optimizes write frequency to the underlying persistence layer, reducing I/O operations and improving performance.
+  - **Remote Update Handling**: Automatically synchronizes cache state when the persistence layer is updated externally by other instances or processes.
+  - **Custom Serialization/Deserialization**: Provides options to serialize and deserialize complex data types (e.g., `Date`, `Map`, custom classes) for proper storage and retrieval.
+- **Configurable Eviction Policies**:
+  - **Time-Based (TTL)**: Automatically evicts entries that haven't been accessed for a specified `cacheTime`, managing memory efficiently.
+  - **Size-Based (LRU)**: Evicts least recently used items when the `maxSize` limit is exceeded, preventing unbounded memory growth.
+- **Comprehensive Event System**: Subscribe to granular, scoped cache events (e.g., `'cache:read:hit'`, `'cache:fetch:start'`, `'cache:data:set'`) for real-time logging, debugging, analytics, and advanced reactivity. Wildcard subscriptions (e.g., `'cache:read:*'`) are supported for capturing related events.
+- **Performance Metrics**: Built-in tracking for `hits`, `misses`, `fetches`, `errors`, `evictions`, and `staleHits`, providing insights into cache efficiency with calculated hit rates.
+- **Flexible Query Management**: Register asynchronous `fetchFunction`s for specific keys, allowing the `Cache` instance to intelligently manage their data lifecycle, including fetching, caching, and invalidation.
+- **Imperative Control**: Offers direct methods for `invalidate` (making data stale), `prefetch` (loading data proactively), `refresh` (forcing a re-fetch), `setData` (manual data injection), and `remove` operations.
+- **TypeScript Support**: Fully typed API for enhanced developer experience, compile-time safety, and autocompletion.
 
 ---
 
@@ -76,8 +76,8 @@ Unlike simpler caches, `Cache` manages data freshness intelligently, allowing yo
 
 ### Prerequisites
 
-*   Node.js (v14.x or higher)
-*   npm, yarn, or bun
+- Node.js (v14.x or higher)
+- npm, yarn, or bun
 
 ### Installation Steps
 
@@ -96,33 +96,35 @@ yarn add @asaidimu/utils-cache @asaidimu/events
 `Cache` is initialized with a `CacheOptions` object, allowing you to customize its behavior globally. Individual queries registered via `registerQuery` can override these options for specific data keys.
 
 ```typescript
-import { Cache } from '@asaidimu/utils-cache';
+import { Cache } from "@asaidimu/utils-cache";
 // Example persistence layer (install separately, e.g., @asaidimu/utils-persistence)
-import { IndexedDBPersistence } from '@asaidimu/utils-persistence'; // Example
+import { IndexedDBPersistence } from "@asaidimu/utils-persistence"; // Example
 
 const myCache = new Cache({
-  staleTime: 5 * 60 * 1000,   // Data considered stale after 5 minutes (5 * 60 * 1000ms)
-  cacheTime: 30 * 60 * 1000,  // Data evicted if not accessed for 30 minutes
-  retryAttempts: 2,           // Retry fetch up to 2 times on failure
-  retryDelay: 2000,           // 2-second initial delay between retries (doubles each attempt)
-  maxSize: 500,               // Maximum 500 entries in cache (LRU eviction)
-  enableMetrics: true,        // Enable performance tracking
-  
+  staleTime: 5 * 60 * 1000, // Data considered stale after 5 minutes (5 * 60 * 1000ms)
+  cacheTime: 30 * 60 * 1000, // Data evicted if not accessed for 30 minutes
+  retryAttempts: 2, // Retry fetch up to 2 times on failure
+  retryDelay: 2000, // 2-second initial delay between retries (doubles each attempt)
+  maxSize: 500, // Maximum 500 entries in cache (LRU eviction)
+  enableMetrics: true, // Enable performance tracking
+
   // Persistence options (optional but recommended for stateful caches)
-  persistence: new IndexedDBPersistence('my-app-db'), // Plug in your persistence layer
-  persistenceId: 'my-app-cache-v1', // Unique ID for this cache instance in persistence
+  persistence: new IndexedDBPersistence("my-app-db"), // Plug in your persistence layer
+  persistenceId: "my-app-cache-v1", // Unique ID for this cache instance in persistence
   persistenceDebounceTime: 1000, // Debounce persistence writes by 1 second
 
   // Custom serializers/deserializers for non-JSON-serializable data (optional)
   serializeValue: (value: any) => {
-    if (value instanceof Map) return { _type: 'Map', data: Array.from(value.entries()) };
-    if (value instanceof Date) return { _type: 'Date', data: value.toISOString() };
+    if (value instanceof Map)
+      return { _type: "Map", data: Array.from(value.entries()) };
+    if (value instanceof Date)
+      return { _type: "Date", data: value.toISOString() };
     return value;
   },
   deserializeValue: (value: any) => {
-    if (typeof value === 'object' && value !== null) {
-      if (value._type === 'Map') return new Map(value.data);
-      if (value._type === 'Date') return new Date(value.data);
+    if (typeof value === "object" && value !== null) {
+      if (value._type === "Map") return new Map(value.data);
+      if (value._type === "Date") return new Date(value.data);
     }
     return value;
   },
@@ -138,23 +140,26 @@ const invalidCache = new Cache({ staleTime: -100, cacheTime: -1, maxSize: -5 });
 To verify that `Cache` is installed and initialized correctly, you can run a simple test:
 
 ```typescript
-import { Cache } from '@asaidimu/utils-cache';
+import { Cache } from "@asaidimu/utils-cache";
 
 const cache = new Cache();
-console.log('Cache initialized successfully!');
+console.log("Cache initialized successfully!");
 
 // Register a simple query
-cache.registerQuery('hello', async () => {
+cache.registerQuery("hello", async () => {
   console.log('Fetching "hello" data...');
-  return 'world';
+  return "world";
 });
 
 // Try to fetch data
-cache.get('hello').then(data => {
-  console.log(`Fetched 'hello': ${data}`); // Expected: Fetching "hello" data... \n Fetched 'hello': world
-}).catch(error => {
-  console.error('Error fetching:', error);
-});
+cache
+  .get("hello")
+  .then((data) => {
+    console.log(`Fetched 'hello': ${data}`); // Expected: Fetching "hello" data... \n Fetched 'hello': world
+  })
+  .catch((error) => {
+    console.error("Error fetching:", error);
+  });
 ```
 
 ---
@@ -166,46 +171,50 @@ cache.get('hello').then(data => {
 The core of `Cache` involves registering queries (data fetching functions) and then retrieving data using those queries.
 
 ```typescript
-import { Cache } from '@asaidimu/utils-cache';
+import { Cache } from "@asaidimu/utils-cache";
 
 const myCache = new Cache({
-  staleTime: 5000,  // Data becomes stale after 5 seconds
+  staleTime: 5000, // Data becomes stale after 5 seconds
   cacheTime: 60000, // Data will be garbage collected if not accessed for 1 minute
 });
 
 // 1. Register a query with a unique string key and an async function to fetch the data.
-myCache.registerQuery('user/123', async () => {
-  console.log('--- Fetching user data from API... ---');
-  // Simulate network delay
-  await new Promise(resolve => setTimeout(resolve, 1000));
-  return { id: 123, name: 'Alice', email: 'alice@example.com' };
-}, { staleTime: 2000 }); // Override staleTime for this specific query to 2 seconds
+myCache.registerQuery(
+  "user/123",
+  async () => {
+    console.log("--- Fetching user data from API... ---");
+    // Simulate network delay
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    return { id: 123, name: "Alice", email: "alice@example.com" };
+  },
+  { staleTime: 2000 },
+); // Override staleTime for this specific query to 2 seconds
 
 // 2. Retrieve data from the cache using `get()`.
 
 async function getUserData(label: string) {
   console.log(`\n${label}: Requesting user/123`);
-  const userData = await myCache.get('user/123'); // Default: stale-while-revalidate
+  const userData = await myCache.get("user/123"); // Default: stale-while-revalidate
   console.log(`${label}: User data received:`, userData);
 }
 
 // First call: Data is not in cache (miss). Triggers fetch.
-getUserData('Initial Call');
+getUserData("Initial Call");
 
 // Subsequent calls (within staleTime): Data is returned instantly from cache. No fetch.
-setTimeout(() => getUserData('Cached Call'), 500);
+setTimeout(() => getUserData("Cached Call"), 500);
 
 // Call after query's staleTime: Data is returned instantly, but a background fetch is triggered.
-setTimeout(() => getUserData('Stale & Background Fetch'), 2500);
+setTimeout(() => getUserData("Stale & Background Fetch"), 2500);
 
 // Example of waiting for fresh data
 async function getFreshUserData() {
-  console.log('\n--- Requesting FRESH user data (waiting for fetch)... ---');
+  console.log("\n--- Requesting FRESH user data (waiting for fetch)... ---");
   try {
-    const freshUserData = await myCache.get('user/123', { waitForFresh: true });
-    console.log('Fresh user data received:', freshUserData);
+    const freshUserData = await myCache.get("user/123", { waitForFresh: true });
+    console.log("Fresh user data received:", freshUserData);
   } catch (error) {
-    console.error('Failed to get fresh user data:', error);
+    console.error("Failed to get fresh user data:", error);
   }
 }
 
@@ -220,7 +229,7 @@ setTimeout(() => getFreshUserData(), 3000);
 Creates a new `Cache` instance with global default options.
 
 ```typescript
-import { Cache } from '@asaidimu/utils-cache';
+import { Cache } from "@asaidimu/utils-cache";
 
 const cache = new Cache({
   staleTime: 5 * 60 * 1000, // 5 minutes
@@ -233,41 +242,48 @@ const cache = new Cache({
 
 Registers a data fetching function associated with a unique `key`. This `fetchFunction` will be called when data for the `key` is not in cache, is stale, or explicitly invalidated/refreshed.
 
--   `key`: A unique string identifier for the data.
--   `fetchFunction`: An `async` function that returns a `Promise` resolving to the data of type `T`.
--   `options`: Optional `CacheOptions` to override the instance's default options for this specific query (e.g., a shorter `staleTime` for frequently changing data).
+- `key`: A unique string identifier for the data.
+- `fetchFunction`: An `async` function that returns a `Promise` resolving to the data of type `T`.
+- `options`: Optional `CacheOptions` to override the instance's default options for this specific query (e.g., a shorter `staleTime` for frequently changing data).
 
 ```typescript
-cache.registerQuery('products/featured', async () => {
-  const response = await fetch('https://api.example.com/products/featured');
-  if (!response.ok) throw new Error('Failed to fetch featured products');
-  return response.json();
-}, {
-  staleTime: 60 * 1000, // This query's data is stale after 1 minute
-  retryAttempts: 5,     // It will retry fetching up to 5 times
-});
+cache.registerQuery(
+  "products/featured",
+  async () => {
+    const response = await fetch("https://api.example.com/products/featured");
+    if (!response.ok) throw new Error("Failed to fetch featured products");
+    return response.json();
+  },
+  {
+    staleTime: 60 * 1000, // This query's data is stale after 1 minute
+    retryAttempts: 5, // It will retry fetching up to 5 times
+  },
+);
 ```
 
 #### `cache.get<T>(key: string, options?: { waitForFresh?: boolean; throwOnError?: boolean }): Promise<T | undefined>`
 
 Retrieves data for a given `key`.
 
--   If data is fresh, returns it immediately.
--   If data is stale (and `waitForFresh` is `false` or unset), returns it immediately and triggers a background refetch (stale-while-revalidate).
--   If data is not in cache (miss), it triggers a fetch.
--   `waitForFresh`: If `true`, the method will await the `fetchFunction` to complete and return fresh data. If `false` (default), it will return existing stale data immediately if available, otherwise `undefined` while a fetch is ongoing in the background.
--   `throwOnError`: If `true`, and the `fetchFunction` fails after all retries, the promise returned by `get` will reject with the error. If `false` (default), it will return `undefined` on fetch failure, or the last successfully fetched data if available.
+- If data is fresh, returns it immediately.
+- If data is stale (and `waitForFresh` is `false` or unset), returns it immediately and triggers a background refetch (stale-while-revalidate).
+- If data is not in cache (miss), it triggers a fetch.
+- `waitForFresh`: If `true`, the method will await the `fetchFunction` to complete and return fresh data. If `false` (default), it will return existing stale data immediately if available, otherwise `undefined` while a fetch is ongoing in the background.
+- `throwOnError`: If `true`, and the `fetchFunction` fails after all retries, the promise returned by `get` will reject with the error. If `false` (default), it will return `undefined` on fetch failure, or the last successfully fetched data if available.
 
 ```typescript
 // Basic usage (stale-while-revalidate)
-const post = await cache.get('posts/latest');
+const post = await cache.get("posts/latest");
 
 // Wait for fresh data, throw if fetch fails
 try {
-  const userProfile = await cache.get('user/profile', { waitForFresh: true, throwOnError: true });
-  console.log('Latest user profile:', userProfile);
+  const userProfile = await cache.get("user/profile", {
+    waitForFresh: true,
+    throwOnError: true,
+  });
+  console.log("Latest user profile:", userProfile);
 } catch (error) {
-  console.error('Could not get fresh user profile due to an error:', error);
+  console.error("Could not get fresh user profile due to an error:", error);
 }
 ```
 
@@ -276,11 +292,11 @@ try {
 Retrieves data from the cache without triggering any fetches, updating `lastAccessed` time, or `accessCount`. Useful for quick synchronous checks.
 
 ```typescript
-const cachedValue = cache.peek('some-config-key');
+const cachedValue = cache.peek("some-config-key");
 if (cachedValue) {
-  console.log('Value is in cache:', cachedValue);
+  console.log("Value is in cache:", cachedValue);
 } else {
-  console.log('Value not found in cache.');
+  console.log("Value not found in cache.");
 }
 ```
 
@@ -289,10 +305,10 @@ if (cachedValue) {
 Checks if a non-stale, non-loading entry exists in the cache for the given `key`.
 
 ```typescript
-if (cache.has('config/app')) {
-  console.log('App config is ready and fresh.');
+if (cache.has("config/app")) {
+  console.log("App config is ready and fresh.");
 } else {
-  console.log('App config is missing, stale, or currently loading.');
+  console.log("App config is missing, stale, or currently loading.");
 }
 ```
 
@@ -300,23 +316,23 @@ if (cache.has('config/app')) {
 
 Marks a specific cache entry as stale, forcing the next `get` call for that key to trigger a refetch. Optionally triggers an immediate background refetch.
 
--   `key`: The cache key to invalidate.
--   `refetch`: If `true` (default), triggers an immediate background fetch for the invalidated key using its registered `fetchFunction`.
+- `key`: The cache key to invalidate.
+- `refetch`: If `true` (default), triggers an immediate background fetch for the invalidated key using its registered `fetchFunction`.
 
 ```typescript
 // After updating a user, invalidate their profile data to ensure next fetch is fresh
-await cache.invalidate('user/123/profile');
+await cache.invalidate("user/123/profile");
 
 // Invalidate and don't refetch until `get` is explicitly called later
-await cache.invalidate('admin/dashboard/stats', false);
+await cache.invalidate("admin/dashboard/stats", false);
 ```
 
 #### `cache.invalidatePattern(pattern: RegExp, refetch = true): Promise<void>`
 
 Invalidates all cache entries whose keys match the given regular expression. Similar to `invalidate`, it optionally triggers immediate background refetches for all matched keys.
 
--   `pattern`: A `RegExp` object to match against cache keys.
--   `refetch`: If `true` (default), triggers immediate background fetches for all matched keys.
+- `pattern`: A `RegExp` object to match against cache keys.
+- `refetch`: If `true` (default), triggers immediate background fetches for all matched keys.
 
 ```typescript
 // Invalidate all product-related data (e.g., after a mass product update)
@@ -332,8 +348,8 @@ Triggers a background fetch for a `key` if it's not already in cache or is stale
 
 ```typescript
 // On application startup or route change, prefetch common data
-cache.prefetch('static-content/footer');
-cache.prefetch('user/notifications/unread');
+cache.prefetch("static-content/footer");
+cache.prefetch("user/notifications/unread");
 ```
 
 #### `cache.refresh<T>(key: string): Promise<T | undefined>`
@@ -342,8 +358,8 @@ Forces a re-fetch of data for a given `key`, bypassing staleness checks and any
 
 ```typescript
 // After an API call modifies a resource, force update its cached version
-const updatedUser = await cache.refresh('user/current');
-console.log('User data refreshed:', updatedUser);
+const updatedUser = await cache.refresh("user/current");
+console.log("User data refreshed:", updatedUser);
 ```
 
 #### `cache.setData<T>(key: string, data: T): void`
@@ -352,11 +368,11 @@ Manually sets or updates data in the cache for a given `key`. This immediately u
 
 ```typescript
 // Manually update a shopping cart item count after a local UI interaction
-cache.setData('cart/item-count', 5);
+cache.setData("cart/item-count", 5);
 
 // Directly inject data fetched from another source or computed locally
-const localConfig = { theme: 'dark', fontSize: 'medium' };
-cache.setData('app/settings', localConfig);
+const localConfig = { theme: "dark", fontSize: "medium" };
+cache.setData("app/settings", localConfig);
 ```
 
 #### `cache.remove(key: string): boolean`
@@ -365,51 +381,63 @@ Removes a specific entry from the cache. Returns `true` if an entry was found an
 
 ```typescript
 // When a user logs out, remove their specific session data
-cache.remove('user/session');
+cache.remove("user/session");
 ```
 
 #### `cache.on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, { type: EType }>) => void): () => void`
 
 Subscribes a listener function to specific cache events. Returns an `unsubscribe` function.
 
--   `event`: The type of event to listen for (e.g., `'cache:read:hit'`, `'cache:fetch:error'`). Wildcards like `'cache:read:*'` are supported. See `CacheEventType` in `types.ts` for all available types.
--   `listener`: A callback function that receives the specific event payload for the subscribed event type.
+- `event`: The type of event to listen for (e.g., `'cache:read:hit'`, `'cache:fetch:error'`). Wildcards like `'cache:read:*'` are supported. See `CacheEventType` in `types.ts` for all available types.
+- `listener`: A callback function that receives the specific event payload for the subscribed event type.
 
 ```typescript
-import { Cache, CacheEvent, CacheEventType } from '@asaidimu/utils-cache';
+import { Cache, CacheEvent, CacheEventType } from "@asaidimu/utils-cache";
 
 const myCache = new Cache();
 
-const unsubscribeHit = myCache.on('cache:read:hit', (e) => {
+const unsubscribeHit = myCache.on("cache:read:hit", (e) => {
   console.log(`[CacheEvent] HIT for ${e.key} (isStale: ${e.isStale})`);
 });
 
-myCache.on('cache:read:miss', (e) => {
+myCache.on("cache:read:miss", (e) => {
   console.log(`[CacheEvent] MISS for ${e.key}`);
 });
 
-myCache.on('cache:fetch:error', (e) => {
-  console.error(`[CacheEvent] ERROR for ${e.key} (attempt ${e.attempt}):`, e.error.message);
+myCache.on("cache:fetch:error", (e) => {
+  console.error(
+    `[CacheEvent] ERROR for ${e.key} (attempt ${e.attempt}):`,
+    e.error.message,
+  );
 });
 
-myCache.on('cache:persistence:save:success', (e) => {
-  console.log(`[CacheEvent] Persistence: Cache state saved successfully for ID: ${e.key}`);
+myCache.on("cache:persistence:save:success", (e) => {
+  console.log(
+    `[CacheEvent] Persistence: Cache state saved successfully for ID: ${e.key}`,
+  );
 });
 
-myCache.on('cache:persistence:load:error', (e) => {
-  console.error(`[CacheEvent] Persistence: Failed to load cache state for ID: ${e.key}`, e.error);
+myCache.on("cache:persistence:load:error", (e) => {
+  console.error(
+    `[CacheEvent] Persistence: Failed to load cache state for ID: ${e.key}`,
+    e.error,
+  );
 });
 
 // For demonstration, register a query and trigger events
-myCache.registerQuery('demo-item', async () => {
-    console.log('--- Fetching demo-item ---');
-    await new Promise(r => setTimeout(r, 200));
-    return 'demo-data';
-}, { staleTime: 100 });
+myCache.registerQuery(
+  "demo-item",
+  async () => {
+    console.log("--- Fetching demo-item ---");
+    await new Promise((r) => setTimeout(r, 200));
+    return "demo-data";
+  },
+  { staleTime: 100 },
+);
 
-myCache.get('demo-item'); // Triggers miss, fetch, set_data
-setTimeout(() => myCache.get('demo-item'), 50); // Triggers hit
-setTimeout(() => myCache.get('demo-item'), 150); // Triggers stale hit, background fetch
+myCache.get("demo-item"); // Triggers miss, fetch, set_data
+setTimeout(() => myCache.get("demo-item"), 50); // Triggers hit
+setTimeout(() => myCache.get("demo-item"), 150); // Triggers stale hit, background fetch
 
 // To unsubscribe from a specific event later:
 unsubscribeHit();
@@ -419,18 +447,18 @@ unsubscribeHit();
 
 Returns current cache statistics and detailed metrics.
 
--   `size`: Number of active entries in the cache.
--   `metrics`: An object containing raw counts (`hits`, `misses`, `fetches`, `errors`, `evictions`, `staleHits`).
--   `hitRate`: Ratio of hits to total requests (hits + misses).
--   `staleHitRate`: Ratio of stale hits to total hits.
--   `entries`: An array of objects providing details for each cached item (key, lastAccessed, lastUpdated, accessCount, isStale, isLoading, error status).
+- `size`: Number of active entries in the cache.
+- `metrics`: An object containing raw counts (`hits`, `misses`, `fetches`, `errors`, `evictions`, `staleHits`).
+- `hitRate`: Ratio of hits to total requests (hits + misses).
+- `staleHitRate`: Ratio of stale hits to total hits.
+- `entries`: An array of objects providing details for each cached item (key, lastAccessed, lastUpdated, accessCount, isStale, isLoading, error status).
 
 ```typescript
 const stats = myCache.getStats();
-console.log('Cache Size:', stats.size);
-console.log('Metrics:', stats.metrics);
-console.log('Overall Hit Rate:', (stats.hitRate * 100).toFixed(2) + '%');
-console.log('Entries details:', stats.entries);
+console.log("Cache Size:", stats.size);
+console.log("Metrics:", stats.metrics);
+console.log("Overall Hit Rate:", (stats.hitRate * 100).toFixed(2) + "%");
+console.log("Entries details:", stats.entries);
 ```
 
 #### `cache.clear(): Promise<void>`
@@ -438,9 +466,9 @@ console.log('Entries details:', stats.entries);
 Clears all data from the in-memory cache, resets metrics, and attempts to clear the associated persisted state via the `persistence` layer.
 
 ```typescript
-console.log('Clearing cache...');
+console.log("Clearing cache...");
 await myCache.clear();
-console.log('Cache cleared. Current size:', myCache.getStats().size);
+console.log("Cache cleared. Current size:", myCache.getStats().size);
 ```
 
 #### `cache.destroy(): void`
@@ -449,7 +477,7 @@ Shuts down the cache instance, clearing all data, stopping the automatic garbage
 
 ```typescript
 myCache.destroy();
-console.log('Cache instance destroyed. All timers stopped and data cleared.');
+console.log("Cache instance destroyed. All timers stopped and data cleared.");
 ```
 
 ### Configuration Examples
@@ -457,79 +485,94 @@ console.log('Cache instance destroyed. All timers stopped and data cleared.');
 The `CacheOptions` interface provides extensive control over the cache's behavior:
 
 ```typescript
-import { CacheOptions, SimplePersistence, SerializableCacheState } from '@asaidimu/utils-cache';
+import {
+  CacheOptions,
+  SimplePersistence,
+  SerializableCacheState,
+} from "@asaidimu/utils-cache";
 
 // A mock persistence layer for demonstration purposes.
 // In a real application, you'd use an actual implementation like IndexedDBPersistence.
 class MockPersistence implements SimplePersistence<SerializableCacheState> {
-    private store = new Map<string, SerializableCacheState>();
-    private subscribers = new Map<string, Array<(data: SerializableCacheState) => void>>();
-
-    async get(id: string): Promise<SerializableCacheState | undefined> {
-        console.log(`[MockPersistence] Getting state for ID: ${id}`);
-        return this.store.get(id);
-    }
-    async set(id: string, data: SerializableCacheState): Promise<void> {
-        console.log(`[MockPersistence] Setting state for ID: ${id}`);
-        this.store.set(id, data);
-        // Simulate remote update notification to all subscribed instances
-        this.subscribers.get(id)?.forEach(cb => cb(data));
-    }
-    async clear(id?: string): Promise<void> {
-        console.log(`[MockPersistence] Clearing state ${id ? 'for ID: ' + id : '(all)'}`);
-        if (id) {
-            this.store.delete(id);
-        } else {
-            this.store.clear();
-        }
+  private store = new Map<string, SerializableCacheState>();
+  private subscribers = new Map<
+    string,
+    Array<(data: SerializableCacheState) => void>
+  >();
+
+  async get(id: string): Promise<SerializableCacheState | undefined> {
+    console.log(`[MockPersistence] Getting state for ID: ${id}`);
+    return this.store.get(id);
+  }
+  async set(id: string, data: SerializableCacheState): Promise<void> {
+    console.log(`[MockPersistence] Setting state for ID: ${id}`);
+    this.store.set(id, data);
+    // Simulate remote update notification to all subscribed instances
+    this.subscribers.get(id)?.forEach((cb) => cb(data));
+  }
+  async clear(id?: string): Promise<void> {
+    console.log(
+      `[MockPersistence] Clearing state ${id ? "for ID: " + id : "(all)"}`,
+    );
+    if (id) {
+      this.store.delete(id);
+    } else {
+      this.store.clear();
     }
-    subscribe(id: string, callback: (data: SerializableCacheState) => void): () => void {
-        console.log(`[MockPersistence] Subscribing to ID: ${id}`);
-        if (!this.subscribers.has(id)) {
-            this.subscribers.set(id, []);
-        }
-        this.subscribers.get(id)?.push(callback);
-        // Return unsubscribe function
-        return () => {
-            const callbacks = this.subscribers.get(id);
-            if (callbacks) {
-                this.subscribers.set(id, callbacks.filter(cb => cb !== callback));
-            }
-            console.log(`[MockPersistence] Unsubscribed from ID: ${id}`);
-        };
+  }
+  subscribe(
+    id: string,
+    callback: (data: SerializableCacheState) => void,
+  ): () => void {
+    console.log(`[MockPersistence] Subscribing to ID: ${id}`);
+    if (!this.subscribers.has(id)) {
+      this.subscribers.set(id, []);
     }
+    this.subscribers.get(id)?.push(callback);
+    // Return unsubscribe function
+    return () => {
+      const callbacks = this.subscribers.get(id);
+      if (callbacks) {
+        this.subscribers.set(
+          id,
+          callbacks.filter((cb) => cb !== callback),
+        );
+      }
+      console.log(`[MockPersistence] Unsubscribed from ID: ${id}`);
+    };
+  }
 }
 
 const fullOptions: CacheOptions = {
-  staleTime: 1000 * 60 * 5,    // 5 minutes: After this time, data is stale; a background fetch is considered.
-  cacheTime: 1000 * 60 * 60,   // 1 hour: Items idle (not accessed) for this long are eligible for garbage collection.
-  retryAttempts: 3,            // Max 3 fetch attempts (initial + 2 retries) on network/fetch failures.
-  retryDelay: 1000,            // 1 second initial delay for retries (doubles each subsequent attempt).
-  maxSize: 2000,               // Keep up to 2000 entries; LRU eviction kicks in beyond this limit.
-  enableMetrics: true,         // Enable performance tracking (hits, misses, fetches, etc.).
+  staleTime: 1000 * 60 * 5, // 5 minutes: After this time, data is stale; a background fetch is considered.
+  cacheTime: 1000 * 60 * 60, // 1 hour: Items idle (not accessed) for this long are eligible for garbage collection.
+  retryAttempts: 3, // Max 3 fetch attempts (initial + 2 retries) on network/fetch failures.
+  retryDelay: 1000, // 1 second initial delay for retries (doubles each subsequent attempt).
+  maxSize: 2000, // Keep up to 2000 entries; LRU eviction kicks in beyond this limit.
+  enableMetrics: true, // Enable performance tracking (hits, misses, fetches, etc.).
   persistence: new MockPersistence(), // Provide an instance of your persistence layer implementation.
-  persistenceId: 'my-unique-cache-instance', // A unique identifier for this cache instance within the persistence store.
+  persistenceId: "my-unique-cache-instance", // A unique identifier for this cache instance within the persistence store.
   persistenceDebounceTime: 750, // Wait 750ms after a cache change before writing to persistence to batch writes.
-  
+
   // Custom serializers/deserializers for data that isn't natively JSON serializable (e.g., Maps, Dates, custom classes).
   serializeValue: (value: any) => {
     // Example: Convert Date objects to ISO strings for JSON serialization
     if (value instanceof Date) {
-      return { _type: 'Date', data: value.toISOString() };
+      return { _type: "Date", data: value.toISOString() };
     }
     // Example: Convert Map objects to an array for JSON serialization
     if (value instanceof Map) {
-      return { _type: 'Map', data: Array.from(value.entries()) };
+      return { _type: "Map", data: Array.from(value.entries()) };
     }
     return value; // Return as is for other types
   },
   deserializeValue: (value: any) => {
     // Example: Convert ISO strings back to Date objects
-    if (typeof value === 'object' && value !== null && value._type === 'Date') {
+    if (typeof value === "object" && value !== null && value._type === "Date") {
       return new Date(value.data);
     }
     // Example: Convert array back to Map objects
-    if (typeof value === 'object' && value !== null && value._type === 'Map') {
+    if (typeof value === "object" && value !== null && value._type === "Map") {
       return new Map(value.data);
     }
     return value; // Return as is for other types
@@ -546,36 +589,42 @@ const configuredCache = new Cache(fullOptions);
 This is the default and most common pattern, where you prioritize immediate responsiveness while ensuring data freshness in the background.
 
 ```typescript
-import { Cache } from '@asaidimu/utils-cache';
+import { Cache } from "@asaidimu/utils-cache";
 
 const apiCache = new Cache({
-  staleTime: 5 * 60 * 1000,  // Data considered stale after 5 minutes
+  staleTime: 5 * 60 * 1000, // Data considered stale after 5 minutes
   cacheTime: 30 * 60 * 1000, // Idle data garbage collected after 30 minutes
-  retryAttempts: 3,          // Retry fetching on network failures
+  retryAttempts: 3, // Retry fetching on network failures
 });
 
 // Register a query for a list of blog posts
-apiCache.registerQuery('blog/posts', async () => {
-  console.log('--- Fetching ALL blog posts from API... ---');
-  const response = await fetch('https://api.example.com/blog/posts');
-  if (!response.ok) throw new Error('Failed to fetch blog posts');
+apiCache.registerQuery("blog/posts", async () => {
+  console.log("--- Fetching ALL blog posts from API... ---");
+  const response = await fetch("https://api.example.com/blog/posts");
+  if (!response.ok) throw new Error("Failed to fetch blog posts");
   return response.json();
 });
 
 // Function to display blog posts
 async function displayBlogPosts(source: string) {
   console.log(`\nDisplaying blog posts from: ${source}`);
-  const posts = await apiCache.get('blog/posts'); // Uses SWR by default
+  const posts = await apiCache.get("blog/posts"); // Uses SWR by default
   if (posts) {
-    console.log(`Received ${posts.length} posts (first 2):`, posts.slice(0, 2).map((p: any) => p.title));
+    console.log(
+      `Received ${posts.length} posts (first 2):`,
+      posts.slice(0, 2).map((p: any) => p.title),
+    );
   } else {
-    console.log('No posts yet, waiting for initial fetch...');
+    console.log("No posts yet, waiting for initial fetch...");
   }
 }
 
-displayBlogPosts('Initial Load'); // First `get`: cache miss, triggers fetch.
-setTimeout(() => displayBlogPosts('After 1 sec (cached)'), 1000); // Second `get`: cache hit, returns instantly.
-setTimeout(() => displayBlogPosts('After 6 mins (stale & background fetch)'), 6 * 60 * 1000); // After `staleTime`: returns cached, triggers background fetch.
+displayBlogPosts("Initial Load"); // First `get`: cache miss, triggers fetch.
+setTimeout(() => displayBlogPosts("After 1 sec (cached)"), 1000); // Second `get`: cache hit, returns instantly.
+setTimeout(
+  () => displayBlogPosts("After 6 mins (stale & background fetch)"),
+  6 * 60 * 1000,
+); // After `staleTime`: returns cached, triggers background fetch.
 ```
 
 #### Using `waitForFresh` for Critical Data
@@ -583,29 +632,32 @@ setTimeout(() => displayBlogPosts('After 6 mins (stale & background fetch)'), 6
 For scenarios where serving outdated data is unacceptable (e.g., user permissions, critical configuration).
 
 ```typescript
-import { Cache } from '@asaidimu/utils-cache';
+import { Cache } from "@asaidimu/utils-cache";
 
 const criticalCache = new Cache({ retryAttempts: 5, retryDelay: 1000 });
 
-criticalCache.registerQuery('user/permissions', async () => {
-  console.log('--- Fetching user permissions from API... ---');
+criticalCache.registerQuery("user/permissions", async () => {
+  console.log("--- Fetching user permissions from API... ---");
   // Simulate potential network flakiness
   if (Math.random() > 0.7) {
-    throw new Error('Network error during permission fetch!');
+    throw new Error("Network error during permission fetch!");
   }
-  await new Promise(resolve => setTimeout(resolve, 500));
-  return { canEdit: true, canDelete: false, roles: ['user', 'editor'] };
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  return { canEdit: true, canDelete: false, roles: ["user", "editor"] };
 });
 
 async function checkPermissionsBeforeAction() {
-  console.log('\nAttempting to get FRESH user permissions...');
+  console.log("\nAttempting to get FRESH user permissions...");
   try {
     // We MUST have the latest permissions before proceeding with a sensitive action
-    const permissions = await criticalCache.get('user/permissions', { waitForFresh: true, throwOnError: true });
-    console.log('User permissions received:', permissions);
+    const permissions = await criticalCache.get("user/permissions", {
+      waitForFresh: true,
+      throwOnError: true,
+    });
+    console.log("User permissions received:", permissions);
     // Proceed with action based on permissions
   } catch (error) {
-    console.error('CRITICAL: Failed to load user permissions:', error);
+    console.error("CRITICAL: Failed to load user permissions:", error);
     // Redirect to error page, show critical alert, or disable functionality
   }
 }
@@ -620,54 +672,73 @@ setInterval(() => checkPermissionsBeforeAction(), 3000);
 Utilize the comprehensive event system to log, monitor, or react to cache lifecycle events.
 
 ```typescript
-import { Cache } from '@asaidimu/utils-cache';
+import { Cache } from "@asaidimu/utils-cache";
 
 const monitorCache = new Cache({ enableMetrics: true });
 
-monitorCache.registerQuery('stock/AAPL', async () => {
-  const price = Math.random() * 100 + 150;
-  console.log(`--- Fetching AAPL price: ${price.toFixed(2)} ---`);
-  return { symbol: 'AAPL', price: parseFloat(price.toFixed(2)), timestamp: Date.now() };
-}, { staleTime: 1000 }); // Very short staleTime for frequent fetches
+monitorCache.registerQuery(
+  "stock/AAPL",
+  async () => {
+    const price = Math.random() * 100 + 150;
+    console.log(`--- Fetching AAPL price: ${price.toFixed(2)} ---`);
+    return {
+      symbol: "AAPL",
+      price: parseFloat(price.toFixed(2)),
+      timestamp: Date.now(),
+    };
+  },
+  { staleTime: 1000 },
+); // Very short staleTime for frequent fetches
 
 // Subscribe to various cache events
-monitorCache.on('cache:fetch:start', (e) => {
+monitorCache.on("cache:fetch:start", (e) => {
   console.log(`[EVENT] Fetching ${e.key} (attempt ${e.attempt})`);
 });
-monitorCache.on('cache:read:hit', (e) => {
+monitorCache.on("cache:read:hit", (e) => {
   console.log(`[EVENT] Cache hit for ${e.key}. Stale: ${e.isStale}`);
 });
-monitorCache.on('cache:read:miss', (e) => {
+monitorCache.on("cache:read:miss", (e) => {
   console.log(`[EVENT] Cache miss for ${e.key}`);
 });
-monitorCache.on('cache:data:evict', (e) => {
+monitorCache.on("cache:data:evict", (e) => {
   console.log(`[EVENT] Evicted ${e.key} due to ${e.reason}`);
 });
-monitorCache.on('cache:data:set', (e) => {
-    console.log(`[EVENT] Data for ${e.key} manually set. Old price: ${e.oldData?.price}, New price: ${e.newData.price}`);
+monitorCache.on("cache:data:set", (e) => {
+  console.log(
+    `[EVENT] Data for ${e.key} manually set. Old price: ${e.oldData?.price}, New price: ${e.newData.price}`,
+  );
 });
-monitorCache.on('cache:persistence:save:success', (e) => {
-  console.log(`[EVENT] Persistence: ${e.message || 'Save successful'}`);
+monitorCache.on("cache:persistence:save:success", (e) => {
+  console.log(`[EVENT] Persistence: ${e.message || "Save successful"}`);
 });
 
-
 // Continuously try to get data (will trigger fetches due to short staleTime)
 setInterval(() => {
-  monitorCache.get('stock/AAPL');
+  monitorCache.get("stock/AAPL");
 }, 500);
 
 // Manually set data to trigger 'set_data' and 'persistence' events
 setTimeout(() => {
-    monitorCache.setData('stock/AAPL', { symbol: 'AAPL', price: 160.00, timestamp: Date.now() });
+  monitorCache.setData("stock/AAPL", {
+    symbol: "AAPL",
+    price: 160.0,
+    timestamp: Date.now(),
+  });
 }, 3000);
 
 // Log cache statistics periodically
 setInterval(() => {
   const stats = monitorCache.getStats();
   console.log(`\n--- CACHE STATS ---`);
-  console.log(`Size: ${stats.size}, Hits: ${stats.metrics.hits}, Misses: ${stats.metrics.misses}, Fetches: ${stats.metrics.fetches}`);
-  console.log(`Hit Rate: ${(stats.hitRate * 100).toFixed(2)}%, Stale Hit Rate: ${(stats.staleHitRate * 100).toFixed(2)}%`);
-  console.log(`Active entries: ${stats.entries.map(e => `${e.key} (stale:${e.isStale})`).join(', ')}`);
+  console.log(
+    `Size: ${stats.size}, Hits: ${stats.metrics.hits}, Misses: ${stats.metrics.misses}, Fetches: ${stats.metrics.fetches}`,
+  );
+  console.log(
+    `Hit Rate: ${(stats.hitRate * 100).toFixed(2)}%, Stale Hit Rate: ${(stats.staleHitRate * 100).toFixed(2)}%`,
+  );
+  console.log(
+    `Active entries: ${stats.entries.map((e) => `${e.key} (stale:${e.isStale})`).join(", ")}`,
+  );
   console.log(`-------------------\n`);
 }, 5000); // Log stats every 5 seconds
 ```
@@ -691,72 +762,72 @@ package.json            # Package metadata and dependencies for this specific mo
 
 ### Core Components
 
-*   **`Cache` Class (`cache.ts`)**: The central component of the library. It orchestrates all caching logic, including:
-    *   Managing the in-memory `Map` (`this.cache`) that stores `CacheEntry` objects.
-    *   Handling data fetching, retries, and staleness checks.
-    *   Implementing time-based (TTL) and size-based (LRU) garbage collection.
-    *   Integrating with the pluggable persistence layer.
-    *   Emitting detailed cache events.
-    *   Tracking performance metrics.
-*   **`CacheOptions` (`types.ts`)**: An interface defining the configurable parameters for a `Cache` instance or individual queries. This includes `staleTime`, `cacheTime`, `retryAttempts`, `maxSize`, persistence settings, and custom serialization/deserialization functions.
-*   **`CacheEntry` (`types.ts`)**: Represents a single item stored within the cache. It encapsulates the actual `data`, `lastUpdated` and `lastAccessed` timestamps, `accessCount`, and flags like `isLoading` or `error` status.
-*   **`QueryConfig` (`types.ts`)**: Stores the `fetchFunction` and the resolved `CacheOptions` (merged with instance defaults) for each registered query, enabling tailored behavior per data key.
-*   **`CacheMetrics` (`types.ts`)**: Defines the structure for tracking cache performance statistics, including hits, misses, fetches, errors, and evictions.
-*   **`SimplePersistence<SerializableCacheState>` (from `@asaidimu/utils-persistence`)**: An external interface that `Cache` relies on for persistent storage. It requires implementations of `get()`, `set()`, `clear()`, and optionally `subscribe()` methods to handle data serialization and deserialization for the specific storage medium (e.g., IndexedDB, LocalStorage, or a remote backend).
-*   **`CacheEvent` / `CacheEventType` (`types.ts`)**: A union type defining all possible events emitted by the cache (e.g., `'cache:read:hit'`, `'cache:fetch:start'`, `'cache:data:evict'`). This enables a fine-grained, scoped observability model for the cache's lifecycle.
+- **`Cache` Class (`cache.ts`)**: The central component of the library. It orchestrates all caching logic, including:
+  - Managing the in-memory `Map` (`this.cache`) that stores `CacheEntry` objects.
+  - Handling data fetching, retries, and staleness checks.
+  - Implementing time-based (TTL) and size-based (LRU) garbage collection.
+  - Integrating with the pluggable persistence layer.
+  - Emitting detailed cache events.
+  - Tracking performance metrics.
+- **`CacheOptions` (`types.ts`)**: An interface defining the configurable parameters for a `Cache` instance or individual queries. This includes `staleTime`, `cacheTime`, `retryAttempts`, `maxSize`, persistence settings, and custom serialization/deserialization functions.
+- **`CacheEntry` (`types.ts`)**: Represents a single item stored within the cache. It encapsulates the actual `data`, `lastUpdated` and `lastAccessed` timestamps, `accessCount`, and flags like `isLoading` or `error` status.
+- **`QueryConfig` (`types.ts`)**: Stores the `fetchFunction` and the resolved `CacheOptions` (merged with instance defaults) for each registered query, enabling tailored behavior per data key.
+- **`CacheMetrics` (`types.ts`)**: Defines the structure for tracking cache performance statistics, including hits, misses, fetches, errors, and evictions.
+- **`SimplePersistence<SerializableCacheState>` (from `@asaidimu/utils-persistence`)**: An external interface that `Cache` relies on for persistent storage. It requires implementations of `get()`, `set()`, `clear()`, and optionally `subscribe()` methods to handle data serialization and deserialization for the specific storage medium (e.g., IndexedDB, LocalStorage, or a remote backend).
+- **`CacheEvent` / `CacheEventType` (`types.ts`)**: A union type defining all possible events emitted by the cache (e.g., `'cache:read:hit'`, `'cache:fetch:start'`, `'cache:data:evict'`). This enables a fine-grained, scoped observability model for the cache's lifecycle.
 
 ### Data Flow
 
 1.  **Initialization**:
-    *   The `Cache` constructor sets up global default options, initializes performance metrics, and starts the automatic garbage collection timer.
-    *   If a `persistence` layer is configured, it attempts to load a previously saved state using `persistence.get()`, emitting `'cache:persistence:load:success'` or `'cache:persistence:load:error'`.
-    *   It then subscribes to `persistence.subscribe()` (if available) to listen for remote state changes from the underlying storage, ensuring cache consistency across multiple instances or processes.
+    - The `Cache` constructor sets up global default options, initializes performance metrics, and starts the automatic garbage collection timer.
+    - If a `persistence` layer is configured, it attempts to load a previously saved state using `persistence.get()`, emitting `'cache:persistence:load:success'` or `'cache:persistence:load:error'`.
+    - It then subscribes to `persistence.subscribe()` (if available) to listen for remote state changes from the underlying storage, ensuring cache consistency across multiple instances or processes.
 
 2.  **`registerQuery`**:
-    *   When `registerQuery(key, fetchFunction, options)` is called, the `fetchFunction` and its specific `options` (merged with the global `defaultOptions`) are stored internally in the `this.queries` map. This prepares the cache to handle requests for that `key`.
+    - When `registerQuery(key, fetchFunction, options)` is called, the `fetchFunction` and its specific `options` (merged with the global `defaultOptions`) are stored internally in the `this.queries` map. This prepares the cache to handle requests for that `key`.
 
 3.  **`get` Request**:
-    *   When `get(key, options)` is invoked, `Cache` first checks `this.cache` for an existing `CacheEntry` for the `key`.
-    *   **Cache Hit**: If an entry exists, `lastAccessed` and `accessCount` are updated, a `'cache:read:hit'` event is emitted, and metrics are incremented. The entry's staleness is evaluated based on `staleTime`.
-        *   If `waitForFresh` is `true` OR if the entry is stale/loading, it proceeds to `fetchAndWait`.
-        *   If `waitForFresh` is `false` (default) and the entry is stale, the cached data is returned immediately, and a background `fetch` is triggered to update the data.
-        *   If `waitForFresh` is `false` and the entry is fresh, the cached data is returned immediately.
-    *   **Cache Miss**: If no entry exists, a `'cache:read:miss'` event is emitted. A placeholder `CacheEntry` (marked `isLoading`) is created, and a `fetch` is immediately triggered to retrieve the data.
+    - When `get(key, options)` is invoked, `Cache` first checks `this.cache` for an existing `CacheEntry` for the `key`.
+    - **Cache Hit**: If an entry exists, `lastAccessed` and `accessCount` are updated, a `'cache:read:hit'` event is emitted, and metrics are incremented. The entry's staleness is evaluated based on `staleTime`.
+      - If `waitForFresh` is `true` OR if the entry is stale/loading, it proceeds to `fetchAndWait`.
+      - If `waitForFresh` is `false` (default) and the entry is stale, the cached data is returned immediately, and a background `fetch` is triggered to update the data.
+      - If `waitForFresh` is `false` and the entry is fresh, the cached data is returned immediately.
+    - **Cache Miss**: If no entry exists, a `'cache:read:miss'` event is emitted. A placeholder `CacheEntry` (marked `isLoading`) is created, and a `fetch` is immediately triggered to retrieve the data.
 
 4.  **`fetch` / `fetchAndWait`**:
-    *   These methods ensure that only one `fetchFunction` runs concurrently for a given `key` by tracking ongoing fetches in `this.fetching`.
-    *   They delegate the actual data retrieval and retry logic to `performFetchWithRetry`.
+    - These methods ensure that only one `fetchFunction` runs concurrently for a given `key` by tracking ongoing fetches in `this.fetching`.
+    - They delegate the actual data retrieval and retry logic to `performFetchWithRetry`.
 
 5.  **`performFetchWithRetry`**:
-    *   This is where the registered `fetchFunction` is executed. It attempts to call the `fetchFunction` multiple times (up to `retryAttempts`) with exponential backoff (`retryDelay`).
-    *   Before each attempt, a `'cache:fetch:start'` event is emitted, and `fetches` metrics are updated.
-    *   **On Success**: The `CacheEntry` is updated with the new `data`, `lastUpdated` timestamp, and its `isLoading` status is set to `false`. The cache then calls `schedulePersistState()` to save the updated state and `enforceSizeLimit()` to maintain the `maxSize`.
-    *   **On Failure**: If the `fetchFunction` fails, a `'cache:fetch:error'` event is emitted, and `errors` metrics are updated. If `retryAttempts` are remaining, it waits (`delay`) and retries. After all attempts, the `CacheEntry` is updated with the last `error`, `isLoading` is set to `false`, and `schedulePersistState()` is called.
+    - This is where the registered `fetchFunction` is executed. It attempts to call the `fetchFunction` multiple times (up to `retryAttempts`) with exponential backoff (`retryDelay`).
+    - Before each attempt, a `'cache:fetch:start'` event is emitted, and `fetches` metrics are updated.
+    - **On Success**: The `CacheEntry` is updated with the new `data`, `lastUpdated` timestamp, and its `isLoading` status is set to `false`. The cache then calls `schedulePersistState()` to save the updated state and `enforceSizeLimit()` to maintain the `maxSize`.
+    - **On Failure**: If the `fetchFunction` fails, a `'cache:fetch:error'` event is emitted, and `errors` metrics are updated. If `retryAttempts` are remaining, it waits (`delay`) and retries. After all attempts, the `CacheEntry` is updated with the last `error`, `isLoading` is set to `false`, and `schedulePersistState()` is called.
 
 6.  **`schedulePersistState`**:
-    *   This method debounces write operations to the `persistence` layer. It prevents excessive writes by waiting for a configurable `persistenceDebounceTime` before serializing the current cache state (using `serializeCache` and `serializeValue`) and writing it via `persistence.set()`. Appropriate persistence events (`'cache:persistence:save:success'`/`'cache:persistence:save:error'`) are emitted.
+    - This method debounces write operations to the `persistence` layer. It prevents excessive writes by waiting for a configurable `persistenceDebounceTime` before serializing the current cache state (using `serializeCache` and `serializeValue`) and writing it via `persistence.set()`. Appropriate persistence events (`'cache:persistence:save:success'`/`'cache:persistence:save:error'`) are emitted.
 
 7.  **`handleRemoteStateChange`**:
-    *   This callback is invoked by the `persistence` layer's `subscribe` mechanism when an external change to the persisted state is detected. It deserializes the `remoteState` (using `deserializeValue`) and intelligently updates the local `this.cache` to reflect these external changes, emitting a `'cache:persistence:sync'` event.
+    - This callback is invoked by the `persistence` layer's `subscribe` mechanism when an external change to the persisted state is detected. It deserializes the `remoteState` (using `deserializeValue`) and intelligently updates the local `this.cache` to reflect these external changes, emitting a `'cache:persistence:sync'` event.
 
 8.  **`garbageCollect`**:
-    *   Running on a `setInterval` timer (`gcTimer`), this method periodically scans `this.cache`. It removes any `CacheEntry` that has not been `lastAccessed` for longer than its (or global) `cacheTime`, emitting `'cache:data:evict'` events.
+    - Running on a `setInterval` timer (`gcTimer`), this method periodically scans `this.cache`. It removes any `CacheEntry` that has not been `lastAccessed` for longer than its (or global) `cacheTime`, emitting `'cache:data:evict'` events.
 
 9.  **`enforceSizeLimit`**:
-    *   Triggered after successful data updates (`fetch` success or `setData`). If the `cache.size` exceeds `maxSize`, it evicts the Least Recently Used (LRU) entries until the `maxSize` is satisfied, emitting `'cache:data:evict'` events.
+    - Triggered after successful data updates (`fetch` success or `setData`). If the `cache.size` exceeds `maxSize`, it evicts the Least Recently Used (LRU) entries until the `maxSize` is satisfied, emitting `'cache:data:evict'` events.
 
 ### Extension Points
 
 The design of `@asaidimu/utils-cache` provides several powerful extension points for customization and integration:
 
-*   **`SimplePersistence` Interface**: This is the primary mechanism for integrating `Cache` with various storage backends. By implementing this interface, you can use `Cache` with `localStorage`, `IndexedDB` (e.g., via `@asaidimu/utils-persistence`), a custom database, a server-side cache, or any other persistent storage solution.
-*   **`serializeValue` / `deserializeValue` Options**: These functions within `CacheOptions` allow you to define custom logic for how your specific data types are converted to and from a serializable format (e.g., JSON-compatible strings or objects) before being passed to and received from the `persistence` layer. This is crucial for handling `Date` objects, `Map`s, `Set`s, or custom class instances.
-*   **Event Listeners (`on`)**: The comprehensive event system, powered by `@asaidimu/events`, allows you to subscribe to a wide range of cache lifecycle events. This enables powerful integrations for:
-    *   **Logging**: Detailed logging of cache activity (hits, misses, errors, evictions).
-    *   **Analytics**: Feeding cache performance metrics into an analytics platform.
-    *   **UI Reactivity**: Updating UI components in response to cache changes (e.g., showing a "stale data" indicator or a "refreshing" spinner).
-    *   **Debugging**: Gaining deep insights into cache behavior during development.
-    *   **External Synchronization**: Triggering side effects or synchronizing with other systems based on cache events.
+- **`SimplePersistence` Interface**: This is the primary mechanism for integrating `Cache` with various storage backends. By implementing this interface, you can use `Cache` with `localStorage`, `IndexedDB` (e.g., via `@asaidimu/utils-persistence`), a custom database, a server-side cache, or any other persistent storage solution.
+- **`serializeValue` / `deserializeValue` Options**: These functions within `CacheOptions` allow you to define custom logic for how your specific data types are converted to and from a serializable format (e.g., JSON-compatible strings or objects) before being passed to and received from the `persistence` layer. This is crucial for handling `Date` objects, `Map`s, `Set`s, or custom class instances.
+- **Event Listeners (`on`)**: The comprehensive event system, powered by `@asaidimu/events`, allows you to subscribe to a wide range of cache lifecycle events. This enables powerful integrations for:
+  - **Logging**: Detailed logging of cache activity (hits, misses, errors, evictions).
+  - **Analytics**: Feeding cache performance metrics into an analytics platform.
+  - **UI Reactivity**: Updating UI components in response to cache changes (e.g., showing a "stale data" indicator or a "refreshing" spinner).
+  - **Debugging**: Gaining deep insights into cache behavior during development.
+  - **External Synchronization**: Triggering side effects or synchronizing with other systems based on cache events.
 
 ---
 
@@ -798,11 +869,11 @@ To set up the development environment for `@asaidimu/utils-cache`:
 
 The following `npm` scripts are typically available in this project's setup:
 
-*   `npm run build`: Compiles TypeScript source files from `src/` to JavaScript output in `dist/`.
-*   `npm run test`: Runs the test suite using `Vitest`.
-*   `npm run test:watch`: Runs tests in watch mode for continuous feedback during development.
-*   `npm run lint`: Runs ESLint to check for code style and potential errors.
-*   `npm run format`: Formats code using Prettier according to the project's style guidelines.
+- `npm run build`: Compiles TypeScript source files from `src/` to JavaScript output in `dist/`.
+- `npm run test`: Runs the test suite using `Vitest`.
+- `npm run test:watch`: Runs tests in watch mode for continuous feedback during development.
+- `npm run lint`: Runs ESLint to check for code style and potential errors.
+- `npm run format`: Formats code using Prettier according to the project's style guidelines.
 
 ### Testing
 
@@ -838,11 +909,11 @@ Found a bug, have a feature request, or need clarification? Please open an issue
 
 When reporting a bug, please include:
 
-*   A clear and concise description of the issue.
-*   Detailed steps to reproduce the behavior.
-*   The expected behavior.
-*   Any relevant screenshots or code snippets.
-*   Your environment details (Node.js version, OS, browser, package version).
+- A clear and concise description of the issue.
+- Detailed steps to reproduce the behavior.
+- The expected behavior.
+- Any relevant screenshots or code snippets.
+- Your environment details (Node.js version, OS, browser, package version).
 
 ---
 
@@ -850,29 +921,29 @@ When reporting a bug, please include:
 
 ### Troubleshooting
 
-*   **"No query registered for key: [key]" Error**:
-    *   **Cause**: This error occurs if you try to `get()`, `prefetch()`, or `refresh()` a `key` that has not been previously associated with a `fetchFunction` using `cache.registerQuery()`.
-    *   **Solution**: Ensure you call `cache.registerQuery(key, fetchFunction)` for every `key` you intend to use with the cache before attempting to retrieve data.
-*   **Data not persisting**:
-    *   **Cause**: The cache state is not being correctly saved or loaded from the underlying storage.
-    *   **Solution**:
-        1.  **`persistence` instance**: Double-check that you are passing a valid `SimplePersistence` instance to the `Cache` constructor's `persistence` option.
-        2.  **`persistenceId`**: Ensure you've provided a unique `persistenceId` if multiple cache instances share the same persistence layer.
-        3.  **Serialization**: Verify that your data types are correctly handled by `serializeValue` and `deserializeValue` options, especially for non-JSON-serializable types like `Map`s, `Date` objects, or custom classes.
-        4.  **Persistence Layer**: Confirm your `SimplePersistence` implementation correctly handles `get()`, `set()`, `clear()`, and `subscribe()` operations for the specific storage medium (e.g., local storage quota, IndexedDB permissions).
-        5.  **Event Errors**: Check for persistence event errors in your browser's or Node.js console (e.g., `cache.on('cache:persistence:save:error', ...)`).
-*   **Cache not evicting data**:
-    *   **Cause**: Eviction policies might be disabled or configured with very long durations.
-    *   **Solution**:
-        1.  **`cacheTime`**: Ensure `cacheTime` in `CacheOptions` is set to a finite, non-zero positive number (in milliseconds). `Infinity` or `0` for `cacheTime` disables time-based garbage collection.
-        2.  **`maxSize`**: Ensure `maxSize` is set to a finite, non-zero positive number. `Infinity` disables size-based LRU eviction, and `0` means the cache will always be empty (evicting immediately).
-        3.  **Garbage Collection Interval**: The garbage collection runs periodically. While generally sufficient, verify that `cacheTime` isn't so large that you rarely hit the GC interval.
-*   **Event listeners not firing**:
-    *   **Cause**: The listener might be removed, or the expected event is not actually occurring.
-    *   **Solution**:
-        1.  **Correct Event Type**: Ensure you are subscribing to the exact `CacheEventType` you expect (e.g., `'cache:read:hit'`, `'cache:fetch:error'`).
-        2.  **`enableMetrics`**: If you expect metric-related events or updates, ensure `enableMetrics` is not set to `false` in your `CacheOptions`.
-        3.  **Unsubscribe Function**: Ensure you are not accidentally calling the `unsubscribe` function returned by `on()` prematurely.
+- **"No query registered for key: [key]" Error**:
+  - **Cause**: This error occurs if you try to `get()`, `prefetch()`, or `refresh()` a `key` that has not been previously associated with a `fetchFunction` using `cache.registerQuery()`.
+  - **Solution**: Ensure you call `cache.registerQuery(key, fetchFunction)` for every `key` you intend to use with the cache before attempting to retrieve data.
+- **Data not persisting**:
+  - **Cause**: The cache state is not being correctly saved or loaded from the underlying storage.
+  - **Solution**:
+    1.  **`persistence` instance**: Double-check that you are passing a valid `SimplePersistence` instance to the `Cache` constructor's `persistence` option.
+    2.  **`persistenceId`**: Ensure you've provided a unique `persistenceId` if multiple cache instances share the same persistence layer.
+    3.  **Serialization**: Verify that your data types are correctly handled by `serializeValue` and `deserializeValue` options, especially for non-JSON-serializable types like `Map`s, `Date` objects, or custom classes.
+    4.  **Persistence Layer**: Confirm your `SimplePersistence` implementation correctly handles `get()`, `set()`, `clear()`, and `subscribe()` operations for the specific storage medium (e.g., local storage quota, IndexedDB permissions).
+    5.  **Event Errors**: Check for persistence event errors in your browser's or Node.js console (e.g., `cache.on('cache:persistence:save:error', ...)`).
+- **Cache not evicting data**:
+  - **Cause**: Eviction policies might be disabled or configured with very long durations.
+  - **Solution**:
+    1.  **`cacheTime`**: Ensure `cacheTime` in `CacheOptions` is set to a finite, non-zero positive number (in milliseconds). `Infinity` or `0` for `cacheTime` disables time-based garbage collection.
+    2.  **`maxSize`**: Ensure `maxSize` is set to a finite, non-zero positive number. `Infinity` disables size-based LRU eviction, and `0` means the cache will always be empty (evicting immediately).
+    3.  **Garbage Collection Interval**: The garbage collection runs periodically. While generally sufficient, verify that `cacheTime` isn't so large that you rarely hit the GC interval.
+- **Event listeners not firing**:
+  - **Cause**: The listener might be removed, or the expected event is not actually occurring.
+  - **Solution**:
+    1.  **Correct Event Type**: Ensure you are subscribing to the exact `CacheEventType` you expect (e.g., `'cache:read:hit'`, `'cache:fetch:error'`).
+    2.  **`enableMetrics`**: If you expect metric-related events or updates, ensure `enableMetrics` is not set to `false` in your `CacheOptions`.
+    3.  **Unsubscribe Function**: Ensure you are not accidentally calling the `unsubscribe` function returned by `on()` prematurely.
 
 ### FAQ
 
@@ -886,7 +957,7 @@ A: Use `waitForFresh: true` when your application absolutely needs the most up-t
 A: Yes, `Cache` is designed to be environment-agnostic. Its persistence mechanism is pluggable, so you can implement a `SimplePersistence` that works within a web worker (e.g., using IndexedDB directly or communicating with the main thread via `postMessage`).
 
 **Q: Is `Cache` thread-safe (or safe with concurrent access)?**
-A: JavaScript is single-threaded. `Cache` manages its internal state with `Map`s and `Promise`s. For concurrent `get` requests to the *same key*, it ensures only one `fetchFunction` runs via the `this.fetching` map, preventing redundant fetches. Therefore, it is safe for concurrent access within a single JavaScript runtime context. For multiple JavaScript runtimes (e.g., different browser tabs or Node.js processes), the `persistence` layer's `subscribe` mechanism handles synchronization.
+A: JavaScript is single-threaded. `Cache` manages its internal state with `Map`s and `Promise`s. For concurrent `get` requests to the _same key_, it ensures only one `fetchFunction` runs via the `this.fetching` map, preventing redundant fetches. Therefore, it is safe for concurrent access within a single JavaScript runtime context. For multiple JavaScript runtimes (e.g., different browser tabs or Node.js processes), the `persistence` layer's `subscribe` mechanism handles synchronization.
 
 ### Changelog/Roadmap
 
@@ -898,6 +969,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ### Acknowledgments
 
-*   Inspired by modern data fetching and caching libraries like [React Query](https://react-query.tanstack.com/) and [SWR](https://swr.vercel.app/).
-*   Uses the `uuid` library for generating unique cache instance IDs.
-*   Event system powered by `@asaidimu/events`.
+- Inspired by modern data fetching and caching libraries like [React Query](https://react-query.tanstack.com/) and [SWR](https://swr.vercel.app/).
+- Uses the `uuid` library for generating unique cache instance IDs.
+- Event system powered by `@asaidimu/events`.

package/index.d.mts

@@ -97,51 +97,51 @@ type CacheEventBase<Type extends string, Payload = {}> = {
     key: string;
     timestamp: number;
 } & Payload;
-type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
+type CacheReadHitEvent<T = any> = CacheEventBase<"cache:read:hit", {
     data: T;
     isStale: boolean;
 }>;
-type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
-type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
+type CacheReadMissEvent = CacheEventBase<"cache:read:miss">;
+type CacheFetchStartEvent = CacheEventBase<"cache:fetch:start", {
     attempt: number;
 }>;
-type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<"cache:fetch:success", {
     data: T;
 }>;
-type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
+type CacheFetchErrorEvent = CacheEventBase<"cache:fetch:error", {
     error: Error;
     attempt: number;
 }>;
-type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
+type CacheDataEvictEvent = CacheEventBase<"cache:data:evict", {
     reason?: string;
 }>;
-type CacheDataInvalidateEvent = CacheEventBase<'cache:data:invalidate'>;
-type CacheDataSetEvent<T = any> = CacheEventBase<'cache:data:set', {
+type CacheDataInvalidateEvent = CacheEventBase<"cache:data:invalidate">;
+type CacheDataSetEvent<T = any> = CacheEventBase<"cache:data:set", {
     newData: T;
     oldData?: T;
 }>;
-type CachePersistenceLoadSuccessEvent = CacheEventBase<'cache:persistence:load:success', {
+type CachePersistenceLoadSuccessEvent = CacheEventBase<"cache:persistence:load:success", {
     message?: string;
 }>;
-type CachePersistenceLoadErrorEvent = CacheEventBase<'cache:persistence:load:error', {
+type CachePersistenceLoadErrorEvent = CacheEventBase<"cache:persistence:load:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSaveSuccessEvent = CacheEventBase<'cache:persistence:save:success'>;
-type CachePersistenceSaveErrorEvent = CacheEventBase<'cache:persistence:save:error', {
+type CachePersistenceSaveSuccessEvent = CacheEventBase<"cache:persistence:save:success">;
+type CachePersistenceSaveErrorEvent = CacheEventBase<"cache:persistence:save:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceClearSuccessEvent = CacheEventBase<'cache:persistence:clear:success'>;
-type CachePersistenceClearErrorEvent = CacheEventBase<'cache:persistence:clear:error', {
+type CachePersistenceClearSuccessEvent = CacheEventBase<"cache:persistence:clear:success">;
+type CachePersistenceClearErrorEvent = CacheEventBase<"cache:persistence:clear:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSyncEvent = CacheEventBase<'cache:persistence:sync', {
+type CachePersistenceSyncEvent = CacheEventBase<"cache:persistence:sync", {
     message?: string;
 }>;
 type CacheEvent = CacheReadHitEvent | CacheReadMissEvent | CacheFetchStartEvent | CacheFetchSuccessEvent | CacheFetchErrorEvent | CacheDataEvictEvent | CacheDataInvalidateEvent | CacheDataSetEvent | CachePersistenceLoadSuccessEvent | CachePersistenceLoadErrorEvent | CachePersistenceSaveSuccessEvent | CachePersistenceSaveErrorEvent | CachePersistenceClearSuccessEvent | CachePersistenceClearErrorEvent | CachePersistenceSyncEvent;
-type CacheEventType = CacheEvent['type'];
+type CacheEventType = CacheEvent["type"];
 
 declare class QueryCache {
     private cache;

package/index.d.ts

@@ -97,51 +97,51 @@ type CacheEventBase<Type extends string, Payload = {}> = {
     key: string;
     timestamp: number;
 } & Payload;
-type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
+type CacheReadHitEvent<T = any> = CacheEventBase<"cache:read:hit", {
     data: T;
     isStale: boolean;
 }>;
-type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
-type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
+type CacheReadMissEvent = CacheEventBase<"cache:read:miss">;
+type CacheFetchStartEvent = CacheEventBase<"cache:fetch:start", {
     attempt: number;
 }>;
-type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<"cache:fetch:success", {
     data: T;
 }>;
-type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
+type CacheFetchErrorEvent = CacheEventBase<"cache:fetch:error", {
     error: Error;
     attempt: number;
 }>;
-type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
+type CacheDataEvictEvent = CacheEventBase<"cache:data:evict", {
     reason?: string;
 }>;
-type CacheDataInvalidateEvent = CacheEventBase<'cache:data:invalidate'>;
-type CacheDataSetEvent<T = any> = CacheEventBase<'cache:data:set', {
+type CacheDataInvalidateEvent = CacheEventBase<"cache:data:invalidate">;
+type CacheDataSetEvent<T = any> = CacheEventBase<"cache:data:set", {
     newData: T;
     oldData?: T;
 }>;
-type CachePersistenceLoadSuccessEvent = CacheEventBase<'cache:persistence:load:success', {
+type CachePersistenceLoadSuccessEvent = CacheEventBase<"cache:persistence:load:success", {
     message?: string;
 }>;
-type CachePersistenceLoadErrorEvent = CacheEventBase<'cache:persistence:load:error', {
+type CachePersistenceLoadErrorEvent = CacheEventBase<"cache:persistence:load:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSaveSuccessEvent = CacheEventBase<'cache:persistence:save:success'>;
-type CachePersistenceSaveErrorEvent = CacheEventBase<'cache:persistence:save:error', {
+type CachePersistenceSaveSuccessEvent = CacheEventBase<"cache:persistence:save:success">;
+type CachePersistenceSaveErrorEvent = CacheEventBase<"cache:persistence:save:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceClearSuccessEvent = CacheEventBase<'cache:persistence:clear:success'>;
-type CachePersistenceClearErrorEvent = CacheEventBase<'cache:persistence:clear:error', {
+type CachePersistenceClearSuccessEvent = CacheEventBase<"cache:persistence:clear:success">;
+type CachePersistenceClearErrorEvent = CacheEventBase<"cache:persistence:clear:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSyncEvent = CacheEventBase<'cache:persistence:sync', {
+type CachePersistenceSyncEvent = CacheEventBase<"cache:persistence:sync", {
     message?: string;
 }>;
 type CacheEvent = CacheReadHitEvent | CacheReadMissEvent | CacheFetchStartEvent | CacheFetchSuccessEvent | CacheFetchErrorEvent | CacheDataEvictEvent | CacheDataInvalidateEvent | CacheDataSetEvent | CachePersistenceLoadSuccessEvent | CachePersistenceLoadErrorEvent | CachePersistenceSaveSuccessEvent | CachePersistenceSaveErrorEvent | CachePersistenceClearSuccessEvent | CachePersistenceClearErrorEvent | CachePersistenceSyncEvent;
-type CacheEventType = CacheEvent['type'];
+type CacheEventType = CacheEvent["type"];
 
 declare class QueryCache {
     private cache;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-cache",
-  "version": "3.0.6",
+  "version": "3.1.0",
   "description": "Resource and cache management utilities for @asaidimu applications.",
   "main": "index.js",
   "module": "index.mjs",
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@asaidimu/utils-persistence": "5.0.2",
+    "@asaidimu/utils-persistence": "6.0.0",
     "uuid": "^11.1.0",
     "@asaidimu/events": "^1.1.1"
   },