@asaidimu/utils-cache 2.0.4 → 2.1.0

package/README.md

@@ -64,7 +64,7 @@ Unlike simpler caches, `Cache` manages data freshness intelligently, allowing yo
 *   **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 cache events (e.g., `'hit'`, `'miss'`, `'fetch'`, `'error'`, `'eviction'`, `'invalidation'`, `'set_data'`, `'persistence'`) for real-time logging, debugging, analytics, and advanced reactivity.
+*   **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.
@@ -81,14 +81,14 @@ Unlike simpler caches, `Cache` manages data freshness intelligently, allowing yo
 
 ### Installation Steps
 
-Install `@asaidimu/utils-cache` using your preferred package manager:
+Install `@asaidimu/utils-cache` and its peer dependency `@asaidimu/events`:
 
 ```bash
-bun add @asaidimu/utils-cache
+bun add @asaidimu/utils-cache @asaidimu/events
 # or
-npm install @asaidimu/utils-cache
+npm install @asaidimu/utils-cache @asaidimu/events
 # or
-yarn add @asaidimu/utils-cache
+yarn add @asaidimu/utils-cache @asaidimu/events
 ```
 
 ### Configuration
@@ -368,11 +368,11 @@ Removes a specific entry from the cache. Returns `true` if an entry was found an
 cache.remove('user/session');
 ```
 
-#### `cache.on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, { type: EType }>) => void): void`
+#### `cache.on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, { type: EType }>) => void): () => void`
 
-Subscribes a listener function to specific cache events.
+Subscribes a listener function to specific cache events. Returns an `unsubscribe` function.
 
--   `event`: The type of event to listen for (e.g., `'hit'`, `'miss'`, `'error'`, `'persistence'`). See `CacheEventType` in `types.ts` for all available types.
+-   `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
@@ -380,26 +380,24 @@ import { Cache, CacheEvent, CacheEventType } from '@asaidimu/utils-cache';
 
 const myCache = new Cache();
 
-myCache.on('hit', (e) => {
+const unsubscribeHit = myCache.on('cache:read:hit', (e) => {
   console.log(`[CacheEvent] HIT for ${e.key} (isStale: ${e.isStale})`);
 });
 
-myCache.on('miss', (e) => {
+myCache.on('cache:read:miss', (e) => {
   console.log(`[CacheEvent] MISS for ${e.key}`);
 });
 
-myCache.on('error', (e) => {
+myCache.on('cache:fetch:error', (e) => {
   console.error(`[CacheEvent] ERROR for ${e.key} (attempt ${e.attempt}):`, e.error.message);
 });
 
-myCache.on('persistence', (e) => {
-  if (e.event === 'save_success') {
-    console.log(`[CacheEvent] Persistence: Cache state saved successfully for ID: ${e.key}`);
-  } else if (e.event === 'load_fail') {
-    console.error(`[CacheEvent] Persistence: Failed to load cache state for ID: ${e.key}`, e.error);
-  } else if (e.event === 'remote_update') {
-    console.log(`[CacheEvent] Persistence: Cache state updated from remote source 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);
 });
 
 // For demonstration, register a query and trigger events
@@ -412,18 +410,9 @@ myCache.registerQuery('demo-item', async () => {
 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
-```
-
-#### `cache.off<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, { type: EType }>) => void): void`
-
-Unsubscribes a previously registered listener from a cache event. The `listener` reference must be the exact same function that was passed to `on()`.
-
-```typescript
-const myHitLogger = (e: any) => console.log(`[Log] Cache Hit: ${e.key}`);
-myCache.on('hit', myHitLogger);
 
-// Later, when you no longer need the listener:
-myCache.off('hit', myHitLogger);
+// To unsubscribe from a specific event later:
+unsubscribeHit();
 ```
 
 #### `cache.getStats(): { size: number; metrics: CacheMetrics; hitRate: number; staleHitRate: number; entries: Array<{ key: string; lastAccessed: number; lastUpdated: number; accessCount: number; isStale: boolean; isLoading?: boolean; error?: boolean }> }`
@@ -637,28 +626,28 @@ 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)} ---`);
+  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('fetch', (e) => {
+monitorCache.on('cache:fetch:start', (e) => {
   console.log(`[EVENT] Fetching ${e.key} (attempt ${e.attempt})`);
 });
-monitorCache.on('hit', (e) => {
+monitorCache.on('cache:read:hit', (e) => {
   console.log(`[EVENT] Cache hit for ${e.key}. Stale: ${e.isStale}`);
 });
-monitorCache.on('miss', (e) => {
+monitorCache.on('cache:read:miss', (e) => {
   console.log(`[EVENT] Cache miss for ${e.key}`);
 });
-monitorCache.on('eviction', (e) => {
+monitorCache.on('cache:data:evict', (e) => {
   console.log(`[EVENT] Evicted ${e.key} due to ${e.reason}`);
 });
-monitorCache.on('set_data', (e) => {
+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('persistence', (e) => {
-  if (e.event === 'save_success') console.log(`[EVENT] Persistence: ${e.message || 'Save successful'}`);
+monitorCache.on('cache:persistence:save:success', (e) => {
+  console.log(`[EVENT] Persistence: ${e.message || 'Save successful'}`);
 });
 
 
@@ -714,13 +703,13 @@ package.json            # Package metadata and dependencies for this specific mo
 *   **`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., `'hit'`, `'miss'`, `'fetch'`, `'error'`, `'eviction'`, `'invalidation'`, `'set_data'`, `'persistence'`). This enables a fine-grained observability model for the cache's lifecycle.
+*   **`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()`.
+    *   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`**:
@@ -728,11 +717,11 @@ package.json            # Package metadata and dependencies for this specific mo
 
 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 `'hit'` event is emitted, and metrics are incremented. The entry's staleness is evaluated based on `staleTime`.
+    *   **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 `'miss'` event is emitted. A placeholder `CacheEntry` (marked `isLoading`) is created, and a `fetch` is immediately triggered to retrieve the data.
+    *   **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`.
@@ -740,21 +729,21 @@ package.json            # Package metadata and dependencies for this specific mo
 
 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 `'fetch'` event is emitted, and `fetches` metrics are updated.
+    *   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, an `'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.
+    *   **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 (`save_success`/`save_fail`) 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 `'persistence'` event (`remote_update`).
+    *   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 `'eviction'` 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 `'eviction'` 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
 
@@ -762,7 +751,7 @@ The design of `@asaidimu/utils-cache` provides several powerful extension points
 
 *   **`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`/`off`)**: The comprehensive event system allows you to subscribe to a wide range of cache lifecycle events. This enables powerful integrations for:
+*   **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).
@@ -779,16 +768,16 @@ We welcome contributions to `@asaidimu/utils-cache`! Whether it's a bug fix, a n
 
 To set up the development environment for `@asaidimu/utils-cache`:
 
-1.  **Clone the monorepo:**
+1.  **Clone the monorepo**:
     ```bash
     git clone https://github.com/asaidimu/erp-utils.git
     cd erp-utils
     ```
-2.  **Navigate to the cache package:**
+2.  **Navigate to the cache package**:
     ```bash
     cd src/cache
     ```
-3.  **Install dependencies:**
+3.  **Install dependencies**:
     ```bash
     npm install
     # or
@@ -796,7 +785,7 @@ To set up the development environment for `@asaidimu/utils-cache`:
     # or
     bun install
     ```
-4.  **Build the project:**
+4.  **Build the project**:
     ```bash
     npm run build
     # or
@@ -871,7 +860,7 @@ When reporting a bug, please include:
         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 (`cache.on('persistence', ...)`).
+        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**:
@@ -881,9 +870,9 @@ When reporting a bug, please include:
 *   **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., `'hit'`, `'error'`).
+        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.  **Listener Reference**: When using `off()`, ensure the listener function is the exact same reference passed to `on()`.
+        3.  **Unsubscribe Function**: Ensure you are not accidentally calling the `unsubscribe` function returned by `on()` prematurely.
 
 ### FAQ
 
@@ -911,3 +900,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 *   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

@@ -1,4 +1,4 @@
-import { S as SimplePersistence } from '../types-dsQOAvmQ.js';
+import { S as SimplePersistence } from '../types-DUZGkNEB.js';
 
 interface CacheOptions {
     staleTime?: number;
@@ -13,6 +13,18 @@ interface CacheOptions {
     deserializeValue?: (value: any) => any;
     persistenceDebounceTime?: number;
 }
+interface CacheEntry<T = any> {
+    data: T;
+    lastUpdated: number;
+    lastAccessed: number;
+    accessCount: number;
+    error?: Error;
+    isLoading?: boolean;
+}
+interface QueryConfig {
+    fetchFunction: () => Promise<any>;
+    options: Required<CacheOptions>;
+}
 interface CacheMetrics {
     hits: number;
     misses: number;
@@ -38,47 +50,59 @@ type CacheEventBase<Type extends string, Payload = {}> = {
     key: string;
     timestamp: number;
 } & Payload;
-type CacheHitEvent<T = any> = CacheEventBase<'hit', {
+type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
     data: T;
     isStale: boolean;
 }>;
-type CacheMissEvent = CacheEventBase<'miss'>;
-type CacheFetchEvent = CacheEventBase<'fetch', {
+type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
+type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
     attempt: number;
 }>;
-type CacheErrorEvent = CacheEventBase<'error', {
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+    data: T;
+}>;
+type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
     error: Error;
     attempt: number;
 }>;
-type CacheEvictionEvent = CacheEventBase<'eviction', {
+type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
     reason?: string;
 }>;
-type CacheInvalidationEvent = CacheEventBase<'invalidation'>;
-type CacheSetDataEvent<T = any> = CacheEventBase<'set_data', {
+type CacheDataInvalidateEvent = CacheEventBase<'cache:data:invalidate'>;
+type CacheDataSetEvent<T = any> = CacheEventBase<'cache:data:set', {
     newData: T;
     oldData?: T;
 }>;
-type CachePersistenceEventPayload = {
-    event: 'load_success' | 'remote_update';
+type CachePersistenceLoadSuccessEvent = CacheEventBase<'cache:persistence:load:success', {
     message?: string;
-} | {
-    event: 'load_fail' | 'save_fail' | 'clear_fail';
+}>;
+type CachePersistenceLoadErrorEvent = CacheEventBase<'cache:persistence:load:error', {
     message?: string;
     error?: any;
-} | {
-    event: 'save_success' | 'clear_success';
-};
-type CachePersistenceEvent = CacheEventBase<'persistence', CachePersistenceEventPayload>;
-type CacheEvent = CacheHitEvent | CacheMissEvent | CacheFetchEvent | CacheErrorEvent | CacheEvictionEvent | CacheInvalidationEvent | CacheSetDataEvent | CachePersistenceEvent;
+}>;
+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', {
+    message?: string;
+    error?: any;
+}>;
+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'];
 
-declare class Cache {
+declare class QueryCache {
     private cache;
     private queries;
     private fetching;
     private readonly defaultOptions;
     private metrics;
-    private eventListeners;
+    private eventBus;
     private gcTimer?;
     private readonly persistenceId;
     private persistenceUnsubscribe?;
@@ -127,10 +151,7 @@ declare class Cache {
     };
     on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, {
         type: EType;
-    }>) => void): void;
-    off<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, {
-        type: EType;
-    }>) => void): void;
+    }>) => void): () => void;
     private emitEvent;
     private updateMetrics;
     private delay;
@@ -138,4 +159,4 @@ declare class Cache {
     destroy(): void;
 }
 
-export { Cache };
+export { type CacheDataEvictEvent, type CacheDataInvalidateEvent, type CacheDataSetEvent, type CacheEntry, type CacheEvent, type CacheEventBase, type CacheEventType, type CacheFetchErrorEvent, type CacheFetchStartEvent, type CacheFetchSuccessEvent, type CacheMetrics, type CacheOptions, type CachePersistenceClearErrorEvent, type CachePersistenceClearSuccessEvent, type CachePersistenceLoadErrorEvent, type CachePersistenceLoadSuccessEvent, type CachePersistenceSaveErrorEvent, type CachePersistenceSaveSuccessEvent, type CachePersistenceSyncEvent, type CacheReadHitEvent, type CacheReadMissEvent, QueryCache, type QueryConfig, type SerializableCacheEntry, type SerializableCacheState };

package/index.d.ts

@@ -1,4 +1,4 @@
-import { S as SimplePersistence } from '../types-dsQOAvmQ.js';
+import { S as SimplePersistence } from '../types-DUZGkNEB.js';
 
 interface CacheOptions {
     staleTime?: number;
@@ -13,6 +13,18 @@ interface CacheOptions {
     deserializeValue?: (value: any) => any;
     persistenceDebounceTime?: number;
 }
+interface CacheEntry<T = any> {
+    data: T;
+    lastUpdated: number;
+    lastAccessed: number;
+    accessCount: number;
+    error?: Error;
+    isLoading?: boolean;
+}
+interface QueryConfig {
+    fetchFunction: () => Promise<any>;
+    options: Required<CacheOptions>;
+}
 interface CacheMetrics {
     hits: number;
     misses: number;
@@ -38,47 +50,59 @@ type CacheEventBase<Type extends string, Payload = {}> = {
     key: string;
     timestamp: number;
 } & Payload;
-type CacheHitEvent<T = any> = CacheEventBase<'hit', {
+type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
     data: T;
     isStale: boolean;
 }>;
-type CacheMissEvent = CacheEventBase<'miss'>;
-type CacheFetchEvent = CacheEventBase<'fetch', {
+type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
+type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
     attempt: number;
 }>;
-type CacheErrorEvent = CacheEventBase<'error', {
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+    data: T;
+}>;
+type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
     error: Error;
     attempt: number;
 }>;
-type CacheEvictionEvent = CacheEventBase<'eviction', {
+type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
     reason?: string;
 }>;
-type CacheInvalidationEvent = CacheEventBase<'invalidation'>;
-type CacheSetDataEvent<T = any> = CacheEventBase<'set_data', {
+type CacheDataInvalidateEvent = CacheEventBase<'cache:data:invalidate'>;
+type CacheDataSetEvent<T = any> = CacheEventBase<'cache:data:set', {
     newData: T;
     oldData?: T;
 }>;
-type CachePersistenceEventPayload = {
-    event: 'load_success' | 'remote_update';
+type CachePersistenceLoadSuccessEvent = CacheEventBase<'cache:persistence:load:success', {
     message?: string;
-} | {
-    event: 'load_fail' | 'save_fail' | 'clear_fail';
+}>;
+type CachePersistenceLoadErrorEvent = CacheEventBase<'cache:persistence:load:error', {
     message?: string;
     error?: any;
-} | {
-    event: 'save_success' | 'clear_success';
-};
-type CachePersistenceEvent = CacheEventBase<'persistence', CachePersistenceEventPayload>;
-type CacheEvent = CacheHitEvent | CacheMissEvent | CacheFetchEvent | CacheErrorEvent | CacheEvictionEvent | CacheInvalidationEvent | CacheSetDataEvent | CachePersistenceEvent;
+}>;
+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', {
+    message?: string;
+    error?: any;
+}>;
+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'];
 
-declare class Cache {
+declare class QueryCache {
     private cache;
     private queries;
     private fetching;
     private readonly defaultOptions;
     private metrics;
-    private eventListeners;
+    private eventBus;
     private gcTimer?;
     private readonly persistenceId;
     private persistenceUnsubscribe?;
@@ -127,10 +151,7 @@ declare class Cache {
     };
     on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, {
         type: EType;
-    }>) => void): void;
-    off<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, {
-        type: EType;
-    }>) => void): void;
+    }>) => void): () => void;
     private emitEvent;
     private updateMetrics;
     private delay;
