@asaidimu/utils-persistence 1.0.0

package/README.md

@@ -0,0 +1,830 @@
+# `@asaidimu/utils-persistence` - 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)
+
+---
+
+## 📖 Table of Contents
+
+*   [Overview & Features](#overview--features)
+*   [Installation & Setup](#installation--setup)
+*   [Usage Documentation](#usage-documentation)
+    *   [Core Interface: `SimplePersistence`](#core-interface-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
+
+`@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.
+
+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.
+
+### 🚀 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 (for `WebStoragePersistence`, `IndexedDBPersistence`, and `EphemeralPersistence`).
+*   **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.
+
+---
+
+## 📦 Installation & Setup
+
+### Prerequisites
+
+To use `@asaidimu/utils-persistence`, you need:
+
+*   Node.js (LTS version recommended)
+*   npm or Yarn package manager
+*   A modern web browser environment (e.g., Chrome, Firefox, Safari, Edge) that supports `localStorage`, `sessionStorage`, `IndexedDB`, and `BroadcastChannel`.
+
+### Installation Steps
+
+Install the package using your preferred package manager:
+
+```bash
+# Using Yarn
+bun add @asaidimu/utils-persistence
+```
+
+### Configuration
+
+This library does not require global configuration. All settings are passed directly to the constructor of the respective persistence adapter during instantiation.
+
+### 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');
+```
+
+---
+
+## 📚 Usage Documentation
+
+The library exposes a common interface `SimplePersistence<T>` that all adapters adhere to, allowing for interchangeable persistence strategies.
+
+### Core Interface: `SimplePersistence`
+
+Every persistence adapter in this library implements the `SimplePersistence<T>` interface, where `T` is the type of data you want to persist. This interface is designed to be flexible, supporting both synchronous and asynchronous operations, and is especially geared towards handling multi-instance scenarios (e.g., multiple browser tabs or independent components sharing the same data).
+
+#### 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.
+
+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.
+
+```typescript
+export interface SimplePersistence<T> {
+  /**
+   * Persists data to storage.
+   *
+   * @param id The **unique identifier of the *consumer instance*** making the change. This is NOT the ID of the data (`T`) itself.
+   * Think of it as the ID of the specific browser tab, component, or module that's currently interacting with the persistence layer.
+   * It should typically be a **UUID** generated once at the consumer instance's instantiation.
+   * This `id` is crucial for the `subscribe` method, helping to differentiate updates originating from the current instance versus other instances/tabs, thereby preventing self-triggered notification loops.
+   * @param state The state (of type T) to persist. This state is generally considered the **global or shared state** that all instances interact with.
+   * @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations (like `IndexedDBPersistence`), this returns a `Promise<boolean>`.
+   */
+  set(id: string, state: T): boolean | Promise<boolean>;
+
+  /**
+   * Retrieves the global persisted data from storage.
+   *
+   * @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>);
+
+  /**
+   * 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).
+   *
+   * @param id The **unique identifier of the *consumer instance* subscribing**. This allows the persistence implementation to filter out notifications that were initiated by the subscribing instance itself.
+   * @param callback The function to call when the global persisted data changes from *another* source. The new state (`T`) is passed as an argument to this callback.
+   * @returns A function that, when called, will unsubscribe the provided callback from future updates. Call this when your component or instance is no longer active to prevent memory leaks.
+   */
+  subscribe(id: string, callback: (state: T) => void): () => void;
+
+  /**
+   * Clears (removes) the entire global persisted data from storage.
+   *
+   * @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations, this returns a `Promise<boolean>`.
+   */
+  clear(): boolean | Promise<boolean>;
+}
+```
+
+### Usage and Implementation Guidelines
+
+This section provides practical advice for consuming the `SimplePersistence<T>` interface.
+
+#### 1. Understanding the `id` Parameter: **Consumer Instance ID, NOT Data ID**
+
+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.
+
+**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.
+
+#### 2. Usage Guidelines (For those consuming the `SimplePersistence` interface)
+
+##### 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: `npm install uuid`
+
+    interface MyAppState {
+      data: string;
+      lastUpdated: number;
+    }
+
+    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() };
+
+      constructor(persistenceAdapter: SimplePersistence<MyAppState>) {
+        this.instanceId = uuidv4(); // Generate unique ID for this app/tab instance
+        this.persistence = persistenceAdapter;
+        this.initializePersistence();
+      }
+
+      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;
+        });
+      }
+
+      // 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.`);
+        }
+      }
+
+      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.`);
+        }
+      }
+
+      getCurrentState(): MyAppState {
+        return this.appState;
+      }
+    }
+
+    // Example of how to use:
+    // const webStore = new WebStoragePersistence<MyAppState>('my-shared-app-state');
+    // const appInstance = new MyAppComponent(webStore);
+
+    // // Simulate an update from this instance
+    // appInstance.updateAppState('New data from tab 1');
+
+    // // Simulate a cleanup (e.g., when the component unmounts)
+    // // appInstance.cleanup();
+    ```
+
+##### 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.
+    ```typescript
+    import { WebStoragePersistence } from '@asaidimu/utils-persistence';
+    import { v4 as uuidv4 } from 'uuid';
+
+    interface Settings { theme: string; }
+    const settingsStore = new WebStoragePersistence<Settings>('app-settings');
+    const myInstanceId = uuidv4();
+
+    async function saveSettings(newSettings: Settings) {
+      console.log(`Instance ${myInstanceId}: Attempting to save settings.`);
+      const success = await settingsStore.set(myInstanceId, newSettings);
+      if (!success) {
+        console.error(`Instance ${myInstanceId}: Failed to save settings.`);
+      } else {
+        console.log(`Instance ${myInstanceId}: Settings saved successfully.`);
+      }
+    }
+
+    // Example:
+    // saveSettings({ theme: 'dark' });
+    ```
+
+##### 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 } from '@asaidimu/utils-persistence';
+
+    interface Settings { theme: string; }
+    const settingsStore = new WebStoragePersistence<Settings>('app-settings');
+
+    async function retrieveGlobalState() {
+      const storedState = await settingsStore.get(); // Await for async adapters
+      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.
+
+    ```typescript
+    import { WebStoragePersistence } 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 unsubscribe = notificationStore.subscribe(myInstanceId, (newState) => {
+      console.log(`🔔 Received update from another instance:`, newState);
+      // Update UI or internal state based on `newState`
+    });
+
+    // To simulate a change from another instance, open a new browser tab
+    // and run something like:
+    // const anotherInstance = uuidv4();
+    // const anotherNotificationStore = new WebStoragePersistence<NotificationState>('app-notifications');
+    // anotherNotificationStore.set(anotherInstance, { count: 5, lastMessage: 'New notification!' });
+
+    // When no longer needed:
+    // unsubscribe();
+    // console.log("Unsubscribed from notification updates.");
+    ```
+
+##### 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';
+
+    interface UserData { username: string; }
+    const userDataStore = new WebStoragePersistence<UserData>('user-data');
+
+    async function resetUserData() {
+      console.log("Attempting to clear all persisted user data...");
+      const success = await userDataStore.clear(); // Await for async adapters
+      if (success) {
+        console.log("All persisted user data cleared successfully.");
+      } else {
+        console.error("Failed to clear persisted user data.");
+      }
+    }
+
+    // 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.
+
+**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.
+
+### 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.
+
+```typescript
+import { WebStoragePersistence } from '@asaidimu/utils-persistence';
+import { v4 as uuidv4 } from 'uuid'; // Recommended for generating unique instance IDs
+
+interface UserPreferences {
+  theme: 'dark' | 'light';
+  notificationsEnabled: boolean;
+  language: string;
+}
+
+// Generate a unique instance ID for this specific browser tab/session/component.
+// This ID is crucial for differentiating self-updates from cross-instance updates.
+const instanceId = uuidv4();
+
+// 1. Using localStorage (default for persistent data)
+// Data stored here will persist across browser sessions.
+const userPrefsStore = new WebStoragePersistence<UserPreferences>('user-preferences');
+
+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
+});
+
+// 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.
+
+// After a while, if no longer needed, unsubscribe
+// setTimeout(() => {
+//   unsubscribePrefs();
+//   console.log('Unsubscribed from 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
+
+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' }
+
+// sessionStorage also supports cross-tab synchronization via BroadcastChannel
+const unsubscribeSession = sessionDataStore.subscribe(instanceId, (newState) => {
+  console.log('🔔 Session data updated from another instance:', newState);
+});
+
+// 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();
+```
+
+### IndexedDB Persistence (`IndexedDBPersistence`)
+
+`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 { v4 as uuidv4 } from 'uuid'; // Recommended for generating unique instance IDs
+
+interface Product {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+}
+
+// Generate a unique instance ID for this specific browser tab/session/component.
+const instanceId = uuidv4();
+
+// Instantiate the IndexedDB store.
+// 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[]>({
+  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 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 },
+  ];
+  const setResult = await productCache.set(instanceId, products);
+  console.log('Products cached successfully:', setResult); // Expected: true
+
+  // 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', ... }]
+  }
+
+  // Subscribe to changes from *other* tabs/instances
+  const unsubscribeProducts = productCache.subscribe(instanceId, (newState) => {
+    console.log('🔔 Product cache updated by another instance:', newState);
+    // Refresh your product list in the UI, re-fetch data, etc.
+  });
+
+  // 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
+  ];
+  // 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);
+
+  // 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();
+  console.log('Products after update:', updatedCachedProducts);
+
+  // After a while, if no longer needed, unsubscribe
+  // setTimeout(() => {
+  //   unsubscribeProducts();
+  //   console.log('Unsubscribed from product cache updates.');
+  // }, 5000);
+
+  // Clear data - AWAIT the promise!
+  // const cleared = await productCache.clear();
+  // console.log('Products cleared:', cleared); // Expected: true
+  // console.log('Products after clear:', await productCache.get()); // Expected: null
+
+  // Important: Close the underlying IndexedDB connection when your application is shutting down
+  // 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.');
+}
+
+// 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`)
+
+`EphemeralPersistence` provides an in-memory store that **does not persist data across page reloads or application restarts**. Its primary strength lies in enabling **cross-tab synchronization** for transient, session-specific state using a Last Write Wins (LWW) strategy. This means if the same `storageKey` is used across multiple browser tabs, the latest update (based on timestamp) from any tab will propagate and overwrite the in-memory state in all other tabs.
+
+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 { v4 as uuidv4 } from 'uuid';
+
+interface SessionData {
+  activeUsers: number;
+  lastActivity: string;
+  isPolling: boolean;
+}
+
+// Generate a unique instance ID for this specific browser tab/session/component.
+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');
+
+async function manageSessionState() {
+  console.log('--- Ephemeral Persistence Example ---');
+
+  // Set initial session data
+  const initialData: SessionData = {
+    activeUsers: 1,
+    lastActivity: new Date().toISOString(),
+    isPolling: true,
+  };
+  const setResult = sessionStateStore.set(instanceId, initialData);
+  console.log('Session state set successfully:', setResult); // Expected: true
+
+  // Get data
+  let currentSessionState = sessionStateStore.get();
+  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.
+  });
+
+  // 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(),
+    isPolling: true,
+  };
+  // 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);
+
+  // 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();
+  console.log('Session state after update:', updatedCurrentSessionState);
+
+  // After a while, if no longer needed, unsubscribe
+  // setTimeout(() => {
+  //   unsubscribeSessionState();
+  //   console.log('Unsubscribed from session state updates.');
+  // }, 5000);
+
+  // 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
+}
+
+// Call the async function to start the example
+// 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.
+
+---
+
+## 🏗️ Project Architecture
+
+The `@asaidimu/utils-persistence` library is structured to be modular and extensible, adhering strictly to the `SimplePersistence` interface as its core contract. This design promotes interchangeability and ease of maintenance.
+
+### Directory Structure
+
+```
+src/persistence/
+├── index.ts              # Export entry point for all persistence modules (SimplePersistence, WebStoragePersistence, IndexedDBPersistence, EphemeralPersistence)
+├── types.ts              # Defines the SimplePersistence interface and shared types (e.g., StorageEvents)
+├── local-storage.ts      # Implements SimplePersistence using Web Storage (localStorage/sessionStorage)
+├── ephemeral.ts          # Implements SimplePersistence using an in-memory store with LWW cross-tab sync
+├── indexedb.ts           # Implements SimplePersistence using IndexedDB
+├── fixtures.ts           # Generic test suite helper for SimplePersistence implementations
+├── local-storage.test.ts # Test suite for WebStoragePersistence (assumed from local-storage.ts existence)
+├── ephemeral.test.ts     # Test suite for EphemeralPersistence
+└── indexedb.test.ts      # Comprehensive test suite for the IndexedDBPersistence adapter
+└── README.md             # This documentation file
+```
+
+### 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 `local-storage.ts`)**:
+    *   **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) 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`)**:
+    *   **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.
+    *   **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`)**:
+    *   **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.
+    *   **Shared Resources**: Employs a `SharedResources` singleton pattern to manage and cache database connections and collections efficiently across multiple instances of `IndexedDBPersistence`. This avoids redundant connections and ensures a single source of truth for IndexedDB operations within the application. It also manages a shared event bus per `database`/`store` combination.
+    *   **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.
+
+### 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 directly as an object for IndexedDB/Ephemeral).
+    *   It's then saved to the respective storage mechanism (`localStorage`, `sessionStorage`, in-memory, or an IndexedDB object store).
+    *   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. 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`).
+    *   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.
+
+### Extension Points
+
+The library is designed with extensibility in mind. You can implement your own custom persistence adapters by simply adhering to the `SimplePersistence<T>` interface. This allows you to integrate with any storage mechanism you require.
+
+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.
+
+---
+
+## 🧑‍💻 Development & Contributing
+
+We welcome contributions to `@asaidimu/utils-persistence`! Please follow these guidelines to ensure a smooth collaboration.
+
+### Development Setup
+
+1.  **Clone the Repository**: This library is likely part of a larger monorepo.
+    ```bash
+    git clone https://github.com/asaidimu/erp-utils.git # Or the actual monorepo URL
+    cd erp-utils-packages/utils-src/persistence # Adjust path as necessary
+    ```
+2.  **Install Dependencies**: Navigate to the root of the monorepo first if applicable, then install.
+    ```bash
+    npm install # or yarn install
+    ```
+    This will install all necessary development dependencies, including TypeScript, Vitest, ESLint, and Prettier.
+
+### Scripts
+
+The following `npm` scripts are available for development:
+
+*   `npm run build`: Compiles the TypeScript source files to JavaScript.
+*   `npm run test`: Runs the test suite using `vitest`.
+*   `npm run test:watch`: Runs tests in watch mode, re-running on file changes.
+*   `npm run lint`: Lints the codebase using ESLint to identify potential issues and enforce coding standards.
+*   `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
+    npm test
+    ```
+*   To run tests in watch mode during development:
+    ```bash
+    npm run 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: add new adapter`, `fix: resolve subscription issue`, `docs: update README`).
+*   **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.
+
+---
+
+## ℹ️ Additional Information
+
+### 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`, `IndexedDBPersistence` (for the `data` field), and `EphemeralPersistence` serialize and deserialize your data using `JSON.stringify` and `JSON.parse` (or `structuredClone` for `EphemeralPersistence`). 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.
+
+### 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.
+
+**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*.
+
+**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.
+
+**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.
+
+### Changelog
+
+For detailed changes between versions, please refer to the [CHANGELOG.md](CHANGELOG.md) file in the project's root directory (or specific package directory).
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+### Acknowledgments
+
+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.