@asaidimu/utils-persistence 5.0.2 → 6.1.0

package/README.md

@@ -10,20 +10,20 @@
 
 ## 📖 Table of Contents
 
-*   [Overview & Features](#overview--features)
-*   [Installation & Setup](#installation--setup)
-*   [Usage Documentation](#usage-documentation)
-    *   [Core Interface: `SimplePersistence`](#core-interface-simplepersistence)
-    *   [The Power of Adapters](#the-power-of-adapters)
-    *   [Usage Guidelines](#usage-guidelines-for-those-consuming-the-simplepersistence-interface)
-    *   [When to Use and When to Avoid `SimplePersistence`](#when-to-use-and-when-to-avoid-simplepersistence)
-    *   [Web Storage Persistence (`WebStoragePersistence`)](#web-storage-persistence-webstoragepersistence)
-    *   [IndexedDB Persistence (`IndexedDBPersistence`)](#indexeddb-persistence-indexeddbpersistence)
-    *   [Ephemeral Persistence (`EphemeralPersistence`)](#ephemeral-persistence-ephemeralpersistence)
-    *   [Common Use Cases](#common-use-cases)
-*   [Project Architecture](#project-architecture)
-*   [Development & Contributing](#development--contributing)
-*   [Additional Information](#additional-information)
+- [Overview & Features](#overview--features)
+- [Installation & Setup](#installation--setup)
+- [Usage Documentation](#usage-documentation)
+  - [Core Interface: `SimplePersistence`](#core-interface-simplepersistence)
+  - [The Power of Adapters](#the-power-of-adapters)
+  - [Usage Guidelines](#usage-guidelines-for-those-consuming-the-simplepersistence-interface)
+  - [When to Use and When to Avoid `SimplePersistence`](#when-to-use-and-when-to-avoid-simplepersistence)
+  - [Web Storage Persistence (`WebStoragePersistence`)](#web-storage-persistence-webstoragepersistence)
+  - [IndexedDB Persistence (`IndexedDBPersistence`)](#indexeddb-persistence-indexeddbpersistence)
+  - [Ephemeral Persistence (`EphemeralPersistence`)](#ephemeral-persistence-ephemeralpersistence)
+  - [Common Use Cases](#common-use-cases)
+- [Project Architecture](#project-architecture)
+- [Development & Contributing](#development--contributing)
+- [Additional Information](#additional-information)
 
 ---
 
@@ -35,18 +35,18 @@ This library is ideal for single-page applications (SPAs) that require robust st
 
 ### 🚀 Key Features
 
-*   **Unified `SimplePersistence<T>` API**: A consistent interface for all storage adapters, simplifying integration and making switching storage types straightforward.
-*   **Flexible Storage Options**:
-    *   `WebStoragePersistence`: Supports both `localStorage` (default) and `sessionStorage` for simple key-value storage. Ideal for user preferences or small, temporary data.
-    *   `IndexedDBPersistence`: Provides robust, high-capacity, and structured data storage for more complex needs like offline caching or large datasets. Leverages `@asaidimu/indexed` for simplified IndexedDB interactions.
-    *   `EphemeralPersistence`: Offers an in-memory store with cross-tab synchronization using a Last Write Wins (LWW) strategy. Ideal for transient, session-specific shared state that does not need to persist across page reloads.
-*   **Automatic Cross-Instance Synchronization**: Real-time updates across multiple browser tabs, windows, or even components within the same tab. This is achieved by leveraging native `StorageEvent` (for `localStorage`) and `BroadcastChannel`-based event buses (from `@asaidimu/events`) for `WebStoragePersistence`, `IndexedDBPersistence`, and `EphemeralPersistence`.
-*   **Data Versioning and Migration**: Each store can be configured with a `version` and an optional `onUpgrade` handler to manage data schema changes gracefully across application updates.
-*   **Type-Safe**: Fully written in TypeScript, providing strong typing, compile-time checks, and autocompletion for a better developer experience.
-*   **Lightweight & Minimal Dependencies**: Designed to be small and efficient, relying on a few focused internal utilities (`@asaidimu/events`, `@asaidimu/indexed`, `@asaidimu/query`).
-*   **Robust Error Handling**: Includes internal error handling for common storage operations, providing clearer debugging messages when issues arise.
-*   **Instance-Specific Subscriptions**: The `subscribe` method intelligently uses a unique `instanceId` to listen for changes from *other* instances of the application (e.g., other tabs or different components sharing the same store), deliberately preventing self-triggered updates and enabling efficient state reconciliation without infinite loops.
-*   **Asynchronous Operations**: `IndexedDBPersistence` methods return Promises, allowing for non-blocking UI and efficient handling of large data operations. `WebStoragePersistence` and `EphemeralPersistence` are synchronous where possible, but their cross-tab synchronization aspects are asynchronous.
+- **Unified `SimplePersistence<T>` API**: A consistent interface for all storage adapters, simplifying integration and making switching storage types straightforward.
+- **Flexible Storage Options**:
+  - `WebStoragePersistence`: Supports both `localStorage` (default) and `sessionStorage` for simple key-value storage. Ideal for user preferences or small, temporary data.
+  - `IndexedDBPersistence`: Provides robust, high-capacity, and structured data storage for more complex needs like offline caching or large datasets. Leverages `@asaidimu/indexed` for simplified IndexedDB interactions.
+  - `EphemeralPersistence`: Offers an in-memory store with cross-tab synchronization using a Last Write Wins (LWW) strategy. Ideal for transient, session-specific shared state that does not need to persist across page reloads.
+- **Automatic Cross-Instance Synchronization**: Real-time updates across multiple browser tabs, windows, or even components within the same tab. This is achieved by leveraging native `StorageEvent` (for `localStorage`) and `BroadcastChannel`-based event buses (from `@asaidimu/events`) for `WebStoragePersistence`, `IndexedDBPersistence`, and `EphemeralPersistence`.
+- **Data Versioning and Migration**: Each store can be configured with a `version` and an optional `onUpgrade` handler to manage data schema changes gracefully across application updates.
+- **Type-Safe**: Fully written in TypeScript, providing strong typing, compile-time checks, and autocompletion for a better developer experience.
+- **Lightweight & Minimal Dependencies**: Designed to be small and efficient, relying on a few focused internal utilities (`@asaidimu/events`, `@asaidimu/indexed`, `@asaidimu/query`).
+- **Robust Error Handling**: Includes internal error handling for common storage operations, providing clearer debugging messages when issues arise.
+- **Instance-Specific Subscriptions**: The `subscribe` method intelligently uses a unique `instanceId` to listen for changes from _other_ instances of the application (e.g., other tabs or different components sharing the same store), deliberately preventing self-triggered updates and enabling efficient state reconciliation without infinite loops.
+- **Asynchronous Operations**: `IndexedDBPersistence` methods return Promises, allowing for non-blocking UI and efficient handling of large data operations. `WebStoragePersistence` and `EphemeralPersistence` are synchronous where possible, but their cross-tab synchronization aspects are asynchronous.
 
 ---
 
@@ -56,9 +56,9 @@ This library is ideal for single-page applications (SPAs) that require robust st
 
 To use `@asaidimu/utils-persistence`, you need:
 
-*   Node.js (LTS version recommended)
-*   npm, Yarn, or Bun package manager
-*   A modern web browser environment (e.g., Chrome, Firefox, Safari, Edge) that supports `localStorage`, `sessionStorage`, `IndexedDB`, and `BroadcastChannel`.
+- Node.js (LTS version recommended)
+- npm, Yarn, or Bun package manager
+- A modern web browser environment (e.g., Chrome, Firefox, Safari, Edge) that supports `localStorage`, `sessionStorage`, `IndexedDB`, and `BroadcastChannel`.
 
 ### Installation Steps
 
@@ -92,27 +92,29 @@ This library does not require global configuration. All settings are passed dire
 ```typescript
 // The base configuration for any persistence store
 export interface StoreConfig<T> {
-    /**
-     * The semantic version string (e.g., "1.0.0") of the data schema or application.
-     * Used for version control and data migrations.
-     */
-    version: string;
+  /**
+   * The semantic version string (e.g., "1.0.0") of the data schema or application.
+   * Used for version control and data migrations.
+   */
+  version: string;
 
-    /**
-     * A unique application identifier (e.g., "chat-app").
-     * Prevents collisions between different apps sharing the same persistence backend.
-     */
-    app: string;
+  /**
+   * A unique application identifier (e.g., "chat-app").
+   * Prevents collisions between different apps sharing the same persistence backend.
+   */
+  app: string;
 
-    /**
-     * Optional handler for upgrading persisted state across versions.
-     * Called when the persisted state’s `version` does not match the config's `version`.
-     * @param state The existing state object { data: T | null; version: string; app: string }.
-     * @returns A new state object { state: T | null; version: string } with the migrated data.
-     */
-    onUpgrade?: (
-        state: { data: T | null; version: string; app: string }
-    ) => Promise<{ state: T | null; version: string }>;
+  /**
+   * Optional handler for upgrading persisted state across versions.
+   * Called when the persisted state’s `version` does not match the config's `version`.
+   * @param state The existing state object { data: T | null; version: string; app: string }.
+   * @returns A new state object { state: T | null; version: string } with the migrated data.
+   */
+  onUpgrade?: (state: {
+    data: T | null;
+    version: string;
+    app: string;
+  }) => Promise<{ state: T | null; version: string }>;
 }
 ```
 
@@ -121,9 +123,13 @@ export interface StoreConfig<T> {
 You can quickly verify the installation by attempting to import one of the classes:
 
 ```typescript
-import { WebStoragePersistence, IndexedDBPersistence, EphemeralPersistence } from '@asaidimu/utils-persistence';
+import {
+  WebStoragePersistence,
+  IndexedDBPersistence,
+  EphemeralPersistence,
+} from "@asaidimu/utils-persistence";
 
-console.log('Persistence modules loaded successfully!');
+console.log("Persistence modules loaded successfully!");
 
 // You can now create instances:
 // const myLocalStorageStore = new WebStoragePersistence<{ appState: string }>(/* config */);
@@ -161,7 +167,7 @@ export interface SimplePersistence<T> {
    * @returns The retrieved state of type `T`, or `null` if no data is found or if an error occurs during retrieval/parsing.
    * For asynchronous implementations, this returns a `Promise<T | null>`.
    */
-  get(): (T | null) | (Promise<T | null>);
+  get(): (T | null) | Promise<T | null>;
 
   /**
    * Subscribes to changes in the global persisted data that originate from *other* instances of your application (e.g., other tabs or independent components using the same persistence layer).
@@ -179,27 +185,29 @@ export interface SimplePersistence<T> {
    */
   clear(): boolean | Promise<boolean>;
 
-    /**
-     * Returns metadata about the persistence layer.
-     *
-     * This is useful for distinguishing between multiple apps running on the same host
-     * (e.g., several apps served at `localhost:3000` that share the same storage key).
-     *
-     * @returns An object containing:
-     * - `version`: The semantic version string of the persistence schema or application.
-     * - `id`: A unique identifier for the application using this persistence instance.
-     */
-    stats(): { version: string; id: string };
+  /**
+   * Returns metadata about the persistence layer.
+   *
+   * This is useful for distinguishing between multiple apps running on the same host
+   * (e.g., several apps served at `localhost:3000` that share the same storage key).
+   *
+   * @returns An object containing:
+   * - `version`: The semantic version string of the persistence schema or application.
+   * - `id`: A unique identifier for the application using this persistence instance.
+   */
+  stats(): { version: string; id: string };
 }
 ```
 
 ### The Power of Adapters
+
 The adapter pattern used by `SimplePersistence<T>` is a key strength, enabling seamless swapping of persistence backends without altering application logic. This decoupling offers several advantages:
--   **Interchangeability**: Switch between storage mechanisms (e.g., `localStorage`, `IndexedDB`, an in-memory store, or a remote API) by simply changing the adapter, keeping the interface consistent.
--   **Scalability**: Start with a lightweight adapter (e.g., `EphemeralPersistence` for prototyping) and transition to a robust solution (e.g., `IndexedDBPersistence` or a server-based database) as needs evolve, with minimal changes to the consuming code.
--   **Extensibility**: Easily create custom adapters for new storage technologies or environments (e.g., file systems, serverless functions) while adhering to the same interface.
--   **Environment-Agnostic**: Use the same interface in browser, server, or hybrid applications, supporting diverse use cases like offline-first apps or cross-tab synchronization.
--   **Testing Simplicity**: Implement mock adapters for testing, isolating persistence logic without touching real storage.
+
+- **Interchangeability**: Switch between storage mechanisms (e.g., `localStorage`, `IndexedDB`, an in-memory store, or a remote API) by simply changing the adapter, keeping the interface consistent.
+- **Scalability**: Start with a lightweight adapter (e.g., `EphemeralPersistence` for prototyping) and transition to a robust solution (e.g., `IndexedDBPersistence` or a server-based database) as needs evolve, with minimal changes to the consuming code.
+- **Extensibility**: Easily create custom adapters for new storage technologies or environments (e.g., file systems, serverless functions) while adhering to the same interface.
+- **Environment-Agnostic**: Use the same interface in browser, server, or hybrid applications, supporting diverse use cases like offline-first apps or cross-tab synchronization.
+- **Testing Simplicity**: Implement mock adapters for testing, isolating persistence logic without touching real storage.
 
 This flexibility ensures that the persistence layer can adapt to varying requirements, from small-scale prototypes to production-grade systems, while maintaining a consistent and predictable API.
 
@@ -211,16 +219,17 @@ This section provides practical advice for consuming the `SimplePersistence<T>`
 
 This is the most crucial point to grasp:
 
-*   **`id` does NOT refer to an ID *within* your data type `T`**. If your `T` represents a complex object (e.g., `{ users: User[]; settings: AppSettings; }`), any IDs for `User` objects or specific settings should be managed *inside* your `T` type.
-*   **`id` refers to the unique identifier of the *consumer instance* that is interacting with the persistence layer.**
-    *   Think of a "consumer instance" as a specific browser tab, a running web worker, a distinct application component, or any other isolated context that uses `SimplePersistence`.
-    *   This `id` should be a **UUID (Universally Unique Identifier)**, generated **once** when that consumer instance initializes.
+- **`id` does NOT refer to an ID _within_ your data type `T`**. If your `T` represents a complex object (e.g., `{ users: User[]; settings: AppSettings; }`), any IDs for `User` objects or specific settings should be managed _inside_ your `T` type.
+- **`id` refers to the unique identifier of the _consumer instance_ that is interacting with the persistence layer.**
+  - Think of a "consumer instance" as a specific browser tab, a running web worker, a distinct application component, or any other isolated context that uses `SimplePersistence`.
+  - This `id` should be a **UUID (Universally Unique Identifier)**, generated **once** when that consumer instance initializes.
 
 **Why is this `id` essential?**
 
 It enables robust **multi-instance synchronization**. When multiple instances (e.g., different browser tabs) share the same underlying storage, the `id` allows the persistence layer to:
-*   **Identify the source of a change:** When `set(id, state)` is called, the layer knows *which* instance initiated the save.
-*   **Filter notifications:** The `subscribe(id, callback)` method uses this `id` to ensure that a subscribing instance is notified of changes *only* if they originated from *another* instance, preventing unnecessary self-triggered updates.
+
+- **Identify the source of a change:** When `set(id, state)` is called, the layer knows _which_ instance initiated the save.
+- **Filter notifications:** The `subscribe(id, callback)` method uses this `id` to ensure that a subscribing instance is notified of changes _only_ if they originated from _another_ instance, preventing unnecessary self-triggered updates.
 
 #### 2. Practical Examples for Consuming `SimplePersistence`
 
@@ -229,8 +238,12 @@ It enables robust **multi-instance synchronization**. When multiple instances (e
 Generate a unique UUID for your consumer instance at its very beginning (e.g., when your main application component mounts or your service initializes).
 
 ```typescript
-import { v4 as uuidv4 } from 'uuid'; // Requires 'uuid' library to be installed: `bun add uuid`
-import { SimplePersistence, WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
+import { v4 as uuidv4 } from "uuid"; // Requires 'uuid' library to be installed: `bun add uuid`
+import {
+  SimplePersistence,
+  WebStoragePersistence,
+  StoreConfig,
+} from "@asaidimu/utils-persistence";
 
 interface MyAppState {
   data: string;
@@ -242,7 +255,11 @@ class MyAppComponent {
   private instanceId: string;
   private persistence: SimplePersistence<MyAppState>;
   private unsubscribe: (() => void) | null = null;
-  private appState: MyAppState = { data: 'initial', count: 0, lastUpdated: Date.now() };
+  private appState: MyAppState = {
+    data: "initial",
+    count: 0,
+    lastUpdated: Date.now(),
+  };
 
   constructor(persistenceAdapter: SimplePersistence<MyAppState>) {
     this.instanceId = uuidv4(); // Generate unique ID for this app/tab instance
@@ -255,31 +272,45 @@ class MyAppComponent {
       // Load initial state
       const storedState = await this.persistence.get();
       if (storedState) {
-        console.log(`Instance ${this.instanceId}: Loaded initial state.`, storedState);
+        console.log(
+          `Instance ${this.instanceId}: Loaded initial state.`,
+          storedState,
+        );
         this.appState = storedState; // Update your app's internal state with loaded data
       } else {
-        console.log(`Instance ${this.instanceId}: No initial state found. Using default.`);
+        console.log(
+          `Instance ${this.instanceId}: No initial state found. Using default.`,
+        );
         // Optionally, persist default state if none exists
         await this.persistence.set(this.instanceId, this.appState);
       }
 
       // Subscribe to changes from other instances
-      this.unsubscribe = this.persistence.subscribe(this.instanceId, (newState) => {
-        console.log(`Instance ${this.instanceId}: Received global state update from another instance.`, newState);
-        // Crucial: Update your local application state based on this shared change
-        this.appState = newState;
-        this.render(); // Re-render your component/UI
-      });
+      this.unsubscribe = this.persistence.subscribe(
+        this.instanceId,
+        (newState) => {
+          console.log(
+            `Instance ${this.instanceId}: Received global state update from another instance.`,
+            newState,
+          );
+          // Crucial: Update your local application state based on this shared change
+          this.appState = newState;
+          this.render(); // Re-render your component/UI
+        },
+      );
       console.log(`Instance ${this.instanceId}: Subscribed to updates.`);
     } catch (error) {
-      console.error(`Instance ${this.instanceId}: Error during persistence initialization:`, error);
+      console.error(
+        `Instance ${this.instanceId}: Error during persistence initialization:`,
+        error,
+      );
     }
     this.render();
   }
 
   // Simulate a component render
   private render() {
-    const outputElement = document.getElementById('app-output');
+    const outputElement = document.getElementById("app-output");
     if (outputElement) {
       outputElement.innerHTML = `
         <p><strong>Instance ID:</strong> ${this.instanceId}</p>
@@ -299,8 +330,16 @@ class MyAppComponent {
   }
 
   async updateAppState(newData: string) {
-    this.appState = { ...this.appState, data: newData, count: this.appState.count + 1, lastUpdated: Date.now() };
-    console.log(`Instance ${this.instanceId}: Attempting to save new state:`, this.appState);
+    this.appState = {
+      ...this.appState,
+      data: newData,
+      count: this.appState.count + 1,
+      lastUpdated: Date.now(),
+    };
+    console.log(
+      `Instance ${this.instanceId}: Attempting to save new state:`,
+      this.appState,
+    );
     const success = await this.persistence.set(this.instanceId, this.appState);
     if (!success) {
       console.error(`Instance ${this.instanceId}: Failed to save app state.`);
@@ -317,7 +356,7 @@ class MyAppComponent {
       console.error(`Instance ${this.instanceId}: Failed to clear app state.`);
     } else {
       console.log(`Instance ${this.instanceId}: App state cleared.`);
-      this.appState = { data: 'cleared', count: 0, lastUpdated: Date.now() }; // Reset local state
+      this.appState = { data: "cleared", count: 0, lastUpdated: Date.now() }; // Reset local state
     }
     this.render();
   }
@@ -366,166 +405,206 @@ document.getElementById('close-btn')?.addEventListener('click', () => appInstanc
 
 ##### 2.2 Using `set(id, state)`
 
-*   Always pass the unique `instanceId` of your consumer when calling `set`.
-*   The `state` object you pass will generally overwrite the entire global persisted state. Ensure it contains all necessary data.
-    ```typescript
-    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
-    import { v4 as uuidv4 } from 'uuid';
-
-    interface Settings { theme: string; lastSaved: number; }
-    const myInstanceId = uuidv4();
-
-    async function saveSettings(newSettings: Settings) {
-      const config: StoreConfig<Settings> & { storageKey: string } = {
-        version: "1.0.0",
-        app: "app-settings-manager",
-        storageKey: 'app-settings'
-      };
-      const settingsStore = new WebStoragePersistence<Settings>(config);
-
-      console.log(`Instance ${myInstanceId}: Attempting to save settings.`);
-      const success = await settingsStore.set(myInstanceId, { ...newSettings, lastSaved: Date.now() });
-      if (!success) {
-        console.error(`Instance ${myInstanceId}: Failed to save settings.`);
-      } else {
-        console.log(`Instance ${myInstanceId}: Settings saved successfully.`);
-      }
-    }
+- Always pass the unique `instanceId` of your consumer when calling `set`.
+- The `state` object you pass will generally overwrite the entire global persisted state. Ensure it contains all necessary data.
 
-    // Example:
-    // saveSettings({ theme: 'dark', lastSaved: 0 });
-    ```
+  ```typescript
+  import {
+    WebStoragePersistence,
+    StoreConfig,
+  } from "@asaidimu/utils-persistence";
+  import { v4 as uuidv4 } from "uuid";
 
-##### 2.3 Using `get()`
-
-*   `get()` retrieves the *entire global, shared* persisted state. It does *not* take an `id` because it's designed to fetch the single, overarching state accessible by all instances.
-*   The returned `T | null` (or `Promise<T | null>`) should be used to initialize or update your application's local state.
-    ```typescript
-    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
+  interface Settings {
+    theme: string;
+    lastSaved: number;
+  }
+  const myInstanceId = uuidv4();
 
-    interface Settings { theme: string; lastSaved: number; }
+  async function saveSettings(newSettings: Settings) {
     const config: StoreConfig<Settings> & { storageKey: string } = {
-        version: "1.0.0",
-        app: "app-settings-manager",
-        storageKey: 'app-settings'
+      version: "1.0.0",
+      app: "app-settings-manager",
+      storageKey: "app-settings",
     };
     const settingsStore = new WebStoragePersistence<Settings>(config);
 
-    async function retrieveGlobalState() {
-      const storedState = await settingsStore.get(); // Await for async adapters if it returns a Promise
-      if (storedState) {
-        console.log("Retrieved global app settings:", storedState);
-        // Integrate storedState into your application's current state
-      } else {
-        console.log("No global app settings found in storage.");
-      }
+    console.log(`Instance ${myInstanceId}: Attempting to save settings.`);
+    const success = await settingsStore.set(myInstanceId, {
+      ...newSettings,
+      lastSaved: Date.now(),
+    });
+    if (!success) {
+      console.error(`Instance ${myInstanceId}: Failed to save settings.`);
+    } else {
+      console.log(`Instance ${myInstanceId}: Settings saved successfully.`);
     }
+  }
 
-    // Example:
-    // retrieveGlobalState();
-    ```
+  // Example:
+  // saveSettings({ theme: 'dark', lastSaved: 0 });
+  ```
+
+##### 2.3 Using `get()`
+
+- `get()` retrieves the _entire global, shared_ persisted state. It does _not_ take an `id` because it's designed to fetch the single, overarching state accessible by all instances.
+- The returned `T | null` (or `Promise<T | null>`) should be used to initialize or update your application's local state.
+
+  ```typescript
+  import {
+    WebStoragePersistence,
+    StoreConfig,
+  } from "@asaidimu/utils-persistence";
+
+  interface Settings {
+    theme: string;
+    lastSaved: number;
+  }
+  const config: StoreConfig<Settings> & { storageKey: string } = {
+    version: "1.0.0",
+    app: "app-settings-manager",
+    storageKey: "app-settings",
+  };
+  const settingsStore = new WebStoragePersistence<Settings>(config);
+
+  async function retrieveGlobalState() {
+    const storedState = await settingsStore.get(); // Await for async adapters if it returns a Promise
+    if (storedState) {
+      console.log("Retrieved global app settings:", storedState);
+      // Integrate storedState into your application's current state
+    } else {
+      console.log("No global app settings found in storage.");
+    }
+  }
+
+  // Example:
+  // retrieveGlobalState();
+  ```
 
 ##### 2.4 Using `subscribe(id, callback)`
 
-*   Pass your consumer `instanceId` as the first argument.
-*   The `callback` will be invoked when the global persisted state changes due to a `set` operation initiated by *another* consumer instance.
-*   **Always store the returned unsubscribe function** and call it when your consumer instance is no longer active (e.g., component unmounts, service shuts down) to prevent memory leaks and unnecessary processing.
+- Pass your consumer `instanceId` as the first argument.
+- The `callback` will be invoked when the global persisted state changes due to a `set` operation initiated by _another_ consumer instance.
+- **Always store the returned unsubscribe function** and call it when your consumer instance is no longer active (e.g., component unmounts, service shuts down) to prevent memory leaks and unnecessary processing.
 
-    ```typescript
-    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
-    import { v4 as uuidv4 } from 'uuid';
+  ```typescript
+  import {
+    WebStoragePersistence,
+    StoreConfig,
+  } from "@asaidimu/utils-persistence";
+  import { v4 as uuidv4 } from "uuid";
 
-    interface NotificationState { count: number; lastMessage: string; }
-    const myInstanceId = uuidv4();
+  interface NotificationState {
+    count: number;
+    lastMessage: string;
+  }
+  const myInstanceId = uuidv4();
 
-    const config: StoreConfig<NotificationState> & { storageKey: string } = {
-        version: "1.0.0",
-        app: "notification-center",
-        storageKey: 'app-notifications'
-    };
-    const notificationStore = new WebStoragePersistence<NotificationState>(config);
+  const config: StoreConfig<NotificationState> & { storageKey: string } = {
+    version: "1.0.0",
+    app: "notification-center",
+    storageKey: "app-notifications",
+  };
+  const notificationStore = new WebStoragePersistence<NotificationState>(
+    config,
+  );
+
+  const unsubscribe = notificationStore.subscribe(myInstanceId, (newState) => {
+    console.log(
+      `🔔 Instance ${myInstanceId}: Received update from another instance:`,
+      newState,
+    );
+    // Update UI or internal state based on `newState`
+  });
 
-    const unsubscribe = notificationStore.subscribe(myInstanceId, (newState) => {
-      console.log(`🔔 Instance ${myInstanceId}: Received update from another instance:`, newState);
-      // Update UI or internal state based on `newState`
-    });
+  console.log(`Instance ${myInstanceId}: Subscribed to notifications.`);
 
-    console.log(`Instance ${myInstanceId}: Subscribed to notifications.`);
-
-    // To simulate a change from another instance, open a new browser tab
-    // and run something like this (ensure it's a different instanceId):
-    /*
-    setTimeout(async () => {
-      const anotherInstanceId = uuidv4();
-      const anotherNotificationStore = new WebStoragePersistence<NotificationState>(config);
-      console.log(`Instance ${anotherInstanceId}: Sending new notification...`);
-      await anotherNotificationStore.set(anotherInstanceId, { count: 5, lastMessage: 'New notification from another tab!' });
-      console.log(`Instance ${anotherInstanceId}: Notification sent.`);
-    }, 2000);
-    */
-
-    // When no longer needed (e.g., component unmounts):
-    // setTimeout(() => {
-    //   unsubscribe();
-    //   console.log(`Instance ${myInstanceId}: Unsubscribed from notification updates.`);
-    // }, 5000);
-    ```
+  // To simulate a change from another instance, open a new browser tab
+  // and run something like this (ensure it's a different instanceId):
+  /*
+  setTimeout(async () => {
+    const anotherInstanceId = uuidv4();
+    const anotherNotificationStore = new WebStoragePersistence<NotificationState>(config);
+    console.log(`Instance ${anotherInstanceId}: Sending new notification...`);
+    await anotherNotificationStore.set(anotherInstanceId, { count: 5, lastMessage: 'New notification from another tab!' });
+    console.log(`Instance ${anotherInstanceId}: Notification sent.`);
+  }, 2000);
+  */
+
+  // When no longer needed (e.g., component unmounts):
+  // setTimeout(() => {
+  //   unsubscribe();
+  //   console.log(`Instance ${myInstanceId}: Unsubscribed from notification updates.`);
+  // }, 5000);
+  ```
 
 ##### 2.5 Using `clear()`
 
-*   `clear()` performs a global reset, completely removing the shared persisted data for *all* instances. Use with caution.
-    ```typescript
-    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
+- `clear()` performs a global reset, completely removing the shared persisted data for _all_ instances. Use with caution.
 
-    interface UserData { username: string; email: string; }
-    const config: StoreConfig<UserData> & { storageKey: string } = {
-        version: "1.0.0",
-        app: "user-profile",
-        storageKey: 'user-data'
-    };
-    const userDataStore = new WebStoragePersistence<UserData>(config);
+  ```typescript
+  import {
+    WebStoragePersistence,
+    StoreConfig,
+  } from "@asaidimu/utils-persistence";
 
-    async function resetUserData() {
-      console.log("Attempting to clear all persisted user data...");
-      const success = await userDataStore.clear(); // Await for async adapters if it returns a Promise
-      if (success) {
-        console.log("All persisted user data cleared successfully.");
-      } else {
-        console.error("Failed to clear persisted user data.");
-      }
+  interface UserData {
+    username: string;
+    email: string;
+  }
+  const config: StoreConfig<UserData> & { storageKey: string } = {
+    version: "1.0.0",
+    app: "user-profile",
+    storageKey: "user-data",
+  };
+  const userDataStore = new WebStoragePersistence<UserData>(config);
+
+  async function resetUserData() {
+    console.log("Attempting to clear all persisted user data...");
+    const success = await userDataStore.clear(); // Await for async adapters if it returns a Promise
+    if (success) {
+      console.log("All persisted user data cleared successfully.");
+    } else {
+      console.error("Failed to clear persisted user data.");
     }
+  }
 
-    // Example:
-    // resetUserData();
-    ```
+  // Example:
+  // resetUserData();
+  ```
 
 #### 3. When to Use and When to Avoid `SimplePersistence`
 
 To ensure proper use of the `SimplePersistence<T>` interface and prevent misuse, consider the following guidelines for when it is appropriate and when it should be avoided.
 
 **When to Use**
-*   **Multi-Instance Synchronization**: Ideal for applications where multiple instances (e.g., browser tabs, web workers, or independent components) need to share and synchronize a single global state, such as collaborative web apps, note-taking apps, or shared dashboards.
-*   **Interchangeable Persistence Needs**: Perfect for projects requiring flexibility to switch between storage backends (e.g., `localStorage` for prototyping, `IndexedDB` for production, `EphemeralPersistence` for transient state, or even server-based storage for scalability) without changing application logic.
-*   **Simple Global State Management**: Suitable for managing a single, shared state object (e.g., user settings, app configurations, or a shared data model) that needs to be persisted and accessed across instances.
-*   **Offline-First Applications**: Useful for apps that need to persist state locally and optionally sync with a server when online, leveraging the adapter pattern to handle different storage mechanisms.
-*   **Prototyping and Testing**: Great for quickly implementing persistence with a lightweight adapter (e.g., in-memory or `localStorage`) and later scaling to more robust solutions.
+
+- **Multi-Instance Synchronization**: Ideal for applications where multiple instances (e.g., browser tabs, web workers, or independent components) need to share and synchronize a single global state, such as collaborative web apps, note-taking apps, or shared dashboards.
+- **Interchangeable Persistence Needs**: Perfect for projects requiring flexibility to switch between storage backends (e.g., `localStorage` for prototyping, `IndexedDB` for production, `EphemeralPersistence` for transient state, or even server-based storage for scalability) without changing application logic.
+- **Simple Global State Management**: Suitable for managing a single, shared state object (e.g., user settings, app configurations, or a shared data model) that needs to be persisted and accessed across instances.
+- **Offline-First Applications**: Useful for apps that need to persist state locally and optionally sync with a server when online, leveraging the adapter pattern to handle different storage mechanisms.
+- **Prototyping and Testing**: Great for quickly implementing persistence with a lightweight adapter (e.g., in-memory or `localStorage`) and later scaling to more robust solutions.
 
 **When to Avoid**
-*   **Complex Data Relationships**: Avoid using for applications requiring complex data models with relational queries or indexing (e.g., large-scale databases with multiple tables or complex joins). The interface is designed for a single global state, not for managing multiple entities with intricate relationships. For such cases, consider using a dedicated database library (like `@asaidimu/indexed` directly) or a backend service.
-*   **High-Frequency Updates**: Not suitable for scenarios with rapid, high-frequency state changes (e.g., real-time gaming or live data streams that update hundreds of times per second), as the global state overwrite model and broadcasting mechanism may introduce performance bottlenecks.
-*   **Fine-Grained Data Access**: Do not use if you need to persist or retrieve specific parts of the state independently, as `set` and `get` operate on the entire state object, which can be inefficient for very large datasets where only small portions change.
-*   **Critical Data with Strict Consistency**: Not ideal for systems requiring strict consistency guarantees (e.g., financial transactions) across distributed clients, as the interface does not enforce ACID properties or advanced conflict resolution beyond basic Last Write Wins (LWW) semantics for ephemeral storage, or simple overwrite for others.
+
+- **Complex Data Relationships**: Avoid using for applications requiring complex data models with relational queries or indexing (e.g., large-scale databases with multiple tables or complex joins). The interface is designed for a single global state, not for managing multiple entities with intricate relationships. For such cases, consider using a dedicated database library (like `@asaidimu/indexed` directly) or a backend service.
+- **High-Frequency Updates**: Not suitable for scenarios with rapid, high-frequency state changes (e.g., real-time gaming or live data streams that update hundreds of times per second), as the global state overwrite model and broadcasting mechanism may introduce performance bottlenecks.
+- **Fine-Grained Data Access**: Do not use if you need to persist or retrieve specific parts of the state independently, as `set` and `get` operate on the entire state object, which can be inefficient for very large datasets where only small portions change.
+- **Critical Data with Strict Consistency**: Not ideal for systems requiring strict consistency guarantees (e.g., financial transactions) across distributed clients, as the interface does not enforce ACID properties or advanced conflict resolution beyond basic Last Write Wins (LWW) semantics for ephemeral storage, or simple overwrite for others.
 
 ### Web Storage Persistence (`WebStoragePersistence`)
 
 `WebStoragePersistence` uses the browser's `localStorage` (default) or `sessionStorage`. Its `set`, `get`, and `clear` operations are synchronous, meaning they return `boolean` values directly, not Promises. It supports cross-tab synchronization and data versioning with upgrade handlers.
 
 ```typescript
-import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
-import { v4 as uuidv4 } from 'uuid'; // Recommended for generating unique instance IDs
+import {
+  WebStoragePersistence,
+  StoreConfig,
+} from "@asaidimu/utils-persistence";
+import { v4 as uuidv4 } from "uuid"; // Recommended for generating unique instance IDs
 
 interface UserPreferences {
-  theme: 'dark' | 'light';
+  theme: "dark" | "light";
   notificationsEnabled: boolean;
   language: string;
 }
@@ -538,46 +617,60 @@ const instanceId = uuidv4();
 const commonConfig: StoreConfig<UserPreferences> = {
   version: "1.0.0",
   app: "user-dashboard",
-  async onUpgrade: ({ data, version, app }) => {
-    console.log(`[${app}] Migrating user preferences from version ${version} to 1.0.0.`);
+  onUpgrade: ({ data, version, app }) => {
+    console.log(
+      `[${app}] Migrating user preferences from version ${version} to 1.0.0.`,
+    );
     // Example migration: ensure language is set to default if missing
     if (data && !data.language) {
-      return { state: { ...data, language: 'en-US' }, version: "1.0.0" };
+      return { state: { ...data, language: "en-US" }, version: "1.0.0" };
     }
     // For WebStoragePersistence, if data is null during upgrade, it means no data existed.
     // We could return a default state here.
-    return { state: data || { theme: 'light', notificationsEnabled: true, language: 'en-US' }, version: "1.0.0" };
-  }
+    return {
+      state: data || {
+        theme: "light",
+        notificationsEnabled: true,
+        language: "en-US",
+      },
+      version: "1.0.0",
+    };
+  },
 };
 
 // 1. Using localStorage (default for persistent data)
 // Data stored here will persist across browser sessions.
-const localStorageConfig = { ...commonConfig, storageKey: 'user-preferences-local' };
-const userPrefsStore = new WebStoragePersistence<UserPreferences>(localStorageConfig);
+const localStorageConfig = {
+  ...commonConfig,
+  storageKey: "user-preferences-local",
+};
+const userPrefsStore = new WebStoragePersistence<UserPreferences>(
+  localStorageConfig,
+);
 
-console.log('--- localStorage Example ---');
+console.log("--- localStorage Example ---");
 
 async function manageLocalStorage() {
   // Set initial preferences
   const initialPrefs: UserPreferences = {
-    theme: 'dark',
+    theme: "dark",
     notificationsEnabled: true,
-    language: 'en-US',
+    language: "en-US",
   };
   const setResult = userPrefsStore.set(instanceId, initialPrefs);
-  console.log('Preferences set successfully:', setResult); // Expected: true
+  console.log("Preferences set successfully:", setResult); // Expected: true
 
   // Retrieve data
   let currentPrefs = userPrefsStore.get();
-  console.log('Current preferences:', currentPrefs);
+  console.log("Current preferences:", currentPrefs);
 
   // Subscribe to changes from *other* tabs/instances.
   // Open another browser tab to the same application URL to test this.
   const unsubscribePrefs = userPrefsStore.subscribe(instanceId, (newState) => {
-    console.log('🔔 Preferences updated from another instance:', newState);
+    console.log("🔔 Preferences updated from another instance:", newState);
     // In a real app, you would update your UI or state management system here.
   });
-  console.log('Subscribed to localStorage updates.');
+  console.log("Subscribed to localStorage updates.");
 
   // Simulate an update from another tab:
   // (In a different tab, generate a new instanceId and call set on the same storageKey)
@@ -587,7 +680,7 @@ async function manageLocalStorage() {
   anotherPrefsStore_ls.set(anotherInstanceId_ls, { theme: 'light', notificationsEnabled: false, language: 'es-ES' });
   */
   // You would then see the "🔔 Preferences updated from another instance:" message in the first tab.
-  await new Promise(resolve => setTimeout(resolve, 100)); // Allow event propagation
+  await new Promise((resolve) => setTimeout(resolve, 100)); // Allow event propagation
 
   // After a while, if no longer needed, unsubscribe
   // setTimeout(() => {
@@ -597,33 +690,46 @@ async function manageLocalStorage() {
 
   // Clear data when no longer needed (e.g., user logs out)
   const clearResult = userPrefsStore.clear();
-  console.log('Preferences cleared successfully:', clearResult); // Expected: true
-  console.log('Preferences after clear:', userPrefsStore.get()); // Expected: null
+  console.log("Preferences cleared successfully:", clearResult); // Expected: true
+  console.log("Preferences after clear:", userPrefsStore.get()); // Expected: null
   unsubscribePrefs(); // Unsubscribe immediately after clearing for the example
 }
 manageLocalStorage();
 
-console.log('\n--- sessionStorage Example ---');
+console.log("\n--- sessionStorage Example ---");
 
 // 2. Using sessionStorage (for session-specific data)
 // Data stored here will only persist for the duration of the browser tab.
 // It is cleared when the tab is closed.
-const sessionStorageConfig = { ...commonConfig, storageKey: 'session-data', session: true };
-const sessionDataStore = new WebStoragePersistence<{ lastVisitedPage: string } & UserPreferences>(sessionStorageConfig);
+const sessionStorageConfig = {
+  ...commonConfig,
+  storageKey: "session-data",
+  session: true,
+};
+const sessionDataStore = new WebStoragePersistence<
+  { lastVisitedPage: string } & UserPreferences
+>(sessionStorageConfig);
 
 async function manageSessionStorage() {
   const initialSessionData: { lastVisitedPage: string } & UserPreferences = {
-    ...commonConfig.onUpgrade!({ data: null, version: "0.0.0", app: "user-dashboard" }).state!, // Use migrated default
-    lastVisitedPage: '/dashboard'
+    ...commonConfig.onUpgrade!({
+      data: null,
+      version: "0.0.0",
+      app: "user-dashboard",
+    }).state!, // Use migrated default
+    lastVisitedPage: "/dashboard",
   };
   sessionDataStore.set(instanceId, initialSessionData);
-  console.log('Session data set:', sessionDataStore.get());
+  console.log("Session data set:", sessionDataStore.get());
 
   // sessionStorage also supports cross-tab synchronization via BroadcastChannel
-  const unsubscribeSession = sessionDataStore.subscribe(instanceId, (newState) => {
-    console.log('🔔 Session data updated from another instance:', newState);
-  });
-  console.log('Subscribed to sessionStorage updates.');
+  const unsubscribeSession = sessionDataStore.subscribe(
+    instanceId,
+    (newState) => {
+      console.log("🔔 Session data updated from another instance:", newState);
+    },
+  );
+  console.log("Subscribed to sessionStorage updates.");
 
   // To test session storage cross-tab, open two tabs to the same URL,
   // set a value in one tab, and the other tab's subscriber will be notified.
@@ -633,7 +739,7 @@ async function manageSessionStorage() {
   const anotherSessionDataStore_ss = new WebStoragePersistence<{ lastVisitedPage: string } & UserPreferences>(sessionStorageConfig);
   anotherSessionDataStore_ss.set(anotherInstanceId_ss, { ...initialSessionData, lastVisitedPage: '/settings', theme: 'dark' });
   */
-  await new Promise(resolve => setTimeout(resolve, 100)); // Allow event propagation
+  await new Promise((resolve) => setTimeout(resolve, 100)); // Allow event propagation
 
   // unsubscribeSession();
   // console.log('Unsubscribed from sessionStorage updates.');
@@ -647,8 +753,12 @@ manageSessionStorage();
 `IndexedDBPersistence` is designed for storing larger or more complex data structures. All its methods (`set`, `get`, `clear`, `close`) return `Promise`s because IndexedDB operations are asynchronous and non-blocking. It uses `@asaidimu/indexed` internally, which provides a higher-level, promise-based API over native IndexedDB.
 
 ```typescript
-import { IndexedDBPersistence, StoreConfig, IndexedDBPersistenceConfig } from '@asaidimu/utils-persistence';
-import { v4 as uuidv4 } from 'uuid'; // Recommended for generating unique instance IDs
+import {
+  IndexedDBPersistence,
+  StoreConfig,
+  IndexedDBPersistenceConfig,
+} from "@asaidimu/utils-persistence";
+import { v4 as uuidv4 } from "uuid"; // Recommended for generating unique instance IDs
 
 interface Product {
   id: string;
@@ -668,74 +778,109 @@ const instanceId = uuidv4();
 const indexedDBConfig: StoreConfig<Product[]> & IndexedDBPersistenceConfig = {
   version: "2.0.0", // Let's use a new version for migration example
   app: "product-catalog",
-  store: 'all-products-inventory', // Unique identifier for this piece of data/document
-  database: 'my-app-database',     // Name of the IndexedDB database
-  collection: 'app-stores',        // Name of the object store (table-like structure)
-  enableTelemetry: false,          // Optional: enable telemetry for underlying IndexedDB lib
-  async onUpgrade: ({ data, version, app }) => {
-    console.log(`[${app}] Migrating product data from version ${version} to 2.0.0.`);
+  store: "all-products-inventory", // Unique identifier for this piece of data/document
+  database: "my-app-database", // Name of the IndexedDB database
+  collection: "app-stores", // Name of the object store (table-like structure)
+  enableTelemetry: false, // Optional: enable telemetry for underlying IndexedDB lib
+  onUpgrade: ({ data, version, app }) => {
+    console.log(
+      `[${app}] Migrating product data from version ${version} to 2.0.0.`,
+    );
     if (version === "1.0.0" && data) {
       // Example migration from v1.0.0: Add 'lastUpdated' field if it doesn't exist
-      const migratedData = data.map(p => ({ ...p, lastUpdated: p.lastUpdated || Date.now() }));
+      const migratedData = data.map((p) => ({
+        ...p,
+        lastUpdated: p.lastUpdated || Date.now(),
+      }));
       return { state: migratedData, version: "2.0.0" };
     }
     // If no existing data or unknown version, return null or a sensible default
     return { state: data, version: "2.0.0" };
-  }
+  },
 };
 
 const productCache = new IndexedDBPersistence<Product[]>(indexedDBConfig);
 
 async function manageProductCache() {
-  console.log('--- IndexedDB Example ---');
+  console.log("--- IndexedDB Example ---");
 
   // Set initial product data - AWAIT the promise!
   const products: Product[] = [
-    { id: 'p001', name: 'Laptop', price: 1200, stock: 50, lastUpdated: Date.now() },
-    { id: 'p002', name: 'Mouse', price: 25, stock: 200, lastUpdated: Date.now() },
+    {
+      id: "p001",
+      name: "Laptop",
+      price: 1200,
+      stock: 50,
+      lastUpdated: Date.now(),
+    },
+    {
+      id: "p002",
+      name: "Mouse",
+      price: 25,
+      stock: 200,
+      lastUpdated: Date.now(),
+    },
   ];
   try {
     const setResult = await productCache.set(instanceId, products);
-    console.log('Products cached successfully:', setResult); // Expected: true
+    console.log("Products cached successfully:", setResult); // Expected: true
   } catch (error) {
-    console.error('Failed to set products:', error);
+    console.error("Failed to set products:", error);
   }
 
   // Get data - AWAIT the promise!
   const cachedProducts = await productCache.get();
   if (cachedProducts) {
-    console.log('Retrieved products:', cachedProducts);
+    console.log("Retrieved products:", cachedProducts);
   } else {
-    console.log('No products found in cache.');
+    console.log("No products found in cache.");
   }
 
   // Subscribe to changes from *other* tabs/instances
   const unsubscribeProducts = productCache.subscribe(instanceId, (newState) => {
-    console.log('🔔 Product cache updated by another instance:', newState);
+    console.log("🔔 Product cache updated by another instance:", newState);
     // Refresh your product list in the UI, re-fetch data, etc.
   });
-  console.log('Subscribed to IndexedDB product updates.');
+  console.log("Subscribed to IndexedDB product updates.");
 
   // Simulate an update from another instance (e.g., from a different tab)
   const updatedProducts: Product[] = [
-    { id: 'p001', name: 'Laptop Pro', price: 1150, stock: 45, lastUpdated: Date.now() }, // Price and stock updated
-    { id: 'p002', name: 'Wireless Mouse', price: 30, stock: 190, lastUpdated: Date.now() },
-    { id: 'p003', name: 'Mechanical Keyboard', price: 75, stock: 150, lastUpdated: Date.now() }, // New product
+    {
+      id: "p001",
+      name: "Laptop Pro",
+      price: 1150,
+      stock: 45,
+      lastUpdated: Date.now(),
+    }, // Price and stock updated
+    {
+      id: "p002",
+      name: "Wireless Mouse",
+      price: 30,
+      stock: 190,
+      lastUpdated: Date.now(),
+    },
+    {
+      id: "p003",
+      name: "Mechanical Keyboard",
+      price: 75,
+      stock: 150,
+      lastUpdated: Date.now(),
+    }, // New product
   ];
   try {
     // Use a *new* instanceId for simulation to trigger the subscriber in the *first* tab
     const updateResult = await productCache.set(uuidv4(), updatedProducts);
-    console.log('Simulated update from another instance:', updateResult);
+    console.log("Simulated update from another instance:", updateResult);
   } catch (error) {
-    console.error('Failed to simulate product update:', error);
+    console.error("Failed to simulate product update:", error);
   }
 
   // Give time for the event to propagate and be processed by the subscriber
-  await new Promise(resolve => setTimeout(resolve, 100)); // Short delay for async event bus
+  await new Promise((resolve) => setTimeout(resolve, 100)); // Short delay for async event bus
 
   // Verify updated data
   const updatedCachedProducts = await productCache.get();
-  console.log('Products after update:', updatedCachedProducts);
+  console.log("Products after update:", updatedCachedProducts);
 
   // After a while, if no longer needed, unsubscribe
   // setTimeout(() => {
@@ -759,7 +904,7 @@ async function manageProductCache() {
     await productCache.close(); // Closes 'my-app-database'
     console.log('IndexedDB connection for "my-app-database" closed.');
   } catch (error) {
-    console.error('Failed to close IndexedDB connection:', error);
+    console.error("Failed to close IndexedDB connection:", error);
   }
 }
 
@@ -774,8 +919,8 @@ async function manageProductCache() {
 This adapter's `set`, `get`, and `clear` operations are synchronous, returning `boolean` values or `T | null` directly.
 
 ```typescript
-import { EphemeralPersistence, StoreConfig } from '@asaidimu/utils-persistence';
-import { v4 as uuidv4 } from 'uuid';
+import { EphemeralPersistence, StoreConfig } from "@asaidimu/utils-persistence";
+import { v4 as uuidv4 } from "uuid";
 
 interface SessionData {
   activeUsers: number;
@@ -792,16 +937,27 @@ const ephemeralConfig: StoreConfig<SessionData> & { storageKey: string } = {
   version: "1.0.0",
   app: "multi-tab-session",
   storageKey: "global-session-state",
-  async onUpgrade: ({ data, version, app }) => {
-    console.log(`[${app}] Initializing/Migrating ephemeral state from version ${version}.`);
+  onUpgrade: ({ data, version, app }) => {
+    console.log(
+      `[${app}] Initializing/Migrating ephemeral state from version ${version}.`,
+    );
     // For EphemeralPersistence, onUpgrade is called with data: null initially
-    return { state: data || { activeUsers: 0, lastActivity: new Date().toISOString(), isPolling: false }, version: "1.0.0" };
-  }
+    return {
+      state: data || {
+        activeUsers: 0,
+        lastActivity: new Date().toISOString(),
+        isPolling: false,
+      },
+      version: "1.0.0",
+    };
+  },
 };
-const sessionStateStore = new EphemeralPersistence<SessionData>(ephemeralConfig);
+const sessionStateStore = new EphemeralPersistence<SessionData>(
+  ephemeralConfig,
+);
 
 async function manageSessionState() {
-  console.log('--- Ephemeral Persistence Example ---');
+  console.log("--- Ephemeral Persistence Example ---");
 
   // Set initial session data
   const initialData: SessionData = {
@@ -810,19 +966,22 @@ async function manageSessionState() {
     isPolling: true,
   };
   const setResult = sessionStateStore.set(instanceId, initialData);
-  console.log('Session state set successfully:', setResult); // Expected: true
+  console.log("Session state set successfully:", setResult); // Expected: true
 
   // Get data
   let currentSessionState = sessionStateStore.get();
-  console.log('Current session state:', currentSessionState);
+  console.log("Current session state:", currentSessionState);
 
   // Subscribe to changes from *other* tabs/instances
   // Open another browser tab to the same application URL to test this.
-  const unsubscribeSessionState = sessionStateStore.subscribe(instanceId, (newState) => {
-    console.log('🔔 Session state updated from another instance:', newState);
-    // You might update a UI counter, re-render a component, etc.
-  });
-  console.log('Subscribed to Ephemeral session state updates.');
+  const unsubscribeSessionState = sessionStateStore.subscribe(
+    instanceId,
+    (newState) => {
+      console.log("🔔 Session state updated from another instance:", newState);
+      // You might update a UI counter, re-render a component, etc.
+    },
+  );
+  console.log("Subscribed to Ephemeral session state updates.");
 
   // Simulate an update from another instance (e.g., from a different tab)
   const updatedData: SessionData = {
@@ -832,14 +991,14 @@ async function manageSessionState() {
   };
   // Use a *new* instanceId for simulation to trigger the subscriber in the *first* tab
   const updateResult = sessionStateStore.set(uuidv4(), updatedData);
-  console.log('Simulated update from another instance:', updateResult);
+  console.log("Simulated update from another instance:", updateResult);
 
   // Give time for the event to propagate and be processed by the subscriber
-  await new Promise(resolve => setTimeout(resolve, 50)); // Short delay for async event bus
+  await new Promise((resolve) => setTimeout(resolve, 50)); // Short delay for async event bus
 
   // Verify updated data locally
   const updatedCurrentSessionState = sessionStateStore.get();
-  console.log('Session state after update:', updatedCurrentSessionState);
+  console.log("Session state after update:", updatedCurrentSessionState);
 
   // After a while, if no longer needed, unsubscribe
   // setTimeout(() => {
@@ -850,8 +1009,8 @@ async function manageSessionState() {
 
   // Clear data: this will also propagate via LWW to other tabs
   const clearResult = sessionStateStore.clear();
-  console.log('Session state cleared:', clearResult); // Expected: true
-  console.log('Session state after clear:', sessionStateStore.get()); // Expected: null
+  console.log("Session state cleared:", clearResult); // Expected: true
+  console.log("Session state after clear:", sessionStateStore.get()); // Expected: null
 }
 
 // Call the async function to start the example
@@ -860,12 +1019,12 @@ async function manageSessionState() {
 
 ### Common Use Cases
 
-*   **User Preferences**: Store user settings like theme, language, or notification preferences using `WebStoragePersistence`. These are often small and need to persist across sessions.
-*   **Offline Data Caching**: Cache large datasets (e.g., product catalogs, article content, user-generated content) using `IndexedDBPersistence` to enable offline access and improve perceived performance.
-*   **Shopping Cart State**: Persist a user's shopping cart items using `WebStoragePersistence` (for simple carts with limited items) or `IndexedDBPersistence` (for more complex carts with detailed product information, images, or large quantities) to survive page refreshes or browser restarts.
-*   **Form State Preservation**: Temporarily save complex multi-step form data using `sessionStorage` (via `WebStoragePersistence`) to prevent data loss on accidental navigation or refreshes within the same browser tab session.
-*   **Cross-Tab/Instance Synchronization**: Use the `subscribe` method to build features that require real-time updates across multiple browser tabs, such as a shared todo list, live chat status indicators, synchronized media playback state, or collaborative document editing. This is particularly useful for `EphemeralPersistence` for transient, non-persistent shared state.
-*   **Feature Flags/A/B Testing**: Store user-specific feature flag assignments or A/B test group allocations in `localStorage` for consistent experiences across visits.
+- **User Preferences**: Store user settings like theme, language, or notification preferences using `WebStoragePersistence`. These are often small and need to persist across sessions.
+- **Offline Data Caching**: Cache large datasets (e.g., product catalogs, article content, user-generated content) using `IndexedDBPersistence` to enable offline access and improve perceived performance.
+- **Shopping Cart State**: Persist a user's shopping cart items using `WebStoragePersistence` (for simple carts with limited items) or `IndexedDBPersistence` (for more complex carts with detailed product information, images, or large quantities) to survive page refreshes or browser restarts.
+- **Form State Preservation**: Temporarily save complex multi-step form data using `sessionStorage` (via `WebStoragePersistence`) to prevent data loss on accidental navigation or refreshes within the same browser tab session.
+- **Cross-Tab/Instance Synchronization**: Use the `subscribe` method to build features that require real-time updates across multiple browser tabs, such as a shared todo list, live chat status indicators, synchronized media playback state, or collaborative document editing. This is particularly useful for `EphemeralPersistence` for transient, non-persistent shared state.
+- **Feature Flags/A/B Testing**: Store user-specific feature flag assignments or A/B test group allocations in `localStorage` for consistent experiences across visits.
 
 ---
 
@@ -875,38 +1034,38 @@ The `@asaidimu/utils-persistence` library is structured to be modular and extens
 
 ### Core Components
 
-*   **`SimplePersistence<T>`**: This is the fundamental TypeScript interface that defines the contract for any persistence adapter. It ensures a consistent API for `set`, `get`, `subscribe`, `clear`, and `stats` operations, regardless of the underlying storage mechanism. The `StoreConfig<T>` interface provides common configuration for versioning, application identification, and data migration.
-*   **`WebStoragePersistence<T>`**:
-    *   **Purpose**: Provides simple key-value persistence leveraging the browser's `localStorage` or `sessionStorage` APIs.
-    *   **Mechanism**: Directly interacts with `window.localStorage` or `window.sessionStorage`. Data is serialized/deserialized using `JSON.stringify` and `JSON.parse`.
-    *   **Synchronization**: Utilizes `window.addEventListener('storage', ...)` for `localStorage` (which triggers when changes occur in *other* tabs on the same origin) and the `@asaidimu/events` event bus (which uses `BroadcastChannel` internally) to ensure real-time updates across multiple browser tabs for both `localStorage` and `sessionStorage`.
-*   **`EphemeralPersistence<T>`**:
-    *   **Purpose**: Offers an in-memory store for transient data that needs cross-tab synchronization but *not* persistence across page reloads.
-    *   **Mechanism**: Stores data in a private class property. Data is cloned using `structuredClone` to prevent direct mutation issues.
-    *   **Synchronization**: Leverages the `@asaidimu/events` event bus (via `BroadcastChannel`) for cross-instance synchronization. It implements a Last Write Wins (LWW) strategy based on timestamps included in the broadcast events, ensuring all tabs converge to the most recently written state.
-*   **`IndexedDBPersistence<T>`**:
-    *   **Purpose**: Provides robust, asynchronous persistence using the browser's `IndexedDB` API, suitable for larger datasets and structured data.
-    *   **Mechanism**: Builds upon `@asaidimu/indexed` for simplified IndexedDB interactions (handling databases, object stores, and transactions) and `@asaidimu/query` for declarative data querying. Data is stored in a specific `collection` (object store) within a `database`, identified by a `store` key.
-    *   **Shared Resources**: Employs a `SharedResources` singleton pattern to manage and cache `Database` connections, `Collection` instances, and `EventBus` instances efficiently across multiple `IndexedDBPersistence` instances. This avoids redundant connections, ensures a single source of truth for IndexedDB operations, and manages global event listeners effectively.
-    *   **Synchronization**: Leverages the `@asaidimu/events` event bus (via `BroadcastChannel`) for cross-instance synchronization of IndexedDB changes, notifying other instances about updates.
-*   **`@asaidimu/events`**: An internal utility package that provides a powerful, cross-tab compatible event bus using `BroadcastChannel`. It's crucial for enabling the automatic synchronization features of all persistence adapters.
-*   **`@asaidimu/indexed` & `@asaidimu/query`**: These are internal utility packages specifically used by `IndexedDBPersistence` to abstract and simplify complex interactions with the native IndexedDB API, offering a more declarative and promise-based interface. `@asaidimu/indexed` handles database schema, versions, and CRUD operations, while `@asaidimu/query` provides a query builder for data retrieval.
+- **`SimplePersistence<T>`**: This is the fundamental TypeScript interface that defines the contract for any persistence adapter. It ensures a consistent API for `set`, `get`, `subscribe`, `clear`, and `stats` operations, regardless of the underlying storage mechanism. The `StoreConfig<T>` interface provides common configuration for versioning, application identification, and data migration.
+- **`WebStoragePersistence<T>`**:
+  - **Purpose**: Provides simple key-value persistence leveraging the browser's `localStorage` or `sessionStorage` APIs.
+  - **Mechanism**: Directly interacts with `window.localStorage` or `window.sessionStorage`. Data is serialized/deserialized using `JSON.stringify` and `JSON.parse`.
+  - **Synchronization**: Utilizes `window.addEventListener('storage', ...)` for `localStorage` (which triggers when changes occur in _other_ tabs on the same origin) and the `@asaidimu/events` event bus (which uses `BroadcastChannel` internally) to ensure real-time updates across multiple browser tabs for both `localStorage` and `sessionStorage`.
+- **`EphemeralPersistence<T>`**:
+  - **Purpose**: Offers an in-memory store for transient data that needs cross-tab synchronization but _not_ persistence across page reloads.
+  - **Mechanism**: Stores data in a private class property. Data is cloned using `structuredClone` to prevent direct mutation issues.
+  - **Synchronization**: Leverages the `@asaidimu/events` event bus (via `BroadcastChannel`) for cross-instance synchronization. It implements a Last Write Wins (LWW) strategy based on timestamps included in the broadcast events, ensuring all tabs converge to the most recently written state.
+- **`IndexedDBPersistence<T>`**:
+  - **Purpose**: Provides robust, asynchronous persistence using the browser's `IndexedDB` API, suitable for larger datasets and structured data.
+  - **Mechanism**: Builds upon `@asaidimu/indexed` for simplified IndexedDB interactions (handling databases, object stores, and transactions) and `@asaidimu/query` for declarative data querying. Data is stored in a specific `collection` (object store) within a `database`, identified by a `store` key.
+  - **Shared Resources**: Employs a `SharedResources` singleton pattern to manage and cache `Database` connections, `Collection` instances, and `EventBus` instances efficiently across multiple `IndexedDBPersistence` instances. This avoids redundant connections, ensures a single source of truth for IndexedDB operations, and manages global event listeners effectively.
+  - **Synchronization**: Leverages the `@asaidimu/events` event bus (via `BroadcastChannel`) for cross-instance synchronization of IndexedDB changes, notifying other instances about updates.
+- **`@asaidimu/events`**: An internal utility package that provides a powerful, cross-tab compatible event bus using `BroadcastChannel`. It's crucial for enabling the automatic synchronization features of all persistence adapters.
+- **`@asaidimu/indexed` & `@asaidimu/query`**: These are internal utility packages specifically used by `IndexedDBPersistence` to abstract and simplify complex interactions with the native IndexedDB API, offering a more declarative and promise-based interface. `@asaidimu/indexed` handles database schema, versions, and CRUD operations, while `@asaidimu/query` provides a query builder for data retrieval.
 
 ### Data Flow for State Changes
 
 1.  **Setting State (`set(instanceId, state)`):**
-    *   The provided `state` (of type `T`) is first serialized into a format suitable for the underlying storage (e.g., `JSON.stringify` for web storage, `structuredClone` for ephemeral, or directly as an object for IndexedDB).
-    *   It's then saved to the respective storage mechanism (`localStorage`, `sessionStorage`, in-memory, or an IndexedDB object store). For IndexedDB, existing data for the given `store` key is updated, or new data is created.
-    *   An event (of type `store:updated`) is immediately `emit`ted on an internal event bus (from `@asaidimu/events`). This event includes the `instanceId` of the updater, the `storageKey`/`store` identifying the data, and the new `state`. For `EphemeralPersistence`, a `timestamp` is also included for LWW resolution. This event is broadcast to other browser tabs via `BroadcastChannel` (managed by `@asaidimu/events`).
-    *   For `localStorage`, native `StorageEvent`s also trigger when the value is set from another tab. The `WebStoragePersistence` adapter listens for these native events and re-emits them on its internal event bus, ensuring consistent notification pathways.
+    - The provided `state` (of type `T`) is first serialized into a format suitable for the underlying storage (e.g., `JSON.stringify` for web storage, `structuredClone` for ephemeral, or directly as an object for IndexedDB).
+    - It's then saved to the respective storage mechanism (`localStorage`, `sessionStorage`, in-memory, or an IndexedDB object store). For IndexedDB, existing data for the given `store` key is updated, or new data is created.
+    - An event (of type `store:updated`) is immediately `emit`ted on an internal event bus (from `@asaidimu/events`). This event includes the `instanceId` of the updater, the `storageKey`/`store` identifying the data, and the new `state`. For `EphemeralPersistence`, a `timestamp` is also included for LWW resolution. This event is broadcast to other browser tabs via `BroadcastChannel` (managed by `@asaidimu/events`).
+    - For `localStorage`, native `StorageEvent`s also trigger when the value is set from another tab. The `WebStoragePersistence` adapter listens for these native events and re-emits them on its internal event bus, ensuring consistent notification pathways.
 2.  **Getting State (`get()`):**
-    *   The adapter retrieves the serialized data using the configured `storageKey` or `store` from the underlying storage.
-    *   It attempts to parse/deserialize the data back into the original `T` type (e.g., `JSON.parse` or direct access).
-    *   Returns the deserialized data, or `null` if the data is not found or cannot be parsed.
+    - The adapter retrieves the serialized data using the configured `storageKey` or `store` from the underlying storage.
+    - It attempts to parse/deserialize the data back into the original `T` type (e.g., `JSON.parse` or direct access).
+    - Returns the deserialized data, or `null` if the data is not found or cannot be parsed.
 3.  **Subscribing to Changes (`subscribe(instanceId, callback)`):**
-    *   A consumer instance registers a `callback` function with its unique `instanceId` to listen for `store:updated` events on the internal event bus.
-    *   When an `store:updated` event is received, the adapter checks if the `instanceId` of the event's source matches the `instanceId` of the subscribing instance.
-    *   The `callback` is invoked *only if* the `instanceId` of the update source does *not* match the `instanceId` of the subscribing instance. This crucial filtering prevents self-triggered loops (where an instance updates its own state, receives its own update notification, and attempts to re-update, leading to an infinite cycle) and ensures the `callback` is exclusively for external changes.
+    - A consumer instance registers a `callback` function with its unique `instanceId` to listen for `store:updated` events on the internal event bus.
+    - When an `store:updated` event is received, the adapter checks if the `instanceId` of the event's source matches the `instanceId` of the subscribing instance.
+    - The `callback` is invoked _only if_ the `instanceId` of the update source does _not_ match the `instanceId` of the subscribing instance. This crucial filtering prevents self-triggered loops (where an instance updates its own state, receives its own update notification, and attempts to re-update, leading to an infinite cycle) and ensures the `callback` is exclusively for external changes.
 
 ### Extension Points
 
@@ -914,9 +1073,9 @@ The library is designed with extensibility in mind. You can implement your own c
 
 For example, you could create adapters for:
 
-*   **Remote Backend API**: An adapter that persists data to a remote server endpoint via `fetch` or `XMLHttpRequest`, enabling cross-device synchronization.
-*   **Service Worker Cache API**: Leverage Service Workers for advanced caching strategies, providing highly performant offline capabilities.
-*   **Custom Local Storage**: Implement a persistence layer over a custom browser extension storage or a file system in an Electron app.
+- **Remote Backend API**: An adapter that persists data to a remote server endpoint via `fetch` or `XMLHttpRequest`, enabling cross-device synchronization.
+- **Service Worker Cache API**: Leverage Service Workers for advanced caching strategies, providing highly performant offline capabilities.
+- **Custom Local Storage**: Implement a persistence layer over a custom browser extension storage or a file system in an Electron app.
 
 ---
 
@@ -941,48 +1100,48 @@ We welcome contributions to `@asaidimu/utils-persistence`! Please follow these g
 
 The following `bun` scripts are available for development within the `src/persistence` directory (or can be run from the monorepo root if configured):
 
-*   `bun run build` (or `npm run build`): Compiles the TypeScript source files to JavaScript.
-*   `bun run test` (or `npm run test`): Runs the test suite using `vitest`.
-*   `bun run test:watch` (or `npm run test:watch`): Runs tests in watch mode, re-running on file changes.
-*   `bun run lint` (or `npm run lint`): Lints the codebase using ESLint to identify potential issues and enforce coding standards.
-*   `bun run format` (or `npm run format`): Formats the code using Prettier to ensure consistent code style.
+- `bun run build` (or `npm run build`): Compiles the TypeScript source files to JavaScript.
+- `bun run test` (or `npm run test`): Runs the test suite using `vitest`.
+- `bun run test:watch` (or `npm run test:watch`): Runs tests in watch mode, re-running on file changes.
+- `bun run lint` (or `npm run lint`): Lints the codebase using ESLint to identify potential issues and enforce coding standards.
+- `bun run format` (or `npm run format`): Formats the code using Prettier to ensure consistent code style.
 
 ### Testing
 
 Tests are crucial for maintaining the quality and stability of the library. The project uses `vitest` for testing.
 
-*   To run all tests:
-    ```bash
-    bun test
-    ```
-*   To run tests in watch mode during development:
-    ```bash
-    bun test:watch
-    ```
-*   Ensure that your changes are covered by new or existing tests, and that all tests pass before submitting a pull request. The `fixtures.ts` file provides a generic test suite (`testSimplePersistence`) for any `SimplePersistence` implementation, ensuring consistent behavior across adapters.
+- To run all tests:
+  ```bash
+  bun test
+  ```
+- To run tests in watch mode during development:
+  ```bash
+  bun test:watch
+  ```
+- Ensure that your changes are covered by new or existing tests, and that all tests pass before submitting a pull request. The `fixtures.ts` file provides a generic test suite (`testSimplePersistence`) for any `SimplePersistence` implementation, ensuring consistent behavior across adapters.
 
 ### Contributing Guidelines
 
-*   **Fork the repository** and create your branch from `main`.
-*   **Follow existing coding standards**: Adhere to the TypeScript, ESLint, and Prettier configurations defined in the project.
-*   **Commit messages**: Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for clear and consistent commit history (e.g., `feat(persistence): add new adapter`, `fix(webstorage): resolve subscription issue`, `docs(readme): update usage examples`).
-*   **Pull Requests**:
-    *   Open a pull request against the `main` branch.
-    *   Provide a clear and detailed description of your changes, including the problem solved and the approach taken.
-    *   Reference any related issues (e.g., `Closes #123`).
-    *   Ensure all tests pass and the code is lint-free before submitting.
-*   **Code Review**: Be open to feedback and suggestions during the code review process.
+- **Fork the repository** and create your branch from `main`.
+- **Follow existing coding standards**: Adhere to the TypeScript, ESLint, and Prettier configurations defined in the project.
+- **Commit messages**: Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for clear and consistent commit history (e.g., `feat(persistence): add new adapter`, `fix(webstorage): resolve subscription issue`, `docs(readme): update usage examples`).
+- **Pull Requests**:
+  - Open a pull request against the `main` branch.
+  - Provide a clear and detailed description of your changes, including the problem solved and the approach taken.
+  - Reference any related issues (e.g., `Closes #123`).
+  - Ensure all tests pass and the code is lint-free before submitting.
+- **Code Review**: Be open to feedback and suggestions during the code review process.
 
 ### Issue Reporting
 
 If you find a bug or have a feature request, please open an issue on our [GitHub Issues page](https://github.com/asaidimu/erp-utils/issues). When reporting a bug, please include:
 
-*   A clear, concise title.
-*   Steps to reproduce the issue.
-*   Expected behavior.
-*   Actual behavior.
-*   Your environment (browser version, Node.js version, `@asaidimu/utils-persistence` version).
-*   Any relevant code snippets or error messages.
+- A clear, concise title.
+- Steps to reproduce the issue.
+- Expected behavior.
+- Actual behavior.
+- Your environment (browser version, Node.js version, `@asaidimu/utils-persistence` version).
+- Any relevant code snippets or error messages.
 
 ---
 
@@ -990,36 +1149,37 @@ If you find a bug or have a feature request, please open an issue on our [GitHub
 
 ### Troubleshooting
 
-*   **Storage Limits**: Be aware that browser storage mechanisms have size limitations. `localStorage` and `sessionStorage` typically offer 5-10 MB, while `IndexedDB` can store much larger amounts (often gigabytes, depending on browser and available disk space). For large data sets, always prefer `IndexedDBPersistence`.
-*   **JSON Parsing Errors**: `WebStoragePersistence` and `IndexedDBPersistence` (for the `data` field) serialize and deserialize your data using `JSON.stringify` and `JSON.parse`. `EphemeralPersistence` uses `structuredClone`. Ensure that the `state` object you are passing to `set` is a valid JSON-serializable object (i.e., it doesn't contain circular references, functions, or Symbols that JSON cannot handle).
-*   **Cross-Origin Restrictions**: Browser storage is typically restricted to the same origin (protocol, host, port). You cannot access data stored by a different origin. Ensure your application is running on the same origin across all tabs for cross-tab synchronization to work.
-*   **`IndexedDBPersistence` Asynchronous Nature**: Remember that `IndexedDBPersistence` methods (`set`, `get`, `clear`, `close`) return `Promise`s. Always use `await` or `.then()` to handle their results and ensure operations complete before proceeding. Forgetting to `await` can lead to unexpected behavior or race conditions.
-*   **`EphemeralPersistence` Data Loss**: Data stored with `EphemeralPersistence` is *not* persisted across page reloads or browser restarts. It is strictly an in-memory solution synchronized across active tabs for the current browsing session. If you need data to survive refreshes, use `WebStoragePersistence` or `IndexedDBPersistence`.
-*   **`instanceId` Usage**: The `instanceId` parameter in `set` and `subscribe` is crucial for distinguishing between local updates and updates from other instances. Ensure each tab/instance of your application generates a *unique* ID (e.g., a UUID, like `uuidv4()`) upon startup and consistently uses it for all `set` and `subscribe` calls from that instance. This ID is *not* persisted to storage; it's ephemeral for the current session of that tab.
-*   **`subscribe` Callback Not Firing**: The most common reason for this is attempting to trigger the callback from the *same* `instanceId` that subscribed. The `subscribe` method deliberately filters out updates from the `instanceId` that subscribed to prevent infinite loops and ensure efficient state reconciliation. To test cross-instance synchronization, open two browser tabs to your application, or ensure two different logical instances are created (each with a unique `instanceId`). Perform a `set` operation in one instance using its unique `instanceId`; the `subscribe` callback in the *other* instance (with a different `instanceId`) should then fire.
-*   **Data Migration (`onUpgrade`):** When implementing `onUpgrade`, remember that the `data` parameter can be `null` if no prior state was found. Your handler should gracefully manage this, potentially returning a default state for the new version. The returned `version` in the `onUpgrade` handler *must* match the `config.version` provided to the persistence constructor.
+- **Storage Limits**: Be aware that browser storage mechanisms have size limitations. `localStorage` and `sessionStorage` typically offer 5-10 MB, while `IndexedDB` can store much larger amounts (often gigabytes, depending on browser and available disk space). For large data sets, always prefer `IndexedDBPersistence`.
+- **JSON Parsing Errors**: `WebStoragePersistence` and `IndexedDBPersistence` (for the `data` field) serialize and deserialize your data using `JSON.stringify` and `JSON.parse`. `EphemeralPersistence` uses `structuredClone`. Ensure that the `state` object you are passing to `set` is a valid JSON-serializable object (i.e., it doesn't contain circular references, functions, or Symbols that JSON cannot handle).
+- **Cross-Origin Restrictions**: Browser storage is typically restricted to the same origin (protocol, host, port). You cannot access data stored by a different origin. Ensure your application is running on the same origin across all tabs for cross-tab synchronization to work.
+- **`IndexedDBPersistence` Asynchronous Nature**: Remember that `IndexedDBPersistence` methods (`set`, `get`, `clear`, `close`) return `Promise`s. Always use `await` or `.then()` to handle their results and ensure operations complete before proceeding. Forgetting to `await` can lead to unexpected behavior or race conditions.
+- **`EphemeralPersistence` Data Loss**: Data stored with `EphemeralPersistence` is _not_ persisted across page reloads or browser restarts. It is strictly an in-memory solution synchronized across active tabs for the current browsing session. If you need data to survive refreshes, use `WebStoragePersistence` or `IndexedDBPersistence`.
+- **`instanceId` Usage**: The `instanceId` parameter in `set` and `subscribe` is crucial for distinguishing between local updates and updates from other instances. Ensure each tab/instance of your application generates a _unique_ ID (e.g., a UUID, like `uuidv4()`) upon startup and consistently uses it for all `set` and `subscribe` calls from that instance. This ID is _not_ persisted to storage; it's ephemeral for the current session of that tab.
+- **`subscribe` Callback Not Firing**: The most common reason for this is attempting to trigger the callback from the _same_ `instanceId` that subscribed. The `subscribe` method deliberately filters out updates from the `instanceId` that subscribed to prevent infinite loops and ensure efficient state reconciliation. To test cross-instance synchronization, open two browser tabs to your application, or ensure two different logical instances are created (each with a unique `instanceId`). Perform a `set` operation in one instance using its unique `instanceId`; the `subscribe` callback in the _other_ instance (with a different `instanceId`) should then fire.
+- **Data Migration (`onUpgrade`):** When implementing `onUpgrade`, remember that the `data` parameter can be `null` if no prior state was found. Your handler should gracefully manage this, potentially returning a default state for the new version. The returned `version` in the `onUpgrade` handler _must_ match the `config.version` provided to the persistence constructor.
 
 ### FAQ
 
 **Q: What's the difference between `store` (or `storageKey`) and `instanceId`?**
-A: `store` (for `IndexedDBPersistence` and `EphemeralPersistence`) or `storageKey` (for `WebStoragePersistence`) is the name or identifier of the *data set* or "document" you are persisting (e.g., `'user-profile'`, `'shopping-cart'`, `'all-products-inventory'`). It's the key under which the data itself is stored.
-`instanceId` is a unique identifier for the *browser tab, application window, or a specific component instance* currently interacting with the store. It's an ephemeral ID (e.g., a UUID generated at app startup) that helps the `subscribe` method differentiate between updates originating from the current instance versus those coming from *other* instances (tabs, windows, or distinct components) of your application, preventing self-triggered loops in your state management.
+A: `store` (for `IndexedDBPersistence` and `EphemeralPersistence`) or `storageKey` (for `WebStoragePersistence`) is the name or identifier of the _data set_ or "document" you are persisting (e.g., `'user-profile'`, `'shopping-cart'`, `'all-products-inventory'`). It's the key under which the data itself is stored.
+`instanceId` is a unique identifier for the _browser tab, application window, or a specific component instance_ currently interacting with the store. It's an ephemeral ID (e.g., a UUID generated at app startup) that helps the `subscribe` method differentiate between updates originating from the current instance versus those coming from _other_ instances (tabs, windows, or distinct components) of your application, preventing self-triggered loops in your state management.
 
 **Q: Why is `IndexedDBPersistence` asynchronous, but `WebStoragePersistence` and `EphemeralPersistence` are synchronous?**
-A: `WebStoragePersistence` utilizes `localStorage` and `sessionStorage`, which are inherently synchronous APIs in web browsers. This means operations block the main thread until they complete. Similarly, `EphemeralPersistence` is an in-memory solution, and its direct data access is synchronous. In contrast, `IndexedDB` is an asynchronous API by design to avoid blocking the main thread, which is especially important when dealing with potentially large datasets or complex queries. Our `IndexedDBPersistence` wrapper naturally exposes this asynchronous behavior through Promises to align with best practices for non-blocking operations. All three adapters use asynchronous mechanisms for *cross-tab synchronization*.
+A: `WebStoragePersistence` utilizes `localStorage` and `sessionStorage`, which are inherently synchronous APIs in web browsers. This means operations block the main thread until they complete. Similarly, `EphemeralPersistence` is an in-memory solution, and its direct data access is synchronous. In contrast, `IndexedDB` is an asynchronous API by design to avoid blocking the main thread, which is especially important when dealing with potentially large datasets or complex queries. Our `IndexedDBPersistence` wrapper naturally exposes this asynchronous behavior through Promises to align with best practices for non-blocking operations. All three adapters use asynchronous mechanisms for _cross-tab synchronization_.
 
 **Q: Can I use this library in a Node.js environment?**
 A: No, this library is specifically designed for browser environments. It relies heavily on browser-specific global APIs such as `window.localStorage`, `window.sessionStorage`, `indexedDB`, and `BroadcastChannel` (for cross-tab synchronization), none of which are available in a standard Node.js runtime.
 
 **Q: My `subscribe` callback isn't firing, even when I change data.**
-A: The most common reason for this is attempting to trigger the callback from the *same* `instanceId` that subscribed. The `subscribe` method deliberately filters out updates from the `instanceId` that subscribed to prevent infinite loops and ensure efficient state reconciliation. To test cross-instance synchronization, open two browser tabs to your application, or ensure two different logical instances are created (each with a unique `instanceId`). Perform a `set` operation in one instance using its unique `instanceId`; the `subscribe` callback in the *other* instance (with a different `instanceId`) should then fire.
+A: The most common reason for this is attempting to trigger the callback from the _same_ `instanceId` that subscribed. The `subscribe` method deliberately filters out updates from the `instanceId` that subscribed to prevent infinite loops and ensure efficient state reconciliation. To test cross-instance synchronization, open two browser tabs to your application, or ensure two different logical instances are created (each with a unique `instanceId`). Perform a `set` operation in one instance using its unique `instanceId`; the `subscribe` callback in the _other_ instance (with a different `instanceId`) should then fire.
 
 **Q: When should I choose `EphemeralPersistence` over `WebStoragePersistence` or `IndexedDBPersistence`?**
 A: Choose `EphemeralPersistence` when:
-*   You need cross-tab synchronized state that **does not need to persist across page reloads**.
-*   The data is transient and only relevant for the current browsing session.
-*   You want very fast in-memory operations.
-Use `WebStoragePersistence` for small, persistent key-value data, and `IndexedDBPersistence` for larger, structured data that needs to persist reliably.
+
+- You need cross-tab synchronized state that **does not need to persist across page reloads**.
+- The data is transient and only relevant for the current browsing session.
+- You want very fast in-memory operations.
+  Use `WebStoragePersistence` for small, persistent key-value data, and `IndexedDBPersistence` for larger, structured data that needs to persist reliably.
 
 ### Changelog
 
@@ -1033,6 +1193,6 @@ This project is licensed under the MIT License. See the [LICENSE](https://github
 
 This library leverages and builds upon the excellent work from:
 
-*   [`@asaidimu/events`](https://github.com/asaidimu/events): For robust cross-tab event communication and asynchronous event bus capabilities.
-*   [`@asaidimu/indexed`](https://github.com/asaidimu/indexed): For providing a simplified and promise-based interface for IndexedDB interactions.
-*   [`@asaidimu/query`](https://github.com/asaidimu/query): For offering a declarative query builder used internally with IndexedDB operations.
+- [`@asaidimu/events`](https://github.com/asaidimu/events): For robust cross-tab event communication and asynchronous event bus capabilities.
+- [`@asaidimu/indexed`](https://github.com/asaidimu/indexed): For providing a simplified and promise-based interface for IndexedDB interactions.
+- [`@asaidimu/query`](https://github.com/asaidimu/query): For offering a declarative query builder used internally with IndexedDB operations.