@asaidimu/utils-persistence 2.0.4 → 2.1.0

package/README.md

@@ -3,8 +3,8 @@
 **Robust Data Persistence for Web Applications**
 
 [![npm version](https://img.shields.io/npm/v/@asaidimu/utils-persistence.svg?style=flat-square)](https://www.npmjs.com/package/@asaidimu/utils-persistence)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
-[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen?style=flat-square)](https://github.com/asaidimu/erp-utils-actions)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/asaidimu/erp-utils/blob/main/LICENSE)
+[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen?style=flat-square)](https://github.com/asaidimu/erp-utils/actions)
 
 ---
 
@@ -29,7 +29,7 @@
 
 ## ✨ Overview & Features
 
-`@asaidimu/utils-persistence` is a lightweight, type-safe library designed to simplify robust data persistence in modern web applications. It provides a unified, asynchronous-friendly API for interacting with various browser storage mechanisms, including `localStorage`, `sessionStorage`, `IndexedDB`, and even an in-memory store. A core strength of this library is its built-in support for **cross-instance synchronization**, ensuring that state changes made in one browser tab, window, or even a logically separate component instance within the same tab, are automatically reflected and propagated to other active instances using the same persistence mechanism. This enables seamless, real-time data consistency across your application.
+`@asaidimu/utils-persistence` is a lightweight, type-safe TypeScript library designed to simplify robust data persistence in modern web applications. It provides a unified, asynchronous-friendly API for interacting with various browser storage mechanisms, including `localStorage`, `sessionStorage`, `IndexedDB`, and even an in-memory store. A core strength of this library is its built-in support for **cross-instance synchronization**, ensuring that state changes made in one browser tab, window, or even a logically separate component instance within the same tab, are automatically reflected and propagated to other active instances using the same persistence mechanism. This enables seamless, real-time data consistency across your application.
 
 This library is ideal for single-page applications (SPAs) that require robust state management, offline capabilities, or seamless data synchronization across multiple browser instances. By abstracting away the complexities of different storage APIs and handling synchronization, it allows developers to focus on application logic rather than intricate persistence details. It integrates smoothly with popular state management libraries or can be used standalone for direct data access.
 
@@ -41,6 +41,7 @@ This library is ideal for single-page applications (SPAs) that require robust st
     *   `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.
@@ -86,26 +87,48 @@ npm install uuid
 
 ### Configuration
 
-This library does not require global configuration. All settings are passed directly to the constructor of the respective persistence adapter during instantiation. For instance, `IndexedDBPersistence` requires a configuration object for its database and collection details.
+This library does not require global configuration. All settings are passed directly to the constructor of the respective persistence adapter during instantiation. Each adapter's constructor expects a `StoreConfig<T>` object, potentially extended with adapter-specific options (e.g., `storageKey` for `WebStoragePersistence` or `database`/`collection` for `IndexedDBPersistence`).
+
+```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;
+
+    /**
+     * 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 }
+    ) => { state: T | null; version: string };
+}
+```
 
 ### Verification
 
 You can quickly verify the installation by attempting to import one of the classes:
 
 ```typescript
-// Import in your application code (e.g., an entry point or component)
 import { WebStoragePersistence, IndexedDBPersistence, EphemeralPersistence } from '@asaidimu/utils-persistence';
 
 console.log('Persistence modules loaded successfully!');
 
 // You can now create instances:
-// const myLocalStorageStore = new WebStoragePersistence<{ appState: string }>('my-app-state');
-// const myIndexedDBStore = new IndexedDBPersistence<{ userId: string; data: any }>({
-//   store: 'user-settings',
-//   database: 'app-db',
-//   collection: 'settings'
-// });
-// const myEphemeralStore = new EphemeralPersistence<{ sessionCount: number }>('session-counter');
+// const myLocalStorageStore = new WebStoragePersistence<{ appState: string }>(/* config */);
+// const myIndexedDBStore = new IndexedDBPersistence<{ userId: string; data: any }>(/* config */);
+// const myEphemeralStore = new EphemeralPersistence<{ sessionCount: number }>(/* config */);
 ```
 
 ---
@@ -155,16 +178,28 @@ export interface SimplePersistence<T> {
    * @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations, this returns a `Promise<boolean>`.
    */
   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 };
 }
 ```
 
 ### 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.
 
@@ -187,97 +222,169 @@ It enables robust **multi-instance synchronization**. When multiple instances (e
 *   **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. Usage Guidelines (For those consuming the `SimplePersistence` interface)
+#### 2. Practical Examples for Consuming `SimplePersistence`
 
 ##### 2.1 Generating and Managing the Consumer `instanceId`
 
-*   **Generate Once:** Create 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`
+Generate a unique UUID for your consumer instance at its very beginning (e.g., when your main application component mounts or your service initializes).
 
-    interface MyAppState {
-      data: string;
-      lastUpdated: number;
-    }
+```typescript
+import { v4 as uuidv4 } from 'uuid'; // Requires 'uuid' library to be installed: `bun add uuid`
+import { SimplePersistence, WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
 
-    class MyAppComponent {
-      private instanceId: string;
-      private persistence: SimplePersistence<MyAppState>;
-      private unsubscribe: (() => void) | null = null; // To store the unsubscribe function
-      private appState: MyAppState = { data: 'initial', lastUpdated: Date.now() };
+interface MyAppState {
+  data: string;
+  count: number;
+  lastUpdated: number;
+}
 
-      constructor(persistenceAdapter: SimplePersistence<MyAppState>) {
-        this.instanceId = uuidv4(); // Generate unique ID for this app/tab instance
-        this.persistence = persistenceAdapter;
-        this.initializePersistence();
-      }
+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 async initializePersistence() {
-        // Load initial state
-        const storedState = await this.persistence.get();
-        if (storedState) {
-          console.log(`Instance ${this.instanceId}: Loaded initial state.`, storedState);
-          this.appState = storedState; // Update your app's internal state with loaded data
-        }
-
-        // 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;
-        });
-      }
+  constructor(persistenceAdapter: SimplePersistence<MyAppState>) {
+    this.instanceId = uuidv4(); // Generate unique ID for this app/tab instance
+    this.persistence = persistenceAdapter;
+    this.initializePersistence();
+  }
 
-      // Call this when the component/app instance is being destroyed or unmounted
-      cleanup() {
-        if (this.unsubscribe) {
-          this.unsubscribe(); // Stop listening to updates
-          console.log(`Instance ${this.instanceId}: Unsubscribed from updates.`);
-        }
+  private async initializePersistence() {
+    try {
+      // Load initial state
+      const storedState = await this.persistence.get();
+      if (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.`);
+        // Optionally, persist default state if none exists
+        await this.persistence.set(this.instanceId, this.appState);
       }
 
-      async updateAppState(newData: string) {
-        this.appState = { ...this.appState, data: newData, 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.`);
-        } else {
-          console.log(`Instance ${this.instanceId}: State saved successfully.`);
-        }
-      }
+      // 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
+      });
+      console.log(`Instance ${this.instanceId}: Subscribed to updates.`);
+    } catch (error) {
+      console.error(`Instance ${this.instanceId}: Error during persistence initialization:`, error);
+    }
+    this.render();
+  }
 
