@asaidimu/utils-persistence 6.1.11 → 6.1.13

package/index.d.cts

@@ -0,0 +1,304 @@
+//#region src/persistence/types.d.ts
+/**
+ * configuration object for initializing a persistence store.
+ *
+ * this configuration allows you to:
+ * - define the **schema/application version** of the data being persisted.
+ * - distinguish between multiple **applications** that may run on the same host
+ *   (so they don’t overwrite each other’s storage).
+ * - optionally provide an **upgrade handler** to migrate persisted data when
+ *   the version changes.
+ *
+ * @template T the type of data being persisted.
+ */
+interface StoreConfig<T> {
+  /**
+   * the semantic version string (e.g., "1.0.0") of the data schema or application.
+   *
+   * this is used for version control and data migrations.
+   * when the persisted state’s version does not match the current version,
+   * the `onUpgrade` function will be invoked (if provided).
+   */
+  version: string;
+  /**
+   * a unique application identifier (e.g., "chat-app" or "my-dashboard").
+   *
+   * this prevents collisions between different apps or modules
+   * that might share the same persistence backend (e.g., localstorage).
+   *
+   * example: if two apps both persist under the key "user", the `app`
+   * value ensures they can be distinguished.
+   */
+  app: string;
+  /**
+   * optional handler for upgrading persisted state across versions.
+   *
+   * this function will be called when the persisted state’s `version`
+   * does not match the `version` specified in this config.
+   *
+   * @param state the existing state object, including:
+   *  - `data`: the current persisted data (or null if none exists).
+   *  - `version`: the version string stored with the data.
+   *  - `app`: the application identifier stored with the data.
+   *
+   * @returns a new state object with:
+   *  - `state`: the migrated data (or null if clearing/resetting).
+   *  - `version`: the new version string (must match `config.version`).
+   *
+   * example:
+   * ```ts
+   * onupgrade: async ({ data, version, app }) => {
+   *   if (version === "1.0.0") {
+   *     // migrate from 1.0.0 to 2.0.0
+   *     return { state: { ...data, newfield: "default" }, version: "2.0.0" };
+   *   }
+   *   return { state: data, version: "2.0.0" };
+   * }
+   * ```
+   */
+  onUpgrade?: (state: {
+    data: T | null;
+    version: string;
+    app: string;
+  }) => Promise<{
+    state: T | null;
+    version: string;
+  }>;
+  /**
+   * enables or disables developer mode for the persistence store.
+   *
+   * when set to `true`, the store may provide additional logging,
+   * verbose error reporting, or bypass certain production constraints
+   * (such as strict cache validation) to aid in debugging.
+   *
+   * @default false
+   */
+  dev?: boolean;
+}
+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>;
+  /**
+   * Returns metadata about the persistence layer.
+   *
+   * This is useful for distinguishing between multiple apps running on the same host
+   * (e.g., several apps served at `localhost:3000` that share the same storage key).
+   *
+   * @returns An object containing:
+   * - `version`: The semantic version string of the persistence schema or application.
+   * - `id`: A unique identifier for the application using this persistence instance.
+   */
+  stats(): {
+    version: string;
+    id: string;
+  };
+}
+interface StorageEvents {
+  "store:updated": {
+    storageKey: string;
+    instanceId: string;
+    state: any;
+    timestamp?: number;
+    version: string;
+    app: string;
+  };
+}
+//#endregion
+//#region src/persistence/webstorage.d.ts
+/**
+ * Configuration options specific to the WebStoragePersistence adapter.
+ */
+interface WebStoragePersistenceConfig {
+  /**
+   * The key under which data is stored in web storage (e.g., 'user-profile').
+   */
+  storageKey: string;
+  /**
+   * If true, uses sessionStorage instead of localStorage. Defaults to false.
+   */
+  session?: boolean;
+}
+/**
+ * Implements SimplePersistence using web storage (localStorage or sessionStorage).
+ * Supports cross-tab synchronization and data versioning with upgrade handlers.
+ */
+declare class WebStoragePersistence<T> implements SimplePersistence<T> {
+  private readonly eventBus;
+  private readonly storage;
+  private readonly config;
+  private initialized;
+  private initializationCallbacks;
+  constructor(config: StoreConfig<T> & WebStoragePersistenceConfig);
+  private initialize;
+  private _onInitialized;
+  private initializeEventBus;
+  private getStoreName;
+  private setupStorageEventListener;
+  set(instanceId: string, state: T): boolean;
+  private _get;
+  get(): Promise<T | null>;
+  subscribe(instanceId: string, onStateChange: (state: T) => void): () => void;
+  clear(): boolean;
+  stats(): {
+    version: string;
+    id: string;
+  };
+}
+//#endregion
+//#region src/persistence/indexedb.d.ts
+interface IndexedDBPersistenceConfig {
+  store: string;
+  database: string;
+  collection: string;
+  enableTelemetry?: boolean;
+}
+declare class IndexedDBPersistence<T> implements SimplePersistence<T> {
+  private collection;
+  private collectionPromise;
+  private config;
+  private eventBus;
+  private initialized;
+  private _initializing;
+  private initializationCallbacks;
+  private doc;
+  private getStoreName;
+  constructor(config: StoreConfig<T> & IndexedDBPersistenceConfig);
+  private initialize;
+  private _onInitialized;
+  private getCollection;
+  /**
+   * Writes state.  Waits for initialisation (migration) to complete first.
+   */
+  set(id: string, state: T): Promise<boolean>;
+  private _read;
+  /**
+   * Returns the stored document data (after ensuring it has been
+   * fully read from the underlying store).  The `document.read()`
+   * call populates internal state and we then return the document
+   * itself which has all fields available.
+   */
+  private _get;
+  get(): Promise<T | null>;
+  subscribe(id: string, callback: (state: T) => void): () => void;
+  clear(): Promise<boolean>;
+  stats(): {
+    version: string;
+    id: string;
+  };
+  /**
+   * Closes this persistence instance, releasing our reference on the
+   * shared database.  The actual database connection is closed only
+   * when every active store has been released.
+   */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/persistence/ephemeral.d.ts
+/**
+ * Implements SimplePersistence using an in-memory store.
+ * Data is NOT persisted across page loads or application restarts.
+ *
+ * Synchronization: This class fully synchronizes its in-memory state across
+ * different browser tabs using an event bus with a Last Write Wins (LWW) strategy.
+ * When a state is set or cleared in one tab, the latest version (based on timestamp)
+ * will propagate to and update the in-memory state of all other tabs.
+ *
+ * IMPORTANT: While the in-memory state is synchronized *across tabs*, it remains
+ * ephemeral within each tab. Closing all tabs will result in data loss.
+ *
+ * Note: The best use case for this class is in tests where intergration with a
+ * SimplePersistence is required.
+ */
+declare class EphemeralPersistence<T> implements SimplePersistence<T> {
+  private readonly eventBus;
+  private inMemoryState;
+  private readonly config;
+  /**
+   * Initializes a new instance of EphemeralPersistence.
+   * @param config Configuration object for the persistence adapter.
+   */
+  constructor(config: StoreConfig<T> & {
+    storageKey: string;
+  });
+  /**
+   * Initializes the event bus with configured settings for cross-tab communication.
+   * @returns Configured event bus instance.
+   */
+  private initializeEventBus;
+  /**
+   * Sets up an internal listener to synchronize the in-memory state
+   * using the Last Write Wins (LWW) strategy.
+   */
+  private setupLwwSynchronizationListener;
+  /**
+   * Persists the provided state to in-memory storage and notifies all subscribers
+   * across tabs. The state is synchronized using LWW.
+   * @param instanceId Unique identifier of the instance making the update.
+   * @param state The state to persist.
+   * @returns True if successful, false if an error occurs.
+   */
+  set(instanceId: string, state: T): boolean;
+  /**
+   * Retrieves the current synchronized state from in-memory storage.
+   * @returns The synchronized state, or null if not set or if cleared.
+   */
+  get(): T | null;
+  /**
+   * Subscribes to updates in the in-memory state.
+   * The callback is invoked when the state is updated by any instance
+   * (including other tabs) *excluding the subscribing instance's own 'set' or 'clear' calls*.
+   * @param instanceId Unique identifier of the subscribing instance.
+   * @param onStateChange Callback to invoke with the updated state.
+   * @returns Function to unsubscribe from updates.
+   */
+  subscribe(instanceId: string, onStateChange: (state: T) => void): () => void;
+  /**
+   * Clears the in-memory state of this instance and synchronizes this clear
+   * across all tabs using the LWW strategy.
+   * @returns True if successful, false if an error occurs.
+   */
+  clear(): boolean;
+  /**
+   * Returns metadata about the persistence layer.
+   *
+   * @returns An object containing:
+   * - `version`: The semantic version string of the persistence schema or application.
+   * - `id`: A unique identifier for the application using this persistence instance.
+   */
+  stats(): {
+    version: string;
+    id: string;
+  };
+}
+//#endregion
+export { EphemeralPersistence, IndexedDBPersistence, IndexedDBPersistenceConfig, SimplePersistence, StorageEvents, StoreConfig, WebStoragePersistence, WebStoragePersistenceConfig };