@asaidimu/utils-persistence 2.0.0 → 2.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.mts

@@ -0,0 +1,82 @@
+import { S as SimplePersistence } from '../types-D26luDbE.js';
+export { a as StorageEvents } from '../types-D26luDbE.js';
+
+/**
+ * Implements SimplePersistence using web storage (localStorage or sessionStorage).
+ * Supports cross-tab synchronization via an event bus and native storage events when using localStorage.
+ */
+declare class WebStoragePersistence<T extends object> implements SimplePersistence<T> {
+    private readonly storageKey;
+    private readonly eventBus;
+    private readonly storage;
+    /**
+     * Initializes a new instance of WebStoragePersistence.
+     * @param storageKey The key under which data is stored in web storage (e.g., 'user-profile').
+     * @param session Optional flag; if true, uses sessionStorage instead of localStorage (default: false).
+     */
+    constructor(storageKey: string, session?: boolean);
+    /**
+     * Initializes the event bus with configured settings.
+     * @returns Configured event bus instance.
+     */
+    private initializeEventBus;
+    /**
+     * Sets up a listener for native storage events to synchronize across tabs (localStorage only).
+     */
+    private setupStorageEventListener;
+    /**
+     * Persists the provided state to web storage and notifies subscribers.
+     * @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 state from web storage.
+     * @returns The persisted state, or null if not found or invalid.
+     */
+    get(): T | null;
+    /**
+     * Subscribes to updates in the persisted state, excluding the instance’s own changes.
+     * @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;
+    /**
+     * Removes the persisted state from web storage.
+     * @returns True if successful, false if an error occurs.
+     */
+    clear(): boolean;
+}
+
+/**
+ * Configuration for database connections
+ */
+interface DatabaseConfig {
+    store: string;
+    database: string;
+    collection: string;
+    enableTelemetry?: boolean;
+}
+/**
+ * IndexedDB persistence adapter with configurable database support
+ */
+declare class IndexedDBPersistence<T> implements SimplePersistence<T> {
+    private collection;
+    private collectionPromise;
+    private config;
+    private eventBus;
+    constructor(config: DatabaseConfig);
+    private getCollection;
+    set(id: string, state: T): Promise<boolean>;
+    get(): Promise<T | null>;
+    subscribe(id: string, callback: (state: T) => void): () => void;
+    clear(): Promise<boolean>;
+    /**
+     * Close a specific database
+     */
+    close(): Promise<void>;
+}
+
+export { IndexedDBPersistence, SimplePersistence, WebStoragePersistence };

package/index.d.ts

@@ -0,0 +1,82 @@
+import { S as SimplePersistence } from '../types-D26luDbE.js';
+export { a as StorageEvents } from '../types-D26luDbE.js';
+
+/**
+ * Implements SimplePersistence using web storage (localStorage or sessionStorage).
+ * Supports cross-tab synchronization via an event bus and native storage events when using localStorage.
+ */
+declare class WebStoragePersistence<T extends object> implements SimplePersistence<T> {
+    private readonly storageKey;
+    private readonly eventBus;
+    private readonly storage;
+    /**
+     * Initializes a new instance of WebStoragePersistence.
+     * @param storageKey The key under which data is stored in web storage (e.g., 'user-profile').
+     * @param session Optional flag; if true, uses sessionStorage instead of localStorage (default: false).
+     */
+    constructor(storageKey: string, session?: boolean);
+    /**
+     * Initializes the event bus with configured settings.
+     * @returns Configured event bus instance.
+     */
+    private initializeEventBus;
+    /**
+     * Sets up a listener for native storage events to synchronize across tabs (localStorage only).
+     */
+    private setupStorageEventListener;
+    /**
+     * Persists the provided state to web storage and notifies subscribers.
+     * @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 state from web storage.
+     * @returns The persisted state, or null if not found or invalid.
+     */
+    get(): T | null;
+    /**
+     * Subscribes to updates in the persisted state, excluding the instance’s own changes.
+     * @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;
+    /**
+     * Removes the persisted state from web storage.
+     * @returns True if successful, false if an error occurs.
+     */
+    clear(): boolean;
+}
+
+/**
+ * Configuration for database connections
+ */
+interface DatabaseConfig {
+    store: string;
+    database: string;
+    collection: string;
+    enableTelemetry?: boolean;
+}
+/**
+ * IndexedDB persistence adapter with configurable database support
+ */
+declare class IndexedDBPersistence<T> implements SimplePersistence<T> {
+    private collection;
+    private collectionPromise;
+    private config;
+    private eventBus;
+    constructor(config: DatabaseConfig);
+    private getCollection;
+    set(id: string, state: T): Promise<boolean>;
+    get(): Promise<T | null>;
+    subscribe(id: string, callback: (state: T) => void): () => void;
+    clear(): Promise<boolean>;
+    /**
+     * Close a specific database
+     */
+    close(): Promise<void>;
+}
+
+export { IndexedDBPersistence, SimplePersistence, WebStoragePersistence };