-      getCurrentState(): MyAppState {
-        return this.appState;
-      }
+  // Simulate a component render
+  private render() {
+    const outputElement = document.getElementById('app-output');
+    if (outputElement) {
+      outputElement.innerHTML = `
+        <p><strong>Instance ID:</strong> ${this.instanceId}</p>
+        <p><strong>App State:</strong> ${JSON.stringify(this.appState, null, 2)}</p>
+        <p><strong>Persistence Stats:</strong> ${JSON.stringify(this.persistence.stats(), null, 2)}</p>
+      `;
     }
+  }
 
-    // Example of how to use:
-    // const webStore = new WebStoragePersistence<MyAppState>('my-shared-app-state');
-    // const appInstance = new MyAppComponent(webStore);
+  // Call this when the component/app instance is being destroyed or unmounted
+  cleanup() {
+    if (this.unsubscribe) {
+      this.unsubscribe(); // Stop listening to updates
+      console.log(`Instance ${this.instanceId}: Unsubscribed from updates.`);
+      this.unsubscribe = null;
+    }
+  }
 
-    // // Simulate an update from this instance
-    // appInstance.updateAppState('New data from tab 1');
+  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);
+    const success = await this.persistence.set(this.instanceId, this.appState);
+    if (!success) {
+      console.error(`Instance ${this.instanceId}: Failed to save app state.`);
+    } else {
+      console.log(`Instance ${this.instanceId}: State saved successfully.`);
+    }
+    this.render(); // Render local changes immediately
+  }
 
