@asaidimu/utils-remote-store 1.2.9 → 1.3.1

package/index.d.mts

@@ -1,51 +1,4 @@
-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;
-    };
-}
+import { SimplePersistence } from '@core/persistence';
 
 interface CacheOptions {
     staleTime?: number;
@@ -85,51 +38,51 @@ type CacheEventBase<Type extends string, Payload = {}> = {
     key: string;
     timestamp: number;
 } & Payload;
-type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
+type CacheReadHitEvent<T = any> = CacheEventBase<"cache:read:hit", {
     data: T;
     isStale: boolean;
 }>;
-type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
-type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
+type CacheReadMissEvent = CacheEventBase<"cache:read:miss">;
+type CacheFetchStartEvent = CacheEventBase<"cache:fetch:start", {
     attempt: number;
 }>;
-type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<"cache:fetch:success", {
     data: T;
 }>;
-type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
+type CacheFetchErrorEvent = CacheEventBase<"cache:fetch:error", {
     error: Error;
     attempt: number;
 }>;
-type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
+type CacheDataEvictEvent = CacheEventBase<"cache:data:evict", {
     reason?: string;
 }>;
-type CacheDataInvalidateEvent = CacheEventBase<'cache:data:invalidate'>;
-type CacheDataSetEvent<T = any> = CacheEventBase<'cache:data:set', {
+type CacheDataInvalidateEvent = CacheEventBase<"cache:data:invalidate">;
+type CacheDataSetEvent<T = any> = CacheEventBase<"cache:data:set", {
     newData: T;
     oldData?: T;
 }>;
-type CachePersistenceLoadSuccessEvent = CacheEventBase<'cache:persistence:load:success', {
+type CachePersistenceLoadSuccessEvent = CacheEventBase<"cache:persistence:load:success", {
     message?: string;
 }>;
-type CachePersistenceLoadErrorEvent = CacheEventBase<'cache:persistence:load:error', {
+type CachePersistenceLoadErrorEvent = CacheEventBase<"cache:persistence:load:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSaveSuccessEvent = CacheEventBase<'cache:persistence:save:success'>;
-type CachePersistenceSaveErrorEvent = CacheEventBase<'cache:persistence:save:error', {
+type CachePersistenceSaveSuccessEvent = CacheEventBase<"cache:persistence:save:success">;
+type CachePersistenceSaveErrorEvent = CacheEventBase<"cache:persistence:save:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceClearSuccessEvent = CacheEventBase<'cache:persistence:clear:success'>;
-type CachePersistenceClearErrorEvent = CacheEventBase<'cache:persistence:clear:error', {
+type CachePersistenceClearSuccessEvent = CacheEventBase<"cache:persistence:clear:success">;
+type CachePersistenceClearErrorEvent = CacheEventBase<"cache:persistence:clear:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSyncEvent = CacheEventBase<'cache:persistence:sync', {
+type CachePersistenceSyncEvent = CacheEventBase<"cache:persistence:sync", {
     message?: string;
 }>;
 type CacheEvent = CacheReadHitEvent | CacheReadMissEvent | CacheFetchStartEvent | CacheFetchSuccessEvent | CacheFetchErrorEvent | CacheDataEvictEvent | CacheDataInvalidateEvent | CacheDataSetEvent | CachePersistenceLoadSuccessEvent | CachePersistenceLoadErrorEvent | CachePersistenceSaveSuccessEvent | CachePersistenceSaveErrorEvent | CachePersistenceClearSuccessEvent | CachePersistenceClearErrorEvent | CachePersistenceSyncEvent;
-type CacheEventType = CacheEvent['type'];
+type CacheEventType = CacheEvent["type"];
 
 declare class QueryCache {
     private cache;
@@ -233,7 +186,7 @@ interface StoreEvent {
 /**
  * Defines the types of mutation operations that can occur.
  */
-type MutationOperation = 'create' | 'update' | 'delete' | 'upload';
+type MutationOperation = "create" | "update" | "delete" | "upload";
 /**
  * A correlator function that determines which active queries should be invalidated
  * based on a mutation operation.
@@ -342,7 +295,7 @@ interface BaseStore<T extends StoreRecord, TFindOptions = Record<string, unknown
         /** A function to call to cancel the ongoing stream. */
         cancel: () => void;
         /** A getter function that returns the current status of the stream ('active', 'cancelled', or 'completed'). */
-        status: () => 'active' | 'cancelled' | 'completed';
+        status: () => "active" | "cancelled" | "completed";
     };
 }
 /**
@@ -512,12 +465,12 @@ declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<s
         file: File;
         options?: TUploadOptions;
     }): Promise<T | undefined>;
-    refresh(operation: 'read', params: TReadOptions): Promise<T | undefined>;
-    refresh(operation: 'list', params: TListOptions): Promise<Page<T> | undefined>;
-    refresh(operation: 'find', query: TFindOptions): Promise<Page<T> | undefined>;
-    prefetch(operation: 'read', params: TReadOptions): void;
-    prefetch(operation: 'list', params: TListOptions): void;
-    prefetch(operation: 'find', params: TFindOptions): void;
+    refresh(operation: "read", params: TReadOptions): Promise<T | undefined>;
+    refresh(operation: "list", params: TListOptions): Promise<Page<T> | undefined>;
+    refresh(operation: "find", query: TFindOptions): Promise<Page<T> | undefined>;
+    prefetch(operation: "read", params: TReadOptions): void;
+    prefetch(operation: "list", params: TListOptions): void;
+    prefetch(operation: "find", params: TFindOptions): void;
     invalidate(operation: string, params: any): Promise<void>;
     invalidateAll(): Promise<void>;
     getStats(): {

package/index.d.ts

@@ -1,51 +1,4 @@
-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;
-    };
-}
+import { SimplePersistence } from '@core/persistence';
 
 interface CacheOptions {
     staleTime?: number;
@@ -85,51 +38,51 @@ type CacheEventBase<Type extends string, Payload = {}> = {
     key: string;
     timestamp: number;
 } & Payload;
-type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
+type CacheReadHitEvent<T = any> = CacheEventBase<"cache:read:hit", {
     data: T;
     isStale: boolean;
 }>;
-type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
-type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
+type CacheReadMissEvent = CacheEventBase<"cache:read:miss">;
+type CacheFetchStartEvent = CacheEventBase<"cache:fetch:start", {
     attempt: number;
 }>;
-type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<"cache:fetch:success", {
     data: T;
 }>;
-type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
+type CacheFetchErrorEvent = CacheEventBase<"cache:fetch:error", {
     error: Error;
     attempt: number;
 }>;
-type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
+type CacheDataEvictEvent = CacheEventBase<"cache:data:evict", {
     reason?: string;
 }>;
-type CacheDataInvalidateEvent = CacheEventBase<'cache:data:invalidate'>;
-type CacheDataSetEvent<T = any> = CacheEventBase<'cache:data:set', {
+type CacheDataInvalidateEvent = CacheEventBase<"cache:data:invalidate">;
+type CacheDataSetEvent<T = any> = CacheEventBase<"cache:data:set", {
     newData: T;
     oldData?: T;
 }>;
-type CachePersistenceLoadSuccessEvent = CacheEventBase<'cache:persistence:load:success', {
+type CachePersistenceLoadSuccessEvent = CacheEventBase<"cache:persistence:load:success", {
     message?: string;
 }>;
-type CachePersistenceLoadErrorEvent = CacheEventBase<'cache:persistence:load:error', {
+type CachePersistenceLoadErrorEvent = CacheEventBase<"cache:persistence:load:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSaveSuccessEvent = CacheEventBase<'cache:persistence:save:success'>;
-type CachePersistenceSaveErrorEvent = CacheEventBase<'cache:persistence:save:error', {
+type CachePersistenceSaveSuccessEvent = CacheEventBase<"cache:persistence:save:success">;
+type CachePersistenceSaveErrorEvent = CacheEventBase<"cache:persistence:save:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceClearSuccessEvent = CacheEventBase<'cache:persistence:clear:success'>;
-type CachePersistenceClearErrorEvent = CacheEventBase<'cache:persistence:clear:error', {
+type CachePersistenceClearSuccessEvent = CacheEventBase<"cache:persistence:clear:success">;
+type CachePersistenceClearErrorEvent = CacheEventBase<"cache:persistence:clear:error", {
     message?: string;
     error?: any;
 }>;
-type CachePersistenceSyncEvent = CacheEventBase<'cache:persistence:sync', {
+type CachePersistenceSyncEvent = CacheEventBase<"cache:persistence:sync", {
     message?: string;
 }>;
 type CacheEvent = CacheReadHitEvent | CacheReadMissEvent | CacheFetchStartEvent | CacheFetchSuccessEvent | CacheFetchErrorEvent | CacheDataEvictEvent | CacheDataInvalidateEvent | CacheDataSetEvent | CachePersistenceLoadSuccessEvent | CachePersistenceLoadErrorEvent | CachePersistenceSaveSuccessEvent | CachePersistenceSaveErrorEvent | CachePersistenceClearSuccessEvent | CachePersistenceClearErrorEvent | CachePersistenceSyncEvent;
-type CacheEventType = CacheEvent['type'];
+type CacheEventType = CacheEvent["type"];
 
 declare class QueryCache {
     private cache;
@@ -233,7 +186,7 @@ interface StoreEvent {
 /**
  * Defines the types of mutation operations that can occur.
  */
-type MutationOperation = 'create' | 'update' | 'delete' | 'upload';
+type MutationOperation = "create" | "update" | "delete" | "upload";
 /**
  * A correlator function that determines which active queries should be invalidated
  * based on a mutation operation.
@@ -342,7 +295,7 @@ interface BaseStore<T extends StoreRecord, TFindOptions = Record<string, unknown
         /** A function to call to cancel the ongoing stream. */
         cancel: () => void;
         /** A getter function that returns the current status of the stream ('active', 'cancelled', or 'completed'). */
-        status: () => 'active' | 'cancelled' | 'completed';
+        status: () => "active" | "cancelled" | "completed";
     };
 }
 /**
@@ -512,12 +465,12 @@ declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<s
         file: File;
         options?: TUploadOptions;
     }): Promise<T | undefined>;
-    refresh(operation: 'read', params: TReadOptions): Promise<T | undefined>;
-    refresh(operation: 'list', params: TListOptions): Promise<Page<T> | undefined>;
-    refresh(operation: 'find', query: TFindOptions): Promise<Page<T> | undefined>;
-    prefetch(operation: 'read', params: TReadOptions): void;
-    prefetch(operation: 'list', params: TListOptions): void;
-    prefetch(operation: 'find', params: TFindOptions): void;
+    refresh(operation: "read", params: TReadOptions): Promise<T | undefined>;
+    refresh(operation: "list", params: TListOptions): Promise<Page<T> | undefined>;
+    refresh(operation: "find", query: TFindOptions): Promise<Page<T> | undefined>;
+    prefetch(operation: "read", params: TReadOptions): void;
+    prefetch(operation: "list", params: TListOptions): void;
+    prefetch(operation: "find", params: TFindOptions): void;
     invalidate(operation: string, params: any): Promise<void>;
     invalidateAll(): Promise<void>;
     getStats(): {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-remote-store",
-  "version": "1.2.9",
+  "version": "1.3.1",
   "description": "A reactive store for remote data, built on top of @asaidimu/utils-cache",
   "main": "index.js",
   "module": "index.mjs",
@@ -9,7 +9,7 @@
     "./*"
   ],
   "dependencies": {
-    "@asaidimu/utils-cache": "3.0.5",
+    "@asaidimu/utils-cache": "3.1.0",
     "eventsource": "^4.0.0"
   },
   "exports": {