@asaidimu/utils-persistence NPM

`@asaidimu/utils-persistence`

Robust Data Persistence for Web Applications

📖 Table of Contents

✨ 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 (from @asaidimu/events) 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, Yarn, or Bun package manager
A modern web browser environment (e.g., Chrome, Firefox, Safari, Edge) that supports localStorage, sessionStorage, IndexedDB, and BroadcastChannel.

Installation Steps

Install the package using your preferred package manager:

# Using Bun
bun add @asaidimu/utils-persistence

# Using Yarn
yarn add @asaidimu/utils-persistence

# Using npm
npm install @asaidimu/utils-persistence

If you plan to use uuid for generating instanceIds as recommended in the examples, install it separately:

bun add uuid
# or
yarn add uuid
# or
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.

Verification

You can quickly verify the installation by attempting to import one of the classes:

// 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).

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>;
}

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.

Usage Guidelines (For those consuming the `SimplePersistence` interface)

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).

import { v4 as uuidv4 } from 'uuid'; // Requires 'uuid' library to be installed: `bun add 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.

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.

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 it returns a Promise
  if (storedState) {
    console.log("Retrieved global app settings:", storedState);
    // Integrate storedState into your application's current state
  } else {
    console.log("No global app settings found in storage.");
  }
}

// Example:
// retrieveGlobalState();

2.4 Using `subscribe(id, callback)`

Pass your consumer instanceId as the first argument.
The callback will be invoked when the global persisted state changes due to a set operation initiated by another consumer instance.

Always store the returned unsubscribe function and call it when your consumer instance is no longer active (e.g., component unmounts, service shuts down) to prevent memory leaks and unnecessary processing.

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 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.");

2.5 Using `clear()`

clear() performs a global reset, completely removing the shared persisted data for all instances. Use with caution.

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 it returns a Promise
  if (success) {
    console.log("All persisted user data cleared successfully.");
  } else {
    console.error("Failed to clear persisted user data.");
  }
}

// Example:
// resetUserData();

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.

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 Promises because IndexedDB operations are asynchronous and non-blocking. It uses @asaidimu/indexed internally, which provides a higher-level, promise-based API over native IndexedDB.

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.

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.

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):
- 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):
- 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):
- Purpose: Provides robust, asynchronous persistence using the browser's IndexedDB API, suitable for larger datasets and structured data.
- Mechanism: Builds upon @asaidimu/indexed for simplified IndexedDB interactions (handling databases, object stores, and transactions) and @asaidimu/query for declarative data querying. Data is stored in a specific collection (object store) within a database, identified by a store key.
- Shared Resources: Employs a SharedResources singleton pattern to manage and cache Database connections, Collection instances, and EventBus instances efficiently across multiple IndexedDBPersistence instances. This avoids redundant connections, ensures a single source of truth for IndexedDB operations, and manages global event listeners effectively.
- Synchronization: Leverages the @asaidimu/events event bus (via BroadcastChannel) for cross-instance synchronization of IndexedDB changes, notifying other instances about updates.
@asaidimu/events: An internal utility package that provides a powerful, cross-tab compatible event bus using BroadcastChannel. It's crucial for enabling the automatic synchronization features of all persistence adapters.
@asaidimu/indexed & @asaidimu/query: These are internal utility packages specifically used by IndexedDBPersistence to abstract and simplify complex interactions with the native IndexedDB API, offering a more declarative and promise-based interface. @asaidimu/indexed handles database schema, versions, and CRUD operations, while @asaidimu/query provides a query builder for data retrieval.

Data Flow for State Changes

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).
- 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 emitted 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 StorageEvents 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.
Getting State (get()):
- The adapter retrieves the serialized data using the configured storageKey or store from the underlying storage.
- It attempts to parse/deserialize the data back into the original T type (e.g., JSON.parse or direct access).
- Returns the deserialized data, or null if the data is not found or cannot be parsed.
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.
Custom Local Storage: Implement a persistence layer over a custom browser extension storage or a file system in an Electron app.

🧑‍💻 Development & Contributing

We welcome contributions to @asaidimu/utils-persistence! Please follow these guidelines to ensure a smooth collaboration.

Development Setup

Clone the Repository: This library is part of a larger monorepo.

git clone https://github.com/asaidimu/erp-utils.git # Or the actual monorepo URL
cd erp-utils # Navigate to the monorepo root

Install Dependencies: Install all monorepo dependencies.
```
bun install # or yarn install or npm install
```
This will install all necessary development dependencies, including TypeScript, Vitest, ESLint, and Prettier.

Scripts

The following npm scripts are available for development within the src/persistence directory (or can be run from the monorepo root if configured):

bun run build (or npm run build): Compiles the TypeScript source files to JavaScript.
bun run test (or npm run test): Runs the test suite using vitest.
bun run test:watch (or npm run test:watch): Runs tests in watch mode, re-running on file changes.
bun run lint (or npm run lint): Lints the codebase using ESLint to identify potential issues and enforce coding standards.
bun run format (or npm run format): Formats the code using Prettier to ensure consistent code style.

Testing

Tests are crucial for maintaining the quality and stability of the library. The project uses vitest for testing.

To run all tests:
```
bun test
```
To run tests in watch mode during development:
```
bun test:watch
```
Ensure that your changes are covered by new or existing tests, and that all tests pass before submitting a pull request. The fixtures.ts file provides a generic test suite (testSimplePersistence) for any SimplePersistence implementation, ensuring consistent behavior across adapters.

Contributing Guidelines

Fork the repository and create your branch from main.
Follow existing coding standards: Adhere to the TypeScript, ESLint, and Prettier configurations defined in the project.
Commit messages: Use Conventional Commits for clear and consistent commit history (e.g., feat(persistence): add new adapter, fix(webstorage): resolve subscription issue, docs(readme): update usage examples).
Pull Requests:
- Open a pull request against the main branch.
- Provide a clear and detailed description of your changes, including the problem solved and the approach taken.
- Reference any related issues (e.g., Closes #123).
- Ensure all tests pass and the code is lint-free before submitting.
Code Review: Be open to feedback and suggestions during the code review process.

Issue Reporting

If you find a bug or have a feature request, please open an issue on our GitHub Issues page. 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 and IndexedDBPersistence (for the data field) serialize and deserialize your data using JSON.stringify and JSON.parse. EphemeralPersistence uses structuredClone. Ensure that the state object you are passing to set is a valid JSON-serializable object (i.e., it doesn't contain circular references, functions, or Symbols that JSON cannot handle).
Cross-Origin Restrictions: Browser storage is typically restricted to the same origin (protocol, host, port). You cannot access data stored by a different origin. Ensure your application is running on the same origin across all tabs for cross-tab synchronization to work.
IndexedDBPersistence Asynchronous Nature: Remember that IndexedDBPersistence methods (set, get, clear, close) return Promises. 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 file in the project's root directory (or specific package directory).

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

This library leverages and builds upon the excellent work from:

@asaidimu/events: For robust cross-tab event communication and asynchronous event bus capabilities.
@asaidimu/indexed: For providing a simplified and promise-based interface for IndexedDB interactions.
@asaidimu/query: For offering a declarative query builder used internally with IndexedDB operations.

typescript persistence utility

@asaidimu/events @asaidimu/indexed @asaidimu/query uuid

@asaidimu/react-store @asaidimu/utils-cache @asaidimu/utils-store

5 months ago

5 months ago

5 months ago

5 months ago

5 months ago

5 months ago