-    // // Simulate a cleanup (e.g., when the component unmounts)
-    // // appInstance.cleanup();
-    ```
+  async clearAppState() {
+    console.log(`Instance ${this.instanceId}: Attempting to clear app state.`);
+    const success = await this.persistence.clear();
+    if (!success) {
+      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.render();
+  }
+}
+
+// Example of how to use this in an HTML environment:
+// Add a div with id="app-output" and some buttons to trigger actions.
+/*
+document.body.innerHTML = `
+  <div id="app-output">Loading...</div>
+  <button id="update-btn">Update State (Local)</button>
+  <button id="clear-btn">Clear State (Global)</button>
+  <button id="close-btn">Cleanup Instance</button>
+`;
+
+const config: StoreConfig<MyAppState> = {
+  version: "1.0.0",
+  app: "my-first-app",
+  onUpgrade: ({ data, version, app }) => {
+    console.log(`Migrating data for ${app} from version ${version} to 1.0.0. Current data:`, data);
+    // Simple example: if data was older, initialize count
+    return { state: data ? { ...data, count: data.count ?? 0 } : { data: 'migrated-default', count: 0, lastUpdated: Date.now() }, version: "1.0.0" };
+  }
+};
+
+const webStore = new WebStoragePersistence<MyAppState>({ ...config, storageKey: 'my-shared-app-state' });
+const appInstance = new MyAppComponent(webStore);
+
+document.getElementById('update-btn')?.addEventListener('click', () => {
+  const newData = prompt('Enter new data:', appInstance.getCurrentState().data);
+  if (newData !== null) {
+    appInstance.updateAppState(newData);
+  }
+});
+document.getElementById('clear-btn')?.addEventListener('click', () => appInstance.clearAppState());
+document.getElementById('close-btn')?.addEventListener('click', () => appInstance.cleanup());
+
+// To test cross-tab synchronization:
+// 1. Open this page in two browser tabs.
+// 2. Click "Update State (Local)" in one tab.
+// 3. Observe the "Received global state update from another instance" message in the other tab.
+// 4. Click "Clear State (Global)" in one tab.
+// 5. Observe the state clearing in both tabs.
+*/
+```
 
 ##### 2.2 Using `set(id, state)`
 
 *   Always pass the unique `instanceId` of your consumer when calling `set`.
-*   The `state` object you pass will overwrite the entire global persisted state. Ensure it contains all necessary data.
+*   The `state` object you pass will generally overwrite the entire global persisted state. Ensure it contains all necessary data.
     ```typescript
-    import { WebStoragePersistence } from '@asaidimu/utils-persistence';
+    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
     import { v4 as uuidv4 } from 'uuid';
 
-    interface Settings { theme: string; }
-    const settingsStore = new WebStoragePersistence<Settings>('app-settings');
+    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);
+      const success = await settingsStore.set(myInstanceId, { ...newSettings, lastSaved: Date.now() });
       if (!success) {
         console.error(`Instance ${myInstanceId}: Failed to save settings.`);
       } else {
@@ -286,7 +393,7 @@ It enables robust **multi-instance synchronization**. When multiple instances (e
     }
 
     // Example:
-    // saveSettings({ theme: 'dark' });
+    // saveSettings({ theme: 'dark', lastSaved: 0 });
     ```
 
 ##### 2.3 Using `get()`
@@ -294,10 +401,15 @@ It enables robust **multi-instance synchronization**. When multiple instances (e
 *   `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 } from '@asaidimu/utils-persistence';
+    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
 
-    interface Settings { theme: string; }
-    const settingsStore = new WebStoragePersistence<Settings>('app-settings');
+    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
@@ -320,37 +432,58 @@ It enables robust **multi-instance synchronization**. When multiple instances (e
 *   **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 } from '@asaidimu/utils-persistence';
+    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
     import { v4 as uuidv4 } from 'uuid';
 
     interface NotificationState { count: number; lastMessage: string; }
-    const notificationStore = new WebStoragePersistence<NotificationState>('app-notifications');
     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 unsubscribe = notificationStore.subscribe(myInstanceId, (newState) => {
-      console.log(`🔔 Received update from another instance:`, 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.`);
+
     // To simulate a change from another instance, open a new browser tab
-    // and run something like:
-    // const anotherInstanceId = uuidv4();
-    // const anotherNotificationStore = new WebStoragePersistence<NotificationState>('app-notifications');
-    // anotherNotificationStore.set(anotherInstanceId, { count: 5, lastMessage: 'New notification!' });
-
-    // When no longer needed:
-    // unsubscribe();
-    // console.log("Unsubscribed from notification updates.");
+    // 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 } from '@asaidimu/utils-persistence';
+    import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
 
