@asaidimu/utils-persistence 6.1.11 → 6.1.12

package/index.d.ts

@@ -1,3 +1,4 @@
+//#region src/persistence/types.d.ts
 /**
  * configuration object for initializing a persistence store.
  *
@@ -11,215 +12,218 @@
  * @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).
-     */
+  /**
+   * 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;
-    /**
-     * 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;
+  }) => 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;
-    };
+  /**
+   * 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;
-    };
+  "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;
+  /**
+   * 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;
-    };
+  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;
+  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>;
+  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.
@@ -236,65 +240,65 @@ declare class IndexedDBPersistence<T> implements SimplePersistence<T> {
  * 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;
-    };
+  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;
+  };
 }
-
-export { EphemeralPersistence, IndexedDBPersistence, type IndexedDBPersistenceConfig, type SimplePersistence, type StorageEvents, type StoreConfig, WebStoragePersistence, type WebStoragePersistenceConfig };
+//#endregion
+export { EphemeralPersistence, IndexedDBPersistence, IndexedDBPersistenceConfig, SimplePersistence, StorageEvents, StoreConfig, WebStoragePersistence, WebStoragePersistenceConfig };