@@ -138,4 +159,4 @@ declare class Cache {
     destroy(): void;
 }
 
-export { Cache };
+export { type CacheDataEvictEvent, type CacheDataInvalidateEvent, type CacheDataSetEvent, type CacheEntry, type CacheEvent, type CacheEventBase, type CacheEventType, type CacheFetchErrorEvent, type CacheFetchStartEvent, type CacheFetchSuccessEvent, type CacheMetrics, type CacheOptions, type CachePersistenceClearErrorEvent, type CachePersistenceClearSuccessEvent, type CachePersistenceLoadErrorEvent, type CachePersistenceLoadSuccessEvent, type CachePersistenceSaveErrorEvent, type CachePersistenceSaveSuccessEvent, type CachePersistenceSyncEvent, type CacheReadHitEvent, type CacheReadMissEvent, QueryCache, type QueryConfig, type SerializableCacheEntry, type SerializableCacheState };

package/index.js

@@ -1 +1 @@
-"use strict";var e=require("uuid");exports.Cache=class{cache=new Map;queries=new Map;fetching=new Map;defaultOptions;metrics;eventListeners=new Map;gcTimer;persistenceId;persistenceUnsubscribe;persistenceDebounceTimer;isHandlingRemoteUpdate=!1;constructor(t={}){void 0!==t.staleTime&&t.staleTime<0&&(console.warn("CacheOptions: staleTime should be non-negative. Using 0."),t.staleTime=0),void 0!==t.cacheTime&&t.cacheTime<0&&(console.warn("CacheOptions: cacheTime should be non-negative. Using 0."),t.cacheTime=0),void 0!==t.retryAttempts&&t.retryAttempts<0&&(console.warn("CacheOptions: retryAttempts should be non-negative. Using 0."),t.retryAttempts=0),void 0!==t.retryDelay&&t.retryDelay<0&&(console.warn("CacheOptions: retryDelay should be non-negative. Using 0."),t.retryDelay=0),void 0!==t.maxSize&&t.maxSize<0&&(console.warn("CacheOptions: maxSize should be non-negative. Using 0."),t.maxSize=0),this.defaultOptions={staleTime:3e5,cacheTime:18e5,retryAttempts:3,retryDelay:1e3,maxSize:1e3,enableMetrics:!0,persistence:void 0,persistenceId:void 0,serializeValue:e=>e,deserializeValue:e=>e,persistenceDebounceTime:500,...t},this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0},this.persistenceId=this.defaultOptions.persistenceId||e.v4(),this.startGarbageCollection(),this.initializePersistence()}async initializePersistence(){const{persistence:e}=this.defaultOptions;if(e){try{const t=await e.get();t&&(this.deserializeAndLoadCache(t),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"load_success",message:`Cache loaded for ID: ${this.persistenceId}`}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to load state from persistence:`,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"load_fail",error:e,message:`Failed to load cache for ID: ${this.persistenceId}`})}if("function"==typeof e.subscribe)try{this.persistenceUnsubscribe=e.subscribe(this.persistenceId,(e=>{this.handleRemoteStateChange(e)}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to subscribe to persistence:`,e)}}}serializeCache(){const e=[],{serializeValue:t}=this.defaultOptions;for(const[s,i]of this.cache)i.isLoading&&void 0===i.data&&0===i.lastUpdated||e.push([s,{data:t(i.data),lastUpdated:i.lastUpdated,lastAccessed:i.lastAccessed,accessCount:i.accessCount,error:i.error?{name:i.error.name,message:i.error.message,stack:i.error.stack}:void 0}]);return e}deserializeAndLoadCache(e){this.isHandlingRemoteUpdate=!0;const t=new Map,{deserializeValue:s}=this.defaultOptions;for(const[i,a]of e){let e;a.error&&(e=new Error(a.error.message),e.name=a.error.name,e.stack=a.error.stack),t.set(i,{data:s(a.data),lastUpdated:a.lastUpdated,lastAccessed:a.lastAccessed,accessCount:a.accessCount,error:e,isLoading:!1})}this.cache=t,this.enforceSizeLimit(!1),this.isHandlingRemoteUpdate=!1}schedulePersistState(){this.defaultOptions.persistence&&!this.isHandlingRemoteUpdate&&(this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceDebounceTimer=setTimeout((async()=>{try{const e=this.serializeCache();await this.defaultOptions.persistence.set(this.persistenceId,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"save_success"})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to persist state:`,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"save_fail",error:e})}}),this.defaultOptions.persistenceDebounceTime))}handleRemoteStateChange(e){if(this.isHandlingRemoteUpdate||!e)return;this.isHandlingRemoteUpdate=!0;const{deserializeValue:t}=this.defaultOptions,s=new Map;let i=!1;for(const[a,r]of e){let e;r.error&&(e=new Error(r.error.message),e.name=r.error.name,e.stack=r.error.stack);const c={data:t(r.data),lastUpdated:r.lastUpdated,lastAccessed:r.lastAccessed,accessCount:r.accessCount,error:e,isLoading:!1};s.set(a,c);const n=this.cache.get(a);(!n||n.lastUpdated<c.lastUpdated||JSON.stringify(n.data)!==JSON.stringify(c.data))&&(i=!0)}this.cache.size!==s.size&&(i=!0),i&&(this.cache=s,this.enforceSizeLimit(!1),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"remote_update",message:"Cache updated from remote state."})),this.isHandlingRemoteUpdate=!1}registerQuery(e,t,s={}){void 0!==s.staleTime&&s.staleTime<0&&(s.staleTime=0),void 0!==s.cacheTime&&s.cacheTime<0&&(s.cacheTime=0),this.queries.set(e,{fetchFunction:t,options:{...this.defaultOptions,...s}})}async get(e,t){const s=this.queries.get(e);if(!s)throw new Error(`No query registered for key: ${e}`);let i=this.cache.get(e);const a=this.isStale(i,s.options);let r=!1;if(i)i.lastAccessed=Date.now(),i.accessCount++,this.updateMetrics("hits"),a&&this.updateMetrics("staleHits"),this.emitEvent({type:"hit",key:e,timestamp:Date.now(),data:i.data,isStale:a});else if(this.updateMetrics("misses"),this.emitEvent({type:"miss",key:e,timestamp:Date.now()}),!t?.waitForFresh||a){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:1,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}if(t?.waitForFresh&&(!i||a||i.isLoading))try{const t=await this.fetchAndWait(e,s);return r&&this.cache.get(e)===i&&this.schedulePersistState(),t}catch(s){if(t.throwOnError)throw s;return this.cache.get(e)?.data}if(!i||a||i&&!i.isLoading&&0===i.lastUpdated&&!i.error){if(i&&!i.isLoading)i.isLoading=!0;else if(!i){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}this.fetch(e,s).catch((()=>{}))}if(r&&this.schedulePersistState(),i?.error&&t?.throwOnError)throw i.error;return i?.data}peek(e){const t=this.cache.get(e);return t&&(t.lastAccessed=Date.now(),t.accessCount++),t?.data}has(e){const t=this.cache.get(e),s=this.queries.get(e);return!(!t||!s)&&(!this.isStale(t,s.options)&&!t.isLoading)}async fetch(e,t){if(this.fetching.has(e))return this.fetching.get(e);let s=this.cache.get(e);s?s.isLoading||(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}async fetchAndWait(e,t){const s=this.fetching.get(e);if(s)return s;const i=await this.fetch(e,t);if(void 0===i){const t=this.cache.get(e);if(t?.error)throw t.error;throw new Error(`Failed to fetch data for key: ${e} after retries.`)}return i}async performFetchWithRetry(e,t,s){const{retryAttempts:i,retryDelay:a}=t.options;let r;s.isLoading=!0;for(let c=0;c<=i;c++)try{this.emitEvent({type:"fetch",key:e,timestamp:Date.now(),attempt:c}),this.updateMetrics("fetches");const i=await t.fetchFunction();return s.data=i,s.lastUpdated=Date.now(),s.isLoading=!1,s.error=void 0,this.cache.set(e,s),this.schedulePersistState(),this.enforceSizeLimit(),i}catch(t){r=t,this.emitEvent({type:"error",key:e,timestamp:Date.now(),error:r,attempt:c}),c<i&&await this.delay(a*Math.pow(2,c))}this.updateMetrics("errors"),s.error=r,s.isLoading=!1,this.cache.set(e,s),this.schedulePersistState()}isStale(e,t){if(!e||e.error)return!0;if(e.isLoading&&!e.data)return!0;const{staleTime:s}=t;return 0!==s&&s!==1/0&&Date.now()-e.lastUpdated>s}async invalidate(e,t=!0){const s=this.cache.get(e),i=this.queries.get(e);let a=!1;s&&(a=0!==s.lastUpdated||void 0!==s.error,s.lastUpdated=0,s.error=void 0,this.emitEvent({type:"invalidation",key:e,timestamp:Date.now()}),a&&this.schedulePersistState(),t&&i&&this.fetch(e,i).catch((()=>{})))}async invalidatePattern(e,t=!0){const s=[];let i=!1;for(const t of this.cache.keys())e.test(t)&&s.push(t);s.forEach((e=>{const t=this.cache.get(e);t&&(0===t.lastUpdated&&void 0===t.error||(i=!0),t.lastUpdated=0,t.error=void 0,this.emitEvent({type:"invalidation",key:e,timestamp:Date.now()}))})),i&&this.schedulePersistState(),t&&s.length>0&&await Promise.all(s.map((e=>{const t=this.queries.get(e);return t?this.fetch(e,t).catch((()=>{})):Promise.resolve()})))}async prefetch(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot prefetch: No query registered for key: ${e}`);const s=this.cache.get(e);s&&!this.isStale(s,t.options)||this.fetch(e,t).catch((()=>{}))}async refresh(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot refresh: No query registered for key: ${e}`);this.fetching.delete(e);let s=this.cache.get(e);s?(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}setData(e,t){const s=this.cache.get(e),i=s?.data,a={data:t,lastUpdated:Date.now(),lastAccessed:Date.now(),accessCount:(s?.accessCount||0)+1,isLoading:!1,error:void 0};this.cache.set(e,a),this.schedulePersistState(),this.enforceSizeLimit(),this.emitEvent({type:"set_data",key:e,timestamp:Date.now(),newData:t,oldData:i})}remove(e){this.fetching.delete(e);const t=this.cache.has(e),s=this.cache.delete(e);return s&&t&&this.schedulePersistState(),s}enforceSizeLimit(e=!0){const{maxSize:t}=this.defaultOptions;if(t===1/0||this.cache.size<=t)return;let s=0;if(0===t){s=this.cache.size;for(const e of this.cache.keys())this.cache.delete(e),this.emitEvent({type:"eviction",key:e,timestamp:Date.now(),reason:"size_limit_zero"}),this.updateMetrics("evictions")}else{const e=Array.from(this.cache.entries()).sort((([,e],[,t])=>e.lastAccessed-t.lastAccessed)),i=this.cache.size-t;if(i>0){e.slice(0,i).forEach((([e])=>{this.cache.delete(e)&&(s++,this.emitEvent({type:"eviction",key:e,timestamp:Date.now(),reason:"size_limit_lru"}),this.updateMetrics("evictions"))}))}}s>0&&e&&this.schedulePersistState()}startGarbageCollection(){const{cacheTime:e}=this.defaultOptions;if(e===1/0||e<=0)return;const t=Math.max(1e3,Math.min(e/4,3e5));this.gcTimer=setInterval((()=>this.garbageCollect()),t)}garbageCollect(){const e=Date.now();let t=0;const s=[];for(const[t,i]of this.cache){if(i.isLoading)continue;const a=this.queries.get(t),r=a?.options.cacheTime??this.defaultOptions.cacheTime;r===1/0||r<=0||e-i.lastAccessed>r&&s.push(t)}return s.length>0&&(s.forEach((e=>{this.cache.delete(e)&&(this.fetching.delete(e),this.emitEvent({type:"eviction",key:e,timestamp:Date.now(),reason:"garbage_collected_idle"}),this.updateMetrics("evictions"),t++)})),this.schedulePersistState()),t}getStats(){const e=this.metrics.hits+this.metrics.misses,t=e>0?this.metrics.hits/e:0,s=this.metrics.hits>0?this.metrics.staleHits/this.metrics.hits:0,i=Array.from(this.cache.entries()).map((([e,t])=>{const s=this.queries.get(e),i=!s||this.isStale(t,s.options);return{key:e,lastAccessed:t.lastAccessed,lastUpdated:t.lastUpdated,accessCount:t.accessCount,isStale:i,isLoading:t.isLoading,error:!!t.error}}));return{size:this.cache.size,metrics:{...this.metrics},hitRate:t,staleHitRate:s,entries:i}}on(e,t){this.eventListeners.has(e)||this.eventListeners.set(e,new Set),this.eventListeners.get(e).add(t)}off(e,t){this.eventListeners.get(e)?.delete(t)}emitEvent(e){const t=this.eventListeners.get(e.type);t&&t.forEach((t=>{try{t(e)}catch(t){const s="persistence"===e.type?`for ID ${e.key}`:`for key ${e.key}`;console.error(`Cache event listener error during ${e.type} ${s}:`,t)}}))}updateMetrics(e,t=1){this.defaultOptions.enableMetrics&&(this.metrics[e]=(this.metrics[e]||0)+t)}delay(e){return new Promise((t=>setTimeout(t,e)))}async clear(){const e=this.cache.size>0;if(this.cache.clear(),this.fetching.clear(),this.defaultOptions.enableMetrics&&(this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}),this.defaultOptions.persistence)try{await this.defaultOptions.persistence.clear(),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"clear_success"})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to clear persisted state:`,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"clear_fail",error:e})}else e&&this.schedulePersistState()}destroy(){if(this.gcTimer&&(clearInterval(this.gcTimer),this.gcTimer=void 0),this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceUnsubscribe)try{this.persistenceUnsubscribe()}catch(e){console.error(`Cache (${this.persistenceId}): Error unsubscribing persistence:`,e)}this.cache.clear(),this.fetching.clear(),this.queries.clear(),this.eventListeners.clear(),this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}}};
+"use strict";var e,t,s=require("uuid"),i=Object.create,a=Object.defineProperty,r=Object.getOwnPropertyDescriptor,c=Object.getOwnPropertyNames,n=Object.getPrototypeOf,o=Object.prototype.hasOwnProperty,h=(e={"node_modules/@asaidimu/events/index.js"(e,t){var s,i=Object.defineProperty,a=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,c=Object.prototype.hasOwnProperty,n={};((e,t)=>{for(var s in t)i(e,s,{get:t[s],enumerable:!0})})(n,{createEventBus:()=>o}),t.exports=(s=n,((e,t,s,n)=>{if(t&&"object"==typeof t||"function"==typeof t)for(let o of r(t))c.call(e,o)||o===s||i(e,o,{get:()=>t[o],enumerable:!(n=a(t,o))||n.enumerable});return e})(i({},"__esModule",{value:!0}),s));var o=(e={async:!1,batchSize:1e3,batchDelay:16,errorHandler:e=>console.error("EventBus Error:",e),crossTab:!1,channelName:"event-bus-channel"})=>{const t=new Map;let s=[],i=0,a=0;const r=new Map,c=new Map;let n=null;e.crossTab&&"undefined"!=typeof BroadcastChannel?n=new BroadcastChannel(e.channelName):e.crossTab&&console.warn("BroadcastChannel is not supported in this browser. Cross-tab notifications are disabled.");const o=(e,t)=>{i++,a+=t,r.set(e,(r.get(e)||0)+1)},h=()=>{const t=s;s=[],t.forEach((({name:t,payload:s})=>{const i=performance.now();try{(c.get(t)||[]).forEach((e=>e(s)))}catch(i){e.errorHandler({...i,eventName:t,payload:s})}o(t,performance.now()-i)}))},d=(()=>{let t;return()=>{clearTimeout(t),t=setTimeout(h,e.batchDelay)}})(),l=e=>{const s=t.get(e);s?c.set(e,Array.from(s)):c.delete(e)};return n&&(n.onmessage=e=>{const{name:t,payload:s}=e.data;(c.get(t)||[]).forEach((e=>e(s)))}),{subscribe:(e,s)=>{t.has(e)||t.set(e,new Set);const i=t.get(e);return i.add(s),l(e),()=>{i.delete(s),0===i.size?(t.delete(e),c.delete(e)):l(e)}},emit:({name:t,payload:i})=>{if(e.async)return s.push({name:t,payload:i}),s.length>=e.batchSize?h():d(),void(n&&n.postMessage({name:t,payload:i}));const a=performance.now();try{(c.get(t)||[]).forEach((e=>e(i))),n&&n.postMessage({name:t,payload:i})}catch(s){e.errorHandler({...s,eventName:t,payload:i})}o(t,performance.now()-a)},getMetrics:()=>({totalEvents:i,activeSubscriptions:Array.from(t.values()).reduce(((e,t)=>e+t.size),0),eventCounts:r,averageEmitDuration:i>0?a/i:0}),clear:()=>{t.clear(),c.clear(),s=[],i=0,a=0,r.clear(),n&&(n.close(),n=null)}}}}},function(){return t||(0,e[c(e)[0]])((t={exports:{}}).exports,t),t.exports}),d=((e,t,s)=>(s=null!=e?i(n(e)):{},((e,t,s,i)=>{if(t&&"object"==typeof t||"function"==typeof t)for(let n of c(t))o.call(e,n)||n===s||a(e,n,{get:()=>t[n],enumerable:!(i=r(t,n))||i.enumerable});return e})(e&&e.__esModule?s:a(s,"default",{value:e,enumerable:!0}),e)))(h());exports.QueryCache=class{cache=new Map;queries=new Map;fetching=new Map;defaultOptions;metrics;eventBus;gcTimer;persistenceId;persistenceUnsubscribe;persistenceDebounceTimer;isHandlingRemoteUpdate=!1;constructor(e={}){void 0!==e.staleTime&&e.staleTime<0&&(console.warn("CacheOptions: staleTime should be non-negative. Using 0."),e.staleTime=0),void 0!==e.cacheTime&&e.cacheTime<0&&(console.warn("CacheOptions: cacheTime should be non-negative. Using 0."),e.cacheTime=0),void 0!==e.retryAttempts&&e.retryAttempts<0&&(console.warn("CacheOptions: retryAttempts should be non-negative. Using 0."),e.retryAttempts=0),void 0!==e.retryDelay&&e.retryDelay<0&&(console.warn("CacheOptions: retryDelay should be non-negative. Using 0."),e.retryDelay=0),void 0!==e.maxSize&&e.maxSize<0&&(console.warn("CacheOptions: maxSize should be non-negative. Using 0."),e.maxSize=0),this.defaultOptions={staleTime:0,cacheTime:18e5,retryAttempts:3,retryDelay:1e3,maxSize:1e3,enableMetrics:!0,persistence:void 0,persistenceId:void 0,serializeValue:e=>e,deserializeValue:e=>e,persistenceDebounceTime:500,...e},this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0},this.persistenceId=this.defaultOptions.persistenceId||s.v4(),this.eventBus=(0,d.createEventBus)(),this.startGarbageCollection(),this.initializePersistence()}async initializePersistence(){const{persistence:e}=this.defaultOptions;if(e){try{const t=await e.get();t&&(this.deserializeAndLoadCache(t),this.emitEvent({type:"cache:persistence:load:success",key:this.persistenceId,timestamp:Date.now(),message:`Cache loaded for ID: ${this.persistenceId}`}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to load state from persistence:`,e),this.emitEvent({type:"cache:persistence:load:error",key:this.persistenceId,timestamp:Date.now(),error:e,message:`Failed to load cache for ID: ${this.persistenceId}`})}if("function"==typeof e.subscribe)try{this.persistenceUnsubscribe=e.subscribe(this.persistenceId,(e=>{this.handleRemoteStateChange(e)}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to subscribe to persistence:`,e)}}}serializeCache(){const e=[],{serializeValue:t}=this.defaultOptions;for(const[s,i]of this.cache)i.isLoading&&void 0===i.data&&0===i.lastUpdated||e.push([s,{data:t(i.data),lastUpdated:i.lastUpdated,lastAccessed:i.lastAccessed,accessCount:i.accessCount,error:i.error?{name:i.error.name,message:i.error.message,stack:i.error.stack}:void 0}]);return e}deserializeAndLoadCache(e){this.isHandlingRemoteUpdate=!0;const t=new Map,{deserializeValue:s}=this.defaultOptions;for(const[i,a]of e){let e;a.error&&(e=new Error(a.error.message),e.name=a.error.name,e.stack=a.error.stack),t.set(i,{data:s(a.data),lastUpdated:a.lastUpdated,lastAccessed:a.lastAccessed,accessCount:a.accessCount,error:e,isLoading:!1})}this.cache=t,this.enforceSizeLimit(!1),this.isHandlingRemoteUpdate=!1}schedulePersistState(){this.defaultOptions.persistence&&!this.isHandlingRemoteUpdate&&(this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceDebounceTimer=setTimeout((async()=>{try{const e=this.serializeCache();await this.defaultOptions.persistence.set(this.persistenceId,e),this.emitEvent({type:"cache:persistence:save:success",key:this.persistenceId,timestamp:Date.now()})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to persist state:`,e),this.emitEvent({type:"cache:persistence:save:error",key:this.persistenceId,timestamp:Date.now(),error:e})}}),this.defaultOptions.persistenceDebounceTime))}handleRemoteStateChange(e){if(this.isHandlingRemoteUpdate||!e)return;this.isHandlingRemoteUpdate=!0;const{deserializeValue:t}=this.defaultOptions,s=new Map;let i=!1;for(const[a,r]of e){let e;r.error&&(e=new Error(r.error.message),e.name=r.error.name,e.stack=r.error.stack);const c={data:t(r.data),lastUpdated:r.lastUpdated,lastAccessed:r.lastAccessed,accessCount:r.accessCount,error:e,isLoading:!1};s.set(a,c);const n=this.cache.get(a);(!n||n.lastUpdated<c.lastUpdated||JSON.stringify(n.data)!==JSON.stringify(c.data))&&(i=!0)}this.cache.size!==s.size&&(i=!0),i&&(this.cache=s,this.enforceSizeLimit(!1),this.emitEvent({type:"cache:persistence:sync",key:this.persistenceId,timestamp:Date.now(),message:"Cache updated from remote state."})),this.isHandlingRemoteUpdate=!1}registerQuery(e,t,s={}){void 0!==s.staleTime&&s.staleTime<0&&(s.staleTime=0),void 0!==s.cacheTime&&s.cacheTime<0&&(s.cacheTime=0),this.queries.set(e,{fetchFunction:t,options:{...this.defaultOptions,...s}})}async get(e,t){const s=this.queries.get(e);if(!s)throw new Error(`No query registered for key: ${e}`);let i=this.cache.get(e);const a=this.isStale(i,s.options);let r=!1;if(i)i.lastAccessed=Date.now(),i.accessCount++,this.updateMetrics("hits"),a&&this.updateMetrics("staleHits"),this.emitEvent({type:"cache:read:hit",key:e,timestamp:Date.now(),data:i.data,isStale:a});else if(this.updateMetrics("misses"),this.emitEvent({type:"cache:read:miss",key:e,timestamp:Date.now()}),!t?.waitForFresh||a){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:1,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}if(t?.waitForFresh&&(!i||a||i.isLoading))try{const t=await this.fetchAndWait(e,s);return r&&this.cache.get(e)===i&&this.schedulePersistState(),t}catch(s){if(t.throwOnError)throw s;return this.cache.get(e)?.data}if(!i||a||i&&!i.isLoading&&0===i.lastUpdated&&!i.error){if(i&&!i.isLoading)i.isLoading=!0;else if(!i){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}this.fetch(e,s).catch((()=>{}))}if(r&&this.schedulePersistState(),i?.error&&t?.throwOnError)throw i.error;return i?.data}peek(e){const t=this.cache.get(e);return t&&(t.lastAccessed=Date.now(),t.accessCount++),t?.data}has(e){const t=this.cache.get(e),s=this.queries.get(e);return!(!t||!s)&&(!this.isStale(t,s.options)&&!t.isLoading)}async fetch(e,t){if(this.fetching.has(e))return this.fetching.get(e);let s=this.cache.get(e);s?s.isLoading||(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}async fetchAndWait(e,t){const s=this.fetching.get(e);if(s)return s;const i=await this.fetch(e,t);if(void 0===i){const t=this.cache.get(e);if(t?.error)throw t.error;throw new Error(`Failed to fetch data for key: ${e} after retries.`)}return i}async performFetchWithRetry(e,t,s){const{retryAttempts:i,retryDelay:a}=t.options;let r;s.isLoading=!0;for(let c=0;c<=i;c++)try{this.emitEvent({type:"cache:fetch:start",key:e,timestamp:Date.now(),attempt:c}),this.updateMetrics("fetches");const i=await t.fetchFunction();return s.data=i,s.lastUpdated=Date.now(),s.isLoading=!1,s.error=void 0,this.cache.set(e,s),this.schedulePersistState(),this.enforceSizeLimit(),this.emitEvent({type:"cache:fetch:success",key:e,timestamp:Date.now(),data:i}),i}catch(t){r=t,this.updateMetrics("errors"),this.emitEvent({type:"cache:fetch:error",key:e,timestamp:Date.now(),error:r,attempt:c}),c<i&&await this.delay(a*Math.pow(2,c))}s.error=r,s.isLoading=!1,this.cache.set(e,s),this.schedulePersistState()}isStale(e,t){if(!e||e.error)return!0;if(e.isLoading&&!e.data)return!0;const{staleTime:s}=t;return 0!==s&&s!==1/0&&Date.now()-e.lastUpdated>s}async invalidate(e,t=!0){const s=this.cache.get(e),i=this.queries.get(e);let a=!1;s&&(a=0!==s.lastUpdated||void 0!==s.error,s.lastUpdated=0,s.error=void 0,this.emitEvent({type:"cache:data:invalidate",key:e,timestamp:Date.now()}),a&&this.schedulePersistState(),t&&i&&this.fetch(e,i).catch((()=>{})))}async invalidatePattern(e,t=!0){const s=[];let i=!1;for(const t of this.cache.keys())e.test(t)&&s.push(t);s.forEach((e=>{const t=this.cache.get(e);t&&(0===t.lastUpdated&&void 0===t.error||(i=!0),t.lastUpdated=0,t.error=void 0,this.emitEvent({type:"cache:data:invalidate",key:e,timestamp:Date.now()}))})),i&&this.schedulePersistState(),t&&s.length>0&&await Promise.all(s.map((e=>{const t=this.queries.get(e);return t?this.fetch(e,t).catch((()=>{})):Promise.resolve()})))}async prefetch(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot prefetch: No query registered for key: ${e}`);const s=this.cache.get(e);s&&!this.isStale(s,t.options)||this.fetch(e,t).catch((()=>{}))}async refresh(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot refresh: No query registered for key: ${e}`);this.fetching.delete(e);let s=this.cache.get(e);s?(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}setData(e,t){const s=this.cache.get(e),i=s?.data,a={data:t,lastUpdated:Date.now(),lastAccessed:Date.now(),accessCount:(s?.accessCount||0)+1,isLoading:!1,error:void 0};this.cache.set(e,a),this.schedulePersistState(),this.enforceSizeLimit(),this.emitEvent({type:"cache:data:set",key:e,timestamp:Date.now(),newData:t,oldData:i})}remove(e){this.fetching.delete(e);const t=this.cache.has(e),s=this.cache.delete(e);return s&&t&&this.schedulePersistState(),s}enforceSizeLimit(e=!0){const{maxSize:t}=this.defaultOptions;if(t===1/0||this.cache.size<=t)return;let s=0;if(0===t){s=this.cache.size;for(const e of this.cache.keys())this.cache.delete(e),this.emitEvent({type:"cache:data:evict",key:e,timestamp:Date.now(),reason:"size_limit_zero"}),this.updateMetrics("evictions")}else{const e=Array.from(this.cache.entries()).sort((([,e],[,t])=>e.lastAccessed-t.lastAccessed)),i=this.cache.size-t;if(i>0){e.slice(0,i).forEach((([e])=>{this.cache.delete(e)&&(s++,this.emitEvent({type:"cache:data:evict",key:e,timestamp:Date.now(),reason:"size_limit_lru"}),this.updateMetrics("evictions"))}))}}s>0&&e&&this.schedulePersistState()}startGarbageCollection(){const{cacheTime:e}=this.defaultOptions;if(e===1/0||e<=0)return;const t=Math.max(1e3,Math.min(e/4,3e5));this.gcTimer=setInterval((()=>this.garbageCollect()),t)}garbageCollect(){const e=Date.now();let t=0;const s=[];for(const[t,i]of this.cache){if(i.isLoading)continue;const a=this.queries.get(t),r=a?.options.cacheTime??this.defaultOptions.cacheTime;r===1/0||r<=0||e-i.lastAccessed>r&&s.push(t)}return s.length>0&&(s.forEach((e=>{this.cache.delete(e)&&(this.fetching.delete(e),this.emitEvent({type:"cache:data:evict",key:e,timestamp:Date.now(),reason:"garbage_collected_idle"}),this.updateMetrics("evictions"),t++)})),this.schedulePersistState()),t}getStats(){const e=this.metrics.hits+this.metrics.misses,t=e>0?this.metrics.hits/e:0,s=this.metrics.hits>0?this.metrics.staleHits/this.metrics.hits:0,i=Array.from(this.cache.entries()).map((([e,t])=>{const s=this.queries.get(e),i=!s||this.isStale(t,s.options);return{key:e,lastAccessed:t.lastAccessed,lastUpdated:t.lastUpdated,accessCount:t.accessCount,isStale:i,isLoading:t.isLoading,error:!!t.error}}));return{size:this.cache.size,metrics:{...this.metrics},hitRate:t,staleHitRate:s,entries:i}}on(e,t){return this.eventBus.subscribe(e,t)}emitEvent(e){this.eventBus.emit({name:e.type,payload:e})}updateMetrics(e,t=1){this.defaultOptions.enableMetrics&&(this.metrics[e]=(this.metrics[e]||0)+t)}delay(e){return new Promise((t=>setTimeout(t,e)))}async clear(){const e=this.cache.size>0;if(this.cache.clear(),this.fetching.clear(),this.defaultOptions.enableMetrics&&(this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}),this.defaultOptions.persistence)try{await this.defaultOptions.persistence.clear(),this.emitEvent({type:"cache:persistence:clear:success",key:this.persistenceId,timestamp:Date.now()})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to clear persisted state:`,e),this.emitEvent({type:"cache:persistence:clear:error",key:this.persistenceId,timestamp:Date.now(),error:e})}else e&&this.schedulePersistState()}destroy(){if(this.gcTimer&&(clearInterval(this.gcTimer),this.gcTimer=void 0),this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceUnsubscribe)try{this.persistenceUnsubscribe()}catch(e){console.error(`Cache (${this.persistenceId}): Error unsubscribing persistence:`,e)}this.cache.clear(),this.fetching.clear(),this.queries.clear(),this.eventBus.clear(),this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}}};

package/index.mjs

@@ -1 +1 @@
-import{v4 as e}from"uuid";var t=class{cache=new Map;queries=new Map;fetching=new Map;defaultOptions;metrics;eventListeners=new Map;gcTimer;persistenceId;persistenceUnsubscribe;persistenceDebounceTimer;isHandlingRemoteUpdate=!1;constructor(t={}){void 0!==t.staleTime&&t.staleTime<0&&(console.warn("CacheOptions: staleTime should be non-negative. Using 0."),t.staleTime=0),void 0!==t.cacheTime&&t.cacheTime<0&&(console.warn("CacheOptions: cacheTime should be non-negative. Using 0."),t.cacheTime=0),void 0!==t.retryAttempts&&t.retryAttempts<0&&(console.warn("CacheOptions: retryAttempts should be non-negative. Using 0."),t.retryAttempts=0),void 0!==t.retryDelay&&t.retryDelay<0&&(console.warn("CacheOptions: retryDelay should be non-negative. Using 0."),t.retryDelay=0),void 0!==t.maxSize&&t.maxSize<0&&(console.warn("CacheOptions: maxSize should be non-negative. Using 0."),t.maxSize=0),this.defaultOptions={staleTime:3e5,cacheTime:18e5,retryAttempts:3,retryDelay:1e3,maxSize:1e3,enableMetrics:!0,persistence:void 0,persistenceId:void 0,serializeValue:e=>e,deserializeValue:e=>e,persistenceDebounceTime:500,...t},this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0},this.persistenceId=this.defaultOptions.persistenceId||e(),this.startGarbageCollection(),this.initializePersistence()}async initializePersistence(){const{persistence:e}=this.defaultOptions;if(e){try{const t=await e.get();t&&(this.deserializeAndLoadCache(t),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"load_success",message:`Cache loaded for ID: ${this.persistenceId}`}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to load state from persistence:`,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"load_fail",error:e,message:`Failed to load cache for ID: ${this.persistenceId}`})}if("function"==typeof e.subscribe)try{this.persistenceUnsubscribe=e.subscribe(this.persistenceId,(e=>{this.handleRemoteStateChange(e)}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to subscribe to persistence:`,e)}}}serializeCache(){const e=[],{serializeValue:t}=this.defaultOptions;for(const[s,i]of this.cache)i.isLoading&&void 0===i.data&&0===i.lastUpdated||e.push([s,{data:t(i.data),lastUpdated:i.lastUpdated,lastAccessed:i.lastAccessed,accessCount:i.accessCount,error:i.error?{name:i.error.name,message:i.error.message,stack:i.error.stack}:void 0}]);return e}deserializeAndLoadCache(e){this.isHandlingRemoteUpdate=!0;const t=new Map,{deserializeValue:s}=this.defaultOptions;for(const[i,a]of e){let e;a.error&&(e=new Error(a.error.message),e.name=a.error.name,e.stack=a.error.stack),t.set(i,{data:s(a.data),lastUpdated:a.lastUpdated,lastAccessed:a.lastAccessed,accessCount:a.accessCount,error:e,isLoading:!1})}this.cache=t,this.enforceSizeLimit(!1),this.isHandlingRemoteUpdate=!1}schedulePersistState(){this.defaultOptions.persistence&&!this.isHandlingRemoteUpdate&&(this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceDebounceTimer=setTimeout((async()=>{try{const e=this.serializeCache();await this.defaultOptions.persistence.set(this.persistenceId,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"save_success"})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to persist state:`,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"save_fail",error:e})}}),this.defaultOptions.persistenceDebounceTime))}handleRemoteStateChange(e){if(this.isHandlingRemoteUpdate||!e)return;this.isHandlingRemoteUpdate=!0;const{deserializeValue:t}=this.defaultOptions,s=new Map;let i=!1;for(const[a,r]of e){let e;r.error&&(e=new Error(r.error.message),e.name=r.error.name,e.stack=r.error.stack);const c={data:t(r.data),lastUpdated:r.lastUpdated,lastAccessed:r.lastAccessed,accessCount:r.accessCount,error:e,isLoading:!1};s.set(a,c);const n=this.cache.get(a);(!n||n.lastUpdated<c.lastUpdated||JSON.stringify(n.data)!==JSON.stringify(c.data))&&(i=!0)}this.cache.size!==s.size&&(i=!0),i&&(this.cache=s,this.enforceSizeLimit(!1),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"remote_update",message:"Cache updated from remote state."})),this.isHandlingRemoteUpdate=!1}registerQuery(e,t,s={}){void 0!==s.staleTime&&s.staleTime<0&&(s.staleTime=0),void 0!==s.cacheTime&&s.cacheTime<0&&(s.cacheTime=0),this.queries.set(e,{fetchFunction:t,options:{...this.defaultOptions,...s}})}async get(e,t){const s=this.queries.get(e);if(!s)throw new Error(`No query registered for key: ${e}`);let i=this.cache.get(e);const a=this.isStale(i,s.options);let r=!1;if(i)i.lastAccessed=Date.now(),i.accessCount++,this.updateMetrics("hits"),a&&this.updateMetrics("staleHits"),this.emitEvent({type:"hit",key:e,timestamp:Date.now(),data:i.data,isStale:a});else if(this.updateMetrics("misses"),this.emitEvent({type:"miss",key:e,timestamp:Date.now()}),!t?.waitForFresh||a){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:1,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}if(t?.waitForFresh&&(!i||a||i.isLoading))try{const t=await this.fetchAndWait(e,s);return r&&this.cache.get(e)===i&&this.schedulePersistState(),t}catch(s){if(t.throwOnError)throw s;return this.cache.get(e)?.data}if(!i||a||i&&!i.isLoading&&0===i.lastUpdated&&!i.error){if(i&&!i.isLoading)i.isLoading=!0;else if(!i){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}this.fetch(e,s).catch((()=>{}))}if(r&&this.schedulePersistState(),i?.error&&t?.throwOnError)throw i.error;return i?.data}peek(e){const t=this.cache.get(e);return t&&(t.lastAccessed=Date.now(),t.accessCount++),t?.data}has(e){const t=this.cache.get(e),s=this.queries.get(e);return!(!t||!s)&&(!this.isStale(t,s.options)&&!t.isLoading)}async fetch(e,t){if(this.fetching.has(e))return this.fetching.get(e);let s=this.cache.get(e);s?s.isLoading||(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}async fetchAndWait(e,t){const s=this.fetching.get(e);if(s)return s;const i=await this.fetch(e,t);if(void 0===i){const t=this.cache.get(e);if(t?.error)throw t.error;throw new Error(`Failed to fetch data for key: ${e} after retries.`)}return i}async performFetchWithRetry(e,t,s){const{retryAttempts:i,retryDelay:a}=t.options;let r;s.isLoading=!0;for(let c=0;c<=i;c++)try{this.emitEvent({type:"fetch",key:e,timestamp:Date.now(),attempt:c}),this.updateMetrics("fetches");const i=await t.fetchFunction();return s.data=i,s.lastUpdated=Date.now(),s.isLoading=!1,s.error=void 0,this.cache.set(e,s),this.schedulePersistState(),this.enforceSizeLimit(),i}catch(t){r=t,this.emitEvent({type:"error",key:e,timestamp:Date.now(),error:r,attempt:c}),c<i&&await this.delay(a*Math.pow(2,c))}this.updateMetrics("errors"),s.error=r,s.isLoading=!1,this.cache.set(e,s),this.schedulePersistState()}isStale(e,t){if(!e||e.error)return!0;if(e.isLoading&&!e.data)return!0;const{staleTime:s}=t;return 0!==s&&s!==1/0&&Date.now()-e.lastUpdated>s}async invalidate(e,t=!0){const s=this.cache.get(e),i=this.queries.get(e);let a=!1;s&&(a=0!==s.lastUpdated||void 0!==s.error,s.lastUpdated=0,s.error=void 0,this.emitEvent({type:"invalidation",key:e,timestamp:Date.now()}),a&&this.schedulePersistState(),t&&i&&this.fetch(e,i).catch((()=>{})))}async invalidatePattern(e,t=!0){const s=[];let i=!1;for(const t of this.cache.keys())e.test(t)&&s.push(t);s.forEach((e=>{const t=this.cache.get(e);t&&(0===t.lastUpdated&&void 0===t.error||(i=!0),t.lastUpdated=0,t.error=void 0,this.emitEvent({type:"invalidation",key:e,timestamp:Date.now()}))})),i&&this.schedulePersistState(),t&&s.length>0&&await Promise.all(s.map((e=>{const t=this.queries.get(e);return t?this.fetch(e,t).catch((()=>{})):Promise.resolve()})))}async prefetch(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot prefetch: No query registered for key: ${e}`);const s=this.cache.get(e);s&&!this.isStale(s,t.options)||this.fetch(e,t).catch((()=>{}))}async refresh(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot refresh: No query registered for key: ${e}`);this.fetching.delete(e);let s=this.cache.get(e);s?(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}setData(e,t){const s=this.cache.get(e),i=s?.data,a={data:t,lastUpdated:Date.now(),lastAccessed:Date.now(),accessCount:(s?.accessCount||0)+1,isLoading:!1,error:void 0};this.cache.set(e,a),this.schedulePersistState(),this.enforceSizeLimit(),this.emitEvent({type:"set_data",key:e,timestamp:Date.now(),newData:t,oldData:i})}remove(e){this.fetching.delete(e);const t=this.cache.has(e),s=this.cache.delete(e);return s&&t&&this.schedulePersistState(),s}enforceSizeLimit(e=!0){const{maxSize:t}=this.defaultOptions;if(t===1/0||this.cache.size<=t)return;let s=0;if(0===t){s=this.cache.size;for(const e of this.cache.keys())this.cache.delete(e),this.emitEvent({type:"eviction",key:e,timestamp:Date.now(),reason:"size_limit_zero"}),this.updateMetrics("evictions")}else{const e=Array.from(this.cache.entries()).sort((([,e],[,t])=>e.lastAccessed-t.lastAccessed)),i=this.cache.size-t;if(i>0){e.slice(0,i).forEach((([e])=>{this.cache.delete(e)&&(s++,this.emitEvent({type:"eviction",key:e,timestamp:Date.now(),reason:"size_limit_lru"}),this.updateMetrics("evictions"))}))}}s>0&&e&&this.schedulePersistState()}startGarbageCollection(){const{cacheTime:e}=this.defaultOptions;if(e===1/0||e<=0)return;const t=Math.max(1e3,Math.min(e/4,3e5));this.gcTimer=setInterval((()=>this.garbageCollect()),t)}garbageCollect(){const e=Date.now();let t=0;const s=[];for(const[t,i]of this.cache){if(i.isLoading)continue;const a=this.queries.get(t),r=a?.options.cacheTime??this.defaultOptions.cacheTime;r===1/0||r<=0||e-i.lastAccessed>r&&s.push(t)}return s.length>0&&(s.forEach((e=>{this.cache.delete(e)&&(this.fetching.delete(e),this.emitEvent({type:"eviction",key:e,timestamp:Date.now(),reason:"garbage_collected_idle"}),this.updateMetrics("evictions"),t++)})),this.schedulePersistState()),t}getStats(){const e=this.metrics.hits+this.metrics.misses,t=e>0?this.metrics.hits/e:0,s=this.metrics.hits>0?this.metrics.staleHits/this.metrics.hits:0,i=Array.from(this.cache.entries()).map((([e,t])=>{const s=this.queries.get(e),i=!s||this.isStale(t,s.options);return{key:e,lastAccessed:t.lastAccessed,lastUpdated:t.lastUpdated,accessCount:t.accessCount,isStale:i,isLoading:t.isLoading,error:!!t.error}}));return{size:this.cache.size,metrics:{...this.metrics},hitRate:t,staleHitRate:s,entries:i}}on(e,t){this.eventListeners.has(e)||this.eventListeners.set(e,new Set),this.eventListeners.get(e).add(t)}off(e,t){this.eventListeners.get(e)?.delete(t)}emitEvent(e){const t=this.eventListeners.get(e.type);t&&t.forEach((t=>{try{t(e)}catch(t){const s="persistence"===e.type?`for ID ${e.key}`:`for key ${e.key}`;console.error(`Cache event listener error during ${e.type} ${s}:`,t)}}))}updateMetrics(e,t=1){this.defaultOptions.enableMetrics&&(this.metrics[e]=(this.metrics[e]||0)+t)}delay(e){return new Promise((t=>setTimeout(t,e)))}async clear(){const e=this.cache.size>0;if(this.cache.clear(),this.fetching.clear(),this.defaultOptions.enableMetrics&&(this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}),this.defaultOptions.persistence)try{await this.defaultOptions.persistence.clear(),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"clear_success"})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to clear persisted state:`,e),this.emitEvent({type:"persistence",key:this.persistenceId,timestamp:Date.now(),event:"clear_fail",error:e})}else e&&this.schedulePersistState()}destroy(){if(this.gcTimer&&(clearInterval(this.gcTimer),this.gcTimer=void 0),this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceUnsubscribe)try{this.persistenceUnsubscribe()}catch(e){console.error(`Cache (${this.persistenceId}): Error unsubscribing persistence:`,e)}this.cache.clear(),this.fetching.clear(),this.queries.clear(),this.eventListeners.clear(),this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}}};export{t as Cache};
+import{v4 as e}from"uuid";var t,s,i=Object.create,a=Object.defineProperty,r=Object.getOwnPropertyDescriptor,c=Object.getOwnPropertyNames,n=Object.getPrototypeOf,o=Object.prototype.hasOwnProperty,h=(t={"node_modules/@asaidimu/events/index.js"(e,t){var s,i=Object.defineProperty,a=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,c=Object.prototype.hasOwnProperty,n={};((e,t)=>{for(var s in t)i(e,s,{get:t[s],enumerable:!0})})(n,{createEventBus:()=>o}),t.exports=(s=n,((e,t,s,n)=>{if(t&&"object"==typeof t||"function"==typeof t)for(let o of r(t))c.call(e,o)||o===s||i(e,o,{get:()=>t[o],enumerable:!(n=a(t,o))||n.enumerable});return e})(i({},"__esModule",{value:!0}),s));var o=(e={async:!1,batchSize:1e3,batchDelay:16,errorHandler:e=>console.error("EventBus Error:",e),crossTab:!1,channelName:"event-bus-channel"})=>{const t=new Map;let s=[],i=0,a=0;const r=new Map,c=new Map;let n=null;e.crossTab&&"undefined"!=typeof BroadcastChannel?n=new BroadcastChannel(e.channelName):e.crossTab&&console.warn("BroadcastChannel is not supported in this browser. Cross-tab notifications are disabled.");const o=(e,t)=>{i++,a+=t,r.set(e,(r.get(e)||0)+1)},h=()=>{const t=s;s=[],t.forEach((({name:t,payload:s})=>{const i=performance.now();try{(c.get(t)||[]).forEach((e=>e(s)))}catch(i){e.errorHandler({...i,eventName:t,payload:s})}o(t,performance.now()-i)}))},d=(()=>{let t;return()=>{clearTimeout(t),t=setTimeout(h,e.batchDelay)}})(),l=e=>{const s=t.get(e);s?c.set(e,Array.from(s)):c.delete(e)};return n&&(n.onmessage=e=>{const{name:t,payload:s}=e.data;(c.get(t)||[]).forEach((e=>e(s)))}),{subscribe:(e,s)=>{t.has(e)||t.set(e,new Set);const i=t.get(e);return i.add(s),l(e),()=>{i.delete(s),0===i.size?(t.delete(e),c.delete(e)):l(e)}},emit:({name:t,payload:i})=>{if(e.async)return s.push({name:t,payload:i}),s.length>=e.batchSize?h():d(),void(n&&n.postMessage({name:t,payload:i}));const a=performance.now();try{(c.get(t)||[]).forEach((e=>e(i))),n&&n.postMessage({name:t,payload:i})}catch(s){e.errorHandler({...s,eventName:t,payload:i})}o(t,performance.now()-a)},getMetrics:()=>({totalEvents:i,activeSubscriptions:Array.from(t.values()).reduce(((e,t)=>e+t.size),0),eventCounts:r,averageEmitDuration:i>0?a/i:0}),clear:()=>{t.clear(),c.clear(),s=[],i=0,a=0,r.clear(),n&&(n.close(),n=null)}}}}},function(){return s||(0,t[c(t)[0]])((s={exports:{}}).exports,s),s.exports}),d=((e,t,s)=>(s=null!=e?i(n(e)):{},((e,t,s,i)=>{if(t&&"object"==typeof t||"function"==typeof t)for(let n of c(t))o.call(e,n)||n===s||a(e,n,{get:()=>t[n],enumerable:!(i=r(t,n))||i.enumerable});return e})(e&&e.__esModule?s:a(s,"default",{value:e,enumerable:!0}),e)))(h()),l=class{cache=new Map;queries=new Map;fetching=new Map;defaultOptions;metrics;eventBus;gcTimer;persistenceId;persistenceUnsubscribe;persistenceDebounceTimer;isHandlingRemoteUpdate=!1;constructor(t={}){void 0!==t.staleTime&&t.staleTime<0&&(console.warn("CacheOptions: staleTime should be non-negative. Using 0."),t.staleTime=0),void 0!==t.cacheTime&&t.cacheTime<0&&(console.warn("CacheOptions: cacheTime should be non-negative. Using 0."),t.cacheTime=0),void 0!==t.retryAttempts&&t.retryAttempts<0&&(console.warn("CacheOptions: retryAttempts should be non-negative. Using 0."),t.retryAttempts=0),void 0!==t.retryDelay&&t.retryDelay<0&&(console.warn("CacheOptions: retryDelay should be non-negative. Using 0."),t.retryDelay=0),void 0!==t.maxSize&&t.maxSize<0&&(console.warn("CacheOptions: maxSize should be non-negative. Using 0."),t.maxSize=0),this.defaultOptions={staleTime:0,cacheTime:18e5,retryAttempts:3,retryDelay:1e3,maxSize:1e3,enableMetrics:!0,persistence:void 0,persistenceId:void 0,serializeValue:e=>e,deserializeValue:e=>e,persistenceDebounceTime:500,...t},this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0},this.persistenceId=this.defaultOptions.persistenceId||e(),this.eventBus=(0,d.createEventBus)(),this.startGarbageCollection(),this.initializePersistence()}async initializePersistence(){const{persistence:e}=this.defaultOptions;if(e){try{const t=await e.get();t&&(this.deserializeAndLoadCache(t),this.emitEvent({type:"cache:persistence:load:success",key:this.persistenceId,timestamp:Date.now(),message:`Cache loaded for ID: ${this.persistenceId}`}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to load state from persistence:`,e),this.emitEvent({type:"cache:persistence:load:error",key:this.persistenceId,timestamp:Date.now(),error:e,message:`Failed to load cache for ID: ${this.persistenceId}`})}if("function"==typeof e.subscribe)try{this.persistenceUnsubscribe=e.subscribe(this.persistenceId,(e=>{this.handleRemoteStateChange(e)}))}catch(e){console.error(`Cache (${this.persistenceId}): Failed to subscribe to persistence:`,e)}}}serializeCache(){const e=[],{serializeValue:t}=this.defaultOptions;for(const[s,i]of this.cache)i.isLoading&&void 0===i.data&&0===i.lastUpdated||e.push([s,{data:t(i.data),lastUpdated:i.lastUpdated,lastAccessed:i.lastAccessed,accessCount:i.accessCount,error:i.error?{name:i.error.name,message:i.error.message,stack:i.error.stack}:void 0}]);return e}deserializeAndLoadCache(e){this.isHandlingRemoteUpdate=!0;const t=new Map,{deserializeValue:s}=this.defaultOptions;for(const[i,a]of e){let e;a.error&&(e=new Error(a.error.message),e.name=a.error.name,e.stack=a.error.stack),t.set(i,{data:s(a.data),lastUpdated:a.lastUpdated,lastAccessed:a.lastAccessed,accessCount:a.accessCount,error:e,isLoading:!1})}this.cache=t,this.enforceSizeLimit(!1),this.isHandlingRemoteUpdate=!1}schedulePersistState(){this.defaultOptions.persistence&&!this.isHandlingRemoteUpdate&&(this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceDebounceTimer=setTimeout((async()=>{try{const e=this.serializeCache();await this.defaultOptions.persistence.set(this.persistenceId,e),this.emitEvent({type:"cache:persistence:save:success",key:this.persistenceId,timestamp:Date.now()})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to persist state:`,e),this.emitEvent({type:"cache:persistence:save:error",key:this.persistenceId,timestamp:Date.now(),error:e})}}),this.defaultOptions.persistenceDebounceTime))}handleRemoteStateChange(e){if(this.isHandlingRemoteUpdate||!e)return;this.isHandlingRemoteUpdate=!0;const{deserializeValue:t}=this.defaultOptions,s=new Map;let i=!1;for(const[a,r]of e){let e;r.error&&(e=new Error(r.error.message),e.name=r.error.name,e.stack=r.error.stack);const c={data:t(r.data),lastUpdated:r.lastUpdated,lastAccessed:r.lastAccessed,accessCount:r.accessCount,error:e,isLoading:!1};s.set(a,c);const n=this.cache.get(a);(!n||n.lastUpdated<c.lastUpdated||JSON.stringify(n.data)!==JSON.stringify(c.data))&&(i=!0)}this.cache.size!==s.size&&(i=!0),i&&(this.cache=s,this.enforceSizeLimit(!1),this.emitEvent({type:"cache:persistence:sync",key:this.persistenceId,timestamp:Date.now(),message:"Cache updated from remote state."})),this.isHandlingRemoteUpdate=!1}registerQuery(e,t,s={}){void 0!==s.staleTime&&s.staleTime<0&&(s.staleTime=0),void 0!==s.cacheTime&&s.cacheTime<0&&(s.cacheTime=0),this.queries.set(e,{fetchFunction:t,options:{...this.defaultOptions,...s}})}async get(e,t){const s=this.queries.get(e);if(!s)throw new Error(`No query registered for key: ${e}`);let i=this.cache.get(e);const a=this.isStale(i,s.options);let r=!1;if(i)i.lastAccessed=Date.now(),i.accessCount++,this.updateMetrics("hits"),a&&this.updateMetrics("staleHits"),this.emitEvent({type:"cache:read:hit",key:e,timestamp:Date.now(),data:i.data,isStale:a});else if(this.updateMetrics("misses"),this.emitEvent({type:"cache:read:miss",key:e,timestamp:Date.now()}),!t?.waitForFresh||a){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:1,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}if(t?.waitForFresh&&(!i||a||i.isLoading))try{const t=await this.fetchAndWait(e,s);return r&&this.cache.get(e)===i&&this.schedulePersistState(),t}catch(s){if(t.throwOnError)throw s;return this.cache.get(e)?.data}if(!i||a||i&&!i.isLoading&&0===i.lastUpdated&&!i.error){if(i&&!i.isLoading)i.isLoading=!0;else if(!i){const t={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0};this.cache.set(e,t),i=t,r=!0}this.fetch(e,s).catch((()=>{}))}if(r&&this.schedulePersistState(),i?.error&&t?.throwOnError)throw i.error;return i?.data}peek(e){const t=this.cache.get(e);return t&&(t.lastAccessed=Date.now(),t.accessCount++),t?.data}has(e){const t=this.cache.get(e),s=this.queries.get(e);return!(!t||!s)&&(!this.isStale(t,s.options)&&!t.isLoading)}async fetch(e,t){if(this.fetching.has(e))return this.fetching.get(e);let s=this.cache.get(e);s?s.isLoading||(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}async fetchAndWait(e,t){const s=this.fetching.get(e);if(s)return s;const i=await this.fetch(e,t);if(void 0===i){const t=this.cache.get(e);if(t?.error)throw t.error;throw new Error(`Failed to fetch data for key: ${e} after retries.`)}return i}async performFetchWithRetry(e,t,s){const{retryAttempts:i,retryDelay:a}=t.options;let r;s.isLoading=!0;for(let c=0;c<=i;c++)try{this.emitEvent({type:"cache:fetch:start",key:e,timestamp:Date.now(),attempt:c}),this.updateMetrics("fetches");const i=await t.fetchFunction();return s.data=i,s.lastUpdated=Date.now(),s.isLoading=!1,s.error=void 0,this.cache.set(e,s),this.schedulePersistState(),this.enforceSizeLimit(),this.emitEvent({type:"cache:fetch:success",key:e,timestamp:Date.now(),data:i}),i}catch(t){r=t,this.updateMetrics("errors"),this.emitEvent({type:"cache:fetch:error",key:e,timestamp:Date.now(),error:r,attempt:c}),c<i&&await this.delay(a*Math.pow(2,c))}s.error=r,s.isLoading=!1,this.cache.set(e,s),this.schedulePersistState()}isStale(e,t){if(!e||e.error)return!0;if(e.isLoading&&!e.data)return!0;const{staleTime:s}=t;return 0!==s&&s!==1/0&&Date.now()-e.lastUpdated>s}async invalidate(e,t=!0){const s=this.cache.get(e),i=this.queries.get(e);let a=!1;s&&(a=0!==s.lastUpdated||void 0!==s.error,s.lastUpdated=0,s.error=void 0,this.emitEvent({type:"cache:data:invalidate",key:e,timestamp:Date.now()}),a&&this.schedulePersistState(),t&&i&&this.fetch(e,i).catch((()=>{})))}async invalidatePattern(e,t=!0){const s=[];let i=!1;for(const t of this.cache.keys())e.test(t)&&s.push(t);s.forEach((e=>{const t=this.cache.get(e);t&&(0===t.lastUpdated&&void 0===t.error||(i=!0),t.lastUpdated=0,t.error=void 0,this.emitEvent({type:"cache:data:invalidate",key:e,timestamp:Date.now()}))})),i&&this.schedulePersistState(),t&&s.length>0&&await Promise.all(s.map((e=>{const t=this.queries.get(e);return t?this.fetch(e,t).catch((()=>{})):Promise.resolve()})))}async prefetch(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot prefetch: No query registered for key: ${e}`);const s=this.cache.get(e);s&&!this.isStale(s,t.options)||this.fetch(e,t).catch((()=>{}))}async refresh(e){const t=this.queries.get(e);if(!t)return void console.warn(`Cannot refresh: No query registered for key: ${e}`);this.fetching.delete(e);let s=this.cache.get(e);s?(s.isLoading=!0,s.error=void 0):(s={data:void 0,lastUpdated:0,lastAccessed:Date.now(),accessCount:0,isLoading:!0,error:void 0},this.cache.set(e,s),this.schedulePersistState());const i=this.performFetchWithRetry(e,t,s);this.fetching.set(e,i);try{return await i}finally{this.fetching.delete(e)}}setData(e,t){const s=this.cache.get(e),i=s?.data,a={data:t,lastUpdated:Date.now(),lastAccessed:Date.now(),accessCount:(s?.accessCount||0)+1,isLoading:!1,error:void 0};this.cache.set(e,a),this.schedulePersistState(),this.enforceSizeLimit(),this.emitEvent({type:"cache:data:set",key:e,timestamp:Date.now(),newData:t,oldData:i})}remove(e){this.fetching.delete(e);const t=this.cache.has(e),s=this.cache.delete(e);return s&&t&&this.schedulePersistState(),s}enforceSizeLimit(e=!0){const{maxSize:t}=this.defaultOptions;if(t===1/0||this.cache.size<=t)return;let s=0;if(0===t){s=this.cache.size;for(const e of this.cache.keys())this.cache.delete(e),this.emitEvent({type:"cache:data:evict",key:e,timestamp:Date.now(),reason:"size_limit_zero"}),this.updateMetrics("evictions")}else{const e=Array.from(this.cache.entries()).sort((([,e],[,t])=>e.lastAccessed-t.lastAccessed)),i=this.cache.size-t;if(i>0){e.slice(0,i).forEach((([e])=>{this.cache.delete(e)&&(s++,this.emitEvent({type:"cache:data:evict",key:e,timestamp:Date.now(),reason:"size_limit_lru"}),this.updateMetrics("evictions"))}))}}s>0&&e&&this.schedulePersistState()}startGarbageCollection(){const{cacheTime:e}=this.defaultOptions;if(e===1/0||e<=0)return;const t=Math.max(1e3,Math.min(e/4,3e5));this.gcTimer=setInterval((()=>this.garbageCollect()),t)}garbageCollect(){const e=Date.now();let t=0;const s=[];for(const[t,i]of this.cache){if(i.isLoading)continue;const a=this.queries.get(t),r=a?.options.cacheTime??this.defaultOptions.cacheTime;r===1/0||r<=0||e-i.lastAccessed>r&&s.push(t)}return s.length>0&&(s.forEach((e=>{this.cache.delete(e)&&(this.fetching.delete(e),this.emitEvent({type:"cache:data:evict",key:e,timestamp:Date.now(),reason:"garbage_collected_idle"}),this.updateMetrics("evictions"),t++)})),this.schedulePersistState()),t}getStats(){const e=this.metrics.hits+this.metrics.misses,t=e>0?this.metrics.hits/e:0,s=this.metrics.hits>0?this.metrics.staleHits/this.metrics.hits:0,i=Array.from(this.cache.entries()).map((([e,t])=>{const s=this.queries.get(e),i=!s||this.isStale(t,s.options);return{key:e,lastAccessed:t.lastAccessed,lastUpdated:t.lastUpdated,accessCount:t.accessCount,isStale:i,isLoading:t.isLoading,error:!!t.error}}));return{size:this.cache.size,metrics:{...this.metrics},hitRate:t,staleHitRate:s,entries:i}}on(e,t){return this.eventBus.subscribe(e,t)}emitEvent(e){this.eventBus.emit({name:e.type,payload:e})}updateMetrics(e,t=1){this.defaultOptions.enableMetrics&&(this.metrics[e]=(this.metrics[e]||0)+t)}delay(e){return new Promise((t=>setTimeout(t,e)))}async clear(){const e=this.cache.size>0;if(this.cache.clear(),this.fetching.clear(),this.defaultOptions.enableMetrics&&(this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}),this.defaultOptions.persistence)try{await this.defaultOptions.persistence.clear(),this.emitEvent({type:"cache:persistence:clear:success",key:this.persistenceId,timestamp:Date.now()})}catch(e){console.error(`Cache (${this.persistenceId}): Failed to clear persisted state:`,e),this.emitEvent({type:"cache:persistence:clear:error",key:this.persistenceId,timestamp:Date.now(),error:e})}else e&&this.schedulePersistState()}destroy(){if(this.gcTimer&&(clearInterval(this.gcTimer),this.gcTimer=void 0),this.persistenceDebounceTimer&&clearTimeout(this.persistenceDebounceTimer),this.persistenceUnsubscribe)try{this.persistenceUnsubscribe()}catch(e){console.error(`Cache (${this.persistenceId}): Error unsubscribing persistence:`,e)}this.cache.clear(),this.fetching.clear(),this.queries.clear(),this.eventBus.clear(),this.metrics={hits:0,misses:0,fetches:0,errors:0,evictions:0,staleHits:0}}};export{l as QueryCache};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@asaidimu/utils-cache",
-  "version": "2.0.4",
-  "description": "Caching utilities for @asaidimu applications.",
+  "version": "2.1.0",
+  "description": "Resource and cache management utilities for @asaidimu applications.",
   "main": "index.js",
   "module": "index.mjs",
   "types": "index.d.ts",
@@ -10,6 +10,7 @@
   ],
   "keywords": [
     "typescript",
+    "query",
     "cache",
     "utility"
   ],
@@ -29,8 +30,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@asaidimu/utils-persistence": "^2.0.0",
-    "uuid": "^11.1.0"
+    "@asaidimu/utils-persistence": "2.1.0",
+    "uuid": "^11.1.0",
+    "@asaidimu/events": "^1.1.1"
   },
   "exports": {
     ".": {