-    interface UserData { username: string; }
-    const userDataStore = new WebStoragePersistence<UserData>('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...");
@@ -385,10 +518,10 @@ To ensure proper use of the `SimplePersistence<T>` interface and prevent misuse,
 
 ### 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.
+`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 } from '@asaidimu/utils-persistence';
+import { WebStoragePersistence, StoreConfig } from '@asaidimu/utils-persistence';
 import { v4 as uuidv4 } from 'uuid'; // Recommended for generating unique instance IDs
 
 interface UserPreferences {
@@ -401,72 +534,112 @@ interface UserPreferences {
 // This ID is crucial for differentiating self-updates from cross-instance updates.
 const instanceId = uuidv4();
 
+// Common Store Configuration
+const commonConfig: StoreConfig<UserPreferences> = {
+  version: "1.0.0",
+  app: "user-dashboard",
+  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" };
+    }
+    // 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" };
+  }
+};
+
 // 1. Using localStorage (default for persistent data)
 // Data stored here will persist across browser sessions.
-const userPrefsStore = new WebStoragePersistence<UserPreferences>('user-preferences');
+const localStorageConfig = { ...commonConfig, storageKey: 'user-preferences-local' };
+const userPrefsStore = new WebStoragePersistence<UserPreferences>(localStorageConfig);
 
 console.log('--- localStorage Example ---');
 
-// Set initial preferences
-const initialPrefs: UserPreferences = {
-  theme: 'dark',
-  notificationsEnabled: true,
-  language: 'en-US',
-};
-const setResult = userPrefsStore.set(instanceId, initialPrefs);
-console.log('Preferences set successfully:', setResult); // Expected: true
-
-// Retrieve data
-let currentPrefs = userPrefsStore.get();
-console.log('Current preferences:', currentPrefs);
-// Expected output: Current preferences: { theme: 'dark', notificationsEnabled: true, language: 'en-US' }
-
-// 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);
-  // In a real app, you would update your UI or state management system here.
-  // Example: update application theme based on newState.theme
-});
+async function manageLocalStorage() {
+  // Set initial preferences
+  const initialPrefs: UserPreferences = {
+    theme: 'dark',
+    notificationsEnabled: true,
+    language: 'en-US',
+  };
+  const setResult = userPrefsStore.set(instanceId, initialPrefs);
+  console.log('Preferences set successfully:', setResult); // Expected: true
 
-// To simulate an update from another tab:
-// Open a new tab, run this code (generating a *different* instanceId), and call set:
-// const anotherInstanceId = uuidv4();
-// const anotherPrefsStore = new WebStoragePersistence<UserPreferences>('user-preferences');
-// anotherPrefsStore.set(anotherInstanceId, { theme: 'light', notificationsEnabled: false, language: 'es-ES' });
-// You would then see the "🔔 Preferences updated from another instance:" message in the first tab.
+  // Retrieve data
+  let currentPrefs = userPrefsStore.get();
+  console.log('Current preferences:', currentPrefs);
 
-// After a while, if no longer needed, unsubscribe
-// setTimeout(() => {
-//   unsubscribePrefs();
-//   console.log('Unsubscribed from preferences updates.');
-// }, 5000);
+  // 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);
+    // In a real app, you would update your UI or state management system here.
+  });
+  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)
+  /*
+  const anotherInstanceId_ls = uuidv4();
+  const anotherPrefsStore_ls = new WebStoragePersistence<UserPreferences>(localStorageConfig);
+  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
 
-// 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
+  // After a while, if no longer needed, unsubscribe
+  // setTimeout(() => {
+  //   unsubscribePrefs();
+  //   console.log('Unsubscribed from localStorage preferences updates.');
+  // }, 5000);
+
+  // 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
+  unsubscribePrefs(); // Unsubscribe immediately after clearing for the example
+}
+manageLocalStorage();
 
 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 sessionDataStore = new WebStoragePersistence<{ lastVisitedPage: string }>('session-data', true); // Pass `true` for sessionStorage
-
-sessionDataStore.set(instanceId, { lastVisitedPage: '/dashboard' });
-console.log('Session data set:', sessionDataStore.get());
-// Expected output: Session data set: { lastVisitedPage: '/dashboard' }
+const sessionStorageConfig = { ...commonConfig, storageKey: 'session-data', session: true };
+const sessionDataStore = new WebStoragePersistence<{ lastVisitedPage: string } & UserPreferences>(sessionStorageConfig);
 
-// sessionStorage also supports cross-tab synchronization via BroadcastChannel
-const unsubscribeSession = sessionDataStore.subscribe(instanceId, (newState) => {
-  console.log('🔔 Session data updated from another instance:', newState);
-});
+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'
+  };
+  sessionDataStore.set(instanceId, initialSessionData);
+  console.log('Session data set:', sessionDataStore.get());
 
-// 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.
-// Note: If you close and reopen the tab, sessionStorage is cleared.
-// unsubscribeSession();
+  // 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.');
+
+  // 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.
+  // Note: If you close and reopen the tab, sessionStorage is cleared.
+  /*
+  const anotherInstanceId_ss = uuidv4();
+  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
+
+  // unsubscribeSession();
+  // console.log('Unsubscribed from sessionStorage updates.');
+  unsubscribeSession(); // Unsubscribe for example cleanup
+}
+manageSessionStorage();
 ```
 
 ### IndexedDB Persistence (`IndexedDBPersistence`)
@@ -474,7 +647,7 @@ const unsubscribeSession = sessionDataStore.subscribe(instanceId, (newState) =>
 `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 } from '@asaidimu/utils-persistence';
+import { IndexedDBPersistence, StoreConfig, IndexedDBPersistenceConfig } from '@asaidimu/utils-persistence';
 import { v4 as uuidv4 } from 'uuid'; // Recommended for generating unique instance IDs
 
 interface Product {
@@ -482,6 +655,7 @@ interface Product {
   name: string;
   price: number;
   stock: number;
+  lastUpdated: number;
 }
 
 // Generate a unique instance ID for this specific browser tab/session/component.
@@ -491,29 +665,48 @@ const instanceId = uuidv4();
 // A 'store' identifies the specific document/state within the database/collection.
 // The 'database' is the IndexedDB database name.
 // The 'collection' is the object store name within that database.
-const productCache = new IndexedDBPersistence<Product[]>({
+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
-});
+  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() }));
+      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 ---');
 
   // Set initial product data - AWAIT the promise!
   const products: Product[] = [
-    { id: 'p001', name: 'Laptop', price: 1200, stock: 50 },
-    { id: 'p002', name: 'Mouse', price: 25, stock: 200 },
+    { id: 'p001', name: 'Laptop', price: 1200, stock: 50, lastUpdated: Date.now() },
+    { id: 'p002', name: 'Mouse', price: 25, stock: 200, lastUpdated: Date.now() },
   ];
-  const setResult = await productCache.set(instanceId, products);
-  console.log('Products cached successfully:', setResult); // Expected: true
+  try {
+    const setResult = await productCache.set(instanceId, products);
+    console.log('Products cached successfully:', setResult); // Expected: true
+  } catch (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);
-    // Expected output: Retrieved products: [{ id: 'p001', ... }, { id: 'p002', ... }]
+  } else {
+    console.log('No products found in cache.');
   }
 
   // Subscribe to changes from *other* tabs/instances
@@ -521,21 +714,24 @@ async function manageProductCache() {
     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.');
 
   // Simulate an update from another instance (e.g., from a different tab)
-  // In a real scenario, another tab would call `productCache.set` with a different instanceId
   const updatedProducts: Product[] = [
-    { id: 'p001', name: 'Laptop', price: 1150, stock: 45 }, // Price and stock updated
-    { id: 'p002', name: 'Mouse', price: 25, stock: 190 },
-    { id: 'p003', name: 'Keyboard', price: 75, stock: 150 }, // 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
   ];
-  // 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);
+  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);
+  } catch (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
-  // You would see "🔔 Product cache updated by another instance:" followed by the updatedProducts
 
   // Verify updated data
   const updatedCachedProducts = await productCache.get();
@@ -546,6 +742,7 @@ async function manageProductCache() {
   //   unsubscribeProducts();
   //   console.log('Unsubscribed from product cache updates.');
   // }, 5000);
+  unsubscribeProducts(); // Unsubscribe for example cleanup
 
   // Clear data - AWAIT the promise!
   // const cleared = await productCache.clear();
@@ -556,24 +753,18 @@ async function manageProductCache() {
   // or when no more IndexedDB operations are expected across all instances of IndexedDBPersistence.
   // This is a static method that closes shared database connections managed by the library.
   // This is generally called once when the application (or a specific database usage) fully shuts down.
-  // await IndexedDBPersistence.closeAll();
-  // console.log('All IndexedDB connections closed.');
+  // await IndexedDBPersistence.closeAll(); // If SharedResources was exposed publicly.
+  // Instead, use the instance's close() method if you want to close that specific database.
+  try {
+    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);
+  }
 }
 
 // Call the async function to start the example
 // manageProductCache();
-
-// You can also close a specific database connection if you have multiple:
-// async function closeSpecificDb() {
-//   const specificDbPersistence = new IndexedDBPersistence<any>({
-//     store: 'another-store',
-//     database: 'another-database',
-//     collection: 'data'
-//   });
-//   await specificDbPersistence.close(); // Closes 'another-database'
-//   console.log('Specific IndexedDB connection closed.');
-// }
-// closeSpecificDb();
 ```
 
 ### Ephemeral Persistence (`EphemeralPersistence`)
@@ -583,7 +774,7 @@ async function manageProductCache() {
 This adapter's `set`, `get`, and `clear` operations are synchronous, returning `boolean` values or `T | null` directly.
 
 ```typescript
-import { EphemeralPersistence } from '@asaidimu/utils-persistence';
+import { EphemeralPersistence, StoreConfig } from '@asaidimu/utils-persistence';
 import { v4 as uuidv4 } from 'uuid';
 
 interface SessionData {
@@ -597,7 +788,17 @@ const instanceId = uuidv4();
 
 // Instantiate the Ephemeral store.
 // The 'storageKey' is a logical key for this specific piece of in-memory data.
-const sessionStateStore = new EphemeralPersistence<SessionData>('global-session-state');
+const ephemeralConfig: StoreConfig<SessionData> & { storageKey: string } = {
+  version: "1.0.0",
+  app: "multi-tab-session",
+  storageKey: "global-session-state",
+  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" };
+  }
+};
+const sessionStateStore = new EphemeralPersistence<SessionData>(ephemeralConfig);
 
 async function manageSessionState() {
   console.log('--- Ephemeral Persistence Example ---');
@@ -621,9 +822,9 @@ async function manageSessionState() {
     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)
-  // In a real scenario, another tab would call `sessionStateStore.set` with a different instanceId
   const updatedData: SessionData = {
     activeUsers: 2, // User joined in another tab
     lastActivity: new Date().toISOString(),
@@ -635,7 +836,6 @@ async function manageSessionState() {
 
   // 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
-  // You would see "🔔 Session state updated from another instance:" followed by the updatedData
 
   // Verify updated data locally
   const updatedCurrentSessionState = sessionStateStore.get();
@@ -646,11 +846,12 @@ async function manageSessionState() {
   //   unsubscribeSessionState();
   //   console.log('Unsubscribed from session state updates.');
   // }, 5000);
+  unsubscribeSessionState(); // Unsubscribe for example cleanup
 
   // 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
+  const clearResult = sessionStateStore.clear();
+  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
@@ -674,16 +875,16 @@ The `@asaidimu/utils-persistence` library is structured to be modular and extens
 
 ### Core Components
 
-*   **`SimplePersistence<T>` (in `types.ts`)**: This is the fundamental TypeScript interface that defines the contract for any persistence adapter. It ensures a consistent API for `set`, `get`, `subscribe`, and `clear` operations, regardless of the underlying storage mechanism.
-*   **`WebStoragePersistence<T>` (in `webstorage.ts`)**:
+*   **`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>` (in `ephemeral.ts`)**:
+*   **`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>` (in `indexedb.ts`)**:
+*   **`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.
@@ -694,7 +895,7 @@ The `@asaidimu/utils-persistence` library is structured to be modular and extens
 ### 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, or `structuredClone` for ephemeral, or directly as an object for IndexedDB).
+    *   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.
@@ -738,7 +939,7 @@ We welcome contributions to `@asaidimu/utils-persistence`! Please follow these g
 
 ### Scripts
 
-The following `npm` scripts are available for development within the `src/persistence` directory (or can be run from the monorepo root if configured):
+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`.
@@ -796,6 +997,7 @@ If you find a bug or have a feature request, please open an issue on our [GitHub
 *   **`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
 
@@ -833,4 +1035,4 @@ 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/query`](https://github.com/asaidimu/query): For offering a declarative query builder used internally with IndexedDB operations.