@asaidimu/utils-remote-store 1.1.0 → 1.2.1

package/index.d.mts

@@ -1,5 +1,198 @@
-import { QueryCache, CacheMetrics } from '../cache/index.mjs';
-import '../types-DUZGkNEB.js';
+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 CacheOptions {
+    staleTime?: number;
+    cacheTime?: number;
+    retryAttempts?: number;
+    retryDelay?: number;
+    maxSize?: number;
+    enableMetrics?: boolean;
+    persistence?: SimplePersistence<SerializableCacheState>;
+    persistenceId?: string;
+    serializeValue?: (value: any) => any;
+    deserializeValue?: (value: any) => any;
+    persistenceDebounceTime?: number;
+}
+interface CacheMetrics {
+    hits: number;
+    misses: number;
+    fetches: number;
+    errors: number;
+    evictions: number;
+    staleHits: number;
+}
+interface SerializableCacheEntry {
+    data: any;
+    lastUpdated: number;
+    lastAccessed: number;
+    accessCount: number;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+type SerializableCacheState = Array<[string, SerializableCacheEntry]>;
+type CacheEventBase<Type extends string, Payload = {}> = {
+    type: Type;
+    key: string;
+    timestamp: number;
+} & Payload;
+type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
+    data: T;
+    isStale: boolean;
+}>;
+type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
+type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
+    attempt: number;
+}>;
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+    data: T;
+}>;
+type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
+    error: Error;
+    attempt: number;
+}>;
+type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
+    reason?: string;
+}>;
+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', {
+    message?: string;
+}>;
+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', {
+    message?: string;
+    error?: any;
+}>;
+type CachePersistenceClearSuccessEvent = CacheEventBase<'cache:persistence:clear:success'>;
+type CachePersistenceClearErrorEvent = CacheEventBase<'cache:persistence:clear:error', {
+    message?: string;
+    error?: any;
+}>;
+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'];
+
+declare class QueryCache {
+    private cache;
+    private queries;
+    private fetching;
+    private readonly defaultOptions;
+    private metrics;
+    private eventBus;
+    private gcTimer?;
+    private readonly persistenceId;
+    private persistenceUnsubscribe?;
+    private persistenceDebounceTimer?;
+    private isHandlingRemoteUpdate;
+    constructor(defaultOptions?: CacheOptions);
+    private initializePersistence;
+    private serializeCache;
+    private deserializeAndLoadCache;
+    private schedulePersistState;
+    private handleRemoteStateChange;
+    registerQuery<T>(key: string, fetchFunction: () => Promise<T>, options?: CacheOptions): void;
+    get<T>(key: string, options?: {
+        waitForFresh?: boolean;
+        throwOnError?: boolean;
+    }): Promise<T | undefined>;
+    peek<T>(key: string): T | undefined;
+    has(key: string): boolean;
+    private fetch;
+    private fetchAndWait;
+    private performFetchWithRetry;
+    private isStale;
+    invalidate(key: string, refetch?: boolean): Promise<void>;
+    invalidatePattern(pattern: RegExp, refetch?: boolean): Promise<void>;
+    prefetch(key: string): Promise<void>;
+    refresh<T>(key: string): Promise<T | undefined>;
+    setData<T>(key: string, data: T): void;
+    remove(key: string): boolean;
+    private enforceSizeLimit;
+    private startGarbageCollection;
+    garbageCollect(): number;
+    getStats(): {
+        size: number;
+        metrics: CacheMetrics;
+        hitRate: number;
+        staleHitRate: number;
+        entries: Array<{
+            key: string;
+            lastAccessed: number;
+            lastUpdated: number;
+            accessCount: number;
+            isStale: boolean;
+            isLoading?: boolean;
+            error?: boolean;
+        }>;
+    };
+    on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, {
+        type: EType;
+    }>) => void): () => void;
+    private emitEvent;
+    private updateMetrics;
+    private delay;
+    clear(): Promise<void>;
+    destroy(): void;
+}
 
 interface StoreErrorDetails {
     code: string;
@@ -205,7 +398,9 @@ interface PagedQueryResult<T> {
     /** Function to fetch a specific page of data.
      * @param page The page number to fetch.
      */
-    fetch: (page: number) => Promise<void>;
+    navigate: (page: number) => Promise<void>;
+    refresh: (delay?: number) => Promise<void>;
+    changeParams: (setter: (params: any) => any) => Promise<void>;
 }
 /**
  * Represents a basic record in the remote store.
@@ -230,26 +425,6 @@ type PaginationInfo = {
  * Represents the name of a resource in the store, e.g., 'todos', 'users'.
  */
 type ResourceName = string;
-/**
- * Represents the reactive result of a single record query.
- * @template T The type of the data being queried.
- */
-interface ReactiveQueryResult<T> {
-    /** The current query result, including data, loading state, and errors. */
-    value: () => QueryResult<T>;
-    /** A function to subscribe to changes in the query result. Returns an unsubscribe function. */
-    onValueChange: (callback: () => void) => () => void;
-}
-/**
- * Represents the reactive result of a paginated query (list or find).
- * @template T The type of the records in the page.
- */
-interface ReactivePagedQueryResult<T> {
-    /** The current paginated query result, including page data, loading state, and errors. */
-    value: () => PagedQueryResult<T>;
-    /** A function to subscribe to changes in the query result. Returns an unsubscribe function. */
-    onValueChange: (callback: () => void) => () => void;
-}
 /**
  * Internal interface representing an active subscription to a query.
  * @template T The type of the data being queried.
@@ -271,283 +446,80 @@ interface QuerySubscription<T> {
     result: QueryResult<T> | PagedQueryResult<T>;
 }
 
+/**
+ * Represents the result of a store query with stable React integration.
+ * @template T The type of the result data.
+ */
+interface StoreResult<T extends Record<string, any> = Record<string, any>, V = QueryResult<T> | PagedQueryResult<T>> {
+    /** Function that returns the current query state */
+    value: () => V;
+    /** Function to subscribe to state changes */
+    onValueChange: (callback: () => void) => () => void;
+}
 /**
  * A reactive remote store that provides cached and observable access to data
  * from a `BaseStore`. It handles caching, invalidation, and real-time updates
  * via server-sent events (SSE).
- *
- * @template T The type of the records managed by the store, extending Record.
- * @template TFindOptions Options for the find operation.
- * @template TReadOptions Options for the read operation.
- * @template TListOptions Options for the list operation.
- * @template TDeleteOptions Options for the delete operation.
- * @template TUpdateOptions Options for the update operation.
- * @template TCreateOptions Options for the create operation.
- * @template TUploadOptions Options for the upload operation.
- * @template TStreamOptions Options for the stream operation.
  */
 declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<string, unknown>, TReadOptions = Record<string, unknown>, TListOptions = Record<string, unknown>, TDeleteOptions = Record<string, unknown>, TUpdateOptions = Record<string, unknown>, TCreateOptions = Record<string, unknown>, TUploadOptions = Record<string, unknown>, TStreamOptions = Record<string, unknown>> {
     private cache;
     private baseStore;
     private correlator?;
     private storeEventCorrelator?;
-    private querySubscriptions;
+    private queryStates;
+    private stableResults;
+    private stablePaginationMethods;
+    private errorCache;
     private keyCache;
     private unsubscribeFromBaseStore;
-    /**
-     * Creates an instance of ReactiveRemoteStore.
-     * @param cache The QueryCache instance to use for caching data.
-     * @param baseStore The underlying BaseStore for actual data fetching and mutations.
-     * @param correlator Optional function to determine which queries to invalidate after a mutation.
-     * @param storeEventCorrelator Optional function to determine which queries to invalidate after a store event.
-     */
+    private cacheEventCleanups;
     constructor(cache: QueryCache, baseStore: BaseStore<T, TFindOptions, TReadOptions, TListOptions, TDeleteOptions, TUpdateOptions, TCreateOptions, TUploadOptions, TStreamOptions>, correlator?: Correlator | undefined, storeEventCorrelator?: StoreEventCorrelator | undefined);
-    /**
-     * Creates a new query subscription and registers it with the cache.
-     * @template T The type of the data for the subscription.
-     * @param queryKey The unique key for the query.
-     * @param operation The operation type (e.g., 'read', 'list').
-     * @param params The parameters for the query.
-     * @param selector A function that returns the current query result.
-     * @param notificationCondition A function to determine if a cache event should trigger a notification.
-     * @returns The created QuerySubscription.
-     */
-    private createSubscription;
-    /**
-     * Retrieves an existing subscription or creates a new one if it doesn't exist.
-     * @template T The type of the data for the subscription.
-     * @param queryKey The unique key for the query.
-     * @param operation The operation type (e.g., 'read', 'list').
-     * @param params The parameters for the query.
-     * @param selector A function that returns the current query result.
-     * @param notificationCondition A function to determine if a cache event should trigger a notification.
-     * @returns The existing or newly created QuerySubscription.
-     */
-    private getOrCreateSubscription;
-    /**
-     * Builds a unique cache key for a given operation and its parameters.
-     * Uses a WeakMap for caching keys of object parameters to avoid re-hashing.
-     * @param operation The name of the operation (e.g., 'read', 'list').
-     * @param params The parameters for the operation.
-     * @returns A unique string key for the operation and parameters.
-     */
+    private setupCacheEventListeners;
+    private handleCacheEvent;
     private buildKey;
-    /**
-     * Creates a selector function for a single record query.
-     * @template T The type of the data being queried.
-     * @param queryKey The unique key for the query.
-     * @returns A function that returns the current QueryResult for the given key.
-     */
-    private createSelector;
-    /**
-     * Reads a single record from the store.
-     * @param params The read options.
-     * @returns An object containing the current QueryResult and a function to subscribe to changes.
-     */
-    /**
-     * Retrieves a single record reactively.
-     *
-     * This method provides a reactive query result for a single record. The data is fetched from the cache if available,
-     * otherwise it's fetched from the underlying `baseStore`. The method returns an object containing the current
-     * query result and a function to subscribe to future updates.
-     *
-     * @param params The options for the read operation, used to identify the record.
-     * @returns A `ReactiveQueryResult` object containing the reactive value and an `onValueChange` subscription function.
-     */
-    read(params: TReadOptions): ReactiveQueryResult<T>;
-    /**
-     * Creates a selector function for a paginated query (list or find).
-     * @template TParams The type of the parameters for the query.
-     * @param baseQueryKey The base unique key for the query.
-     * @param baseParams The base parameters for the query.
-     * @param fetchFn The function to call to fetch a page of data.
-     * @returns A function that returns the current PagedQueryResult.
-     */
-    private createPagedSelector;
-    /**
-     * Sets up a paginated query (list or find) with caching and reactivity.
-     * @template TParams The type of the parameters for the query.
-     * @param type The type of the paginated query ('list' or 'find').
-     * @param params The parameters for the query.
-     * @param fetchFn The function to call to fetch a page of data.
-     * @returns An object containing the current PagedQueryResult and a function to subscribe to changes.
-     */
+    private getOrCreateError;
+    private getOrCreateStoreError;
+    private computeResult;
+    private scheduleBackgroundFetch;
+    private getCurrentPageForQuery;
+    private getOrCreatePaginationMethods;
+    private computeResultForParams;
+    hasActiveQuery(operation: string, params: any): boolean;
+    getActiveQuery<TResult extends Record<string, unknown> = T>(operation: string, params: any): StoreResult<TResult> | undefined;
+    read(params: TReadOptions): StoreResult<T, QueryResult<T>>;
+    list(params: TListOptions): StoreResult<T, PagedQueryResult<T>>;
+    find(params: TFindOptions): StoreResult<T, PagedQueryResult<T>>;
     private setupPagedQuery;
-    /**
-     * Lists records from the store with pagination and reactivity.
-     * @param params The list options.
-     * @returns An object containing the current PagedQueryResult and a function to subscribe to changes.
-     */
-    /**
-     * Retrieves a paginated list of records reactively.
-     *
-     * This method provides a reactive query result for a list of records. It supports pagination and automatically
-     * fetches data from the cache or the `baseStore`. The result includes methods for navigating to the next,
-     * previous, or a specific page.
-     *
-     * @param params The options for the list operation, including pagination details.
-     * @returns A `ReactivePagedQueryResult` object containing the reactive paged value and an `onValueChange` subscription function.
-     */
-    list(params: TListOptions): ReactivePagedQueryResult<T>;
-    /**
-     * Finds records from the store with pagination and reactivity.
-     * @param params The find options.
-     * @returns An object containing the current PagedQueryResult and a function to subscribe to changes.
-     */
-    /**
-     * Finds and retrieves a paginated list of records reactively based on a query.
-     *
-     * Similar to `list`, this method provides a reactive query result for a set of records that match the given
-     * find options. It supports pagination and provides methods for navigating through the pages.
-     *
-     * @param params The options for the find operation, used to query for specific records.
-     * @returns A `ReactivePagedQueryResult` object containing the reactive paged value and an `onValueChange` subscription function.
-     */
-    find(params: TFindOptions): ReactivePagedQueryResult<T>;
-    /**
-     * Invalidates relevant queries in the cache based on a mutation operation.
-     * If a correlator is provided, it will be used to determine which queries to invalidate.
-     * Otherwise, it invalidates all 'list' and 'find' queries.
-     * @param mutation An object describing the mutation operation and its parameters.
-     */
     private invalidateQueries;
-    /**
-     * Handles incoming store events, invalidating relevant queries if a `storeEventCorrelator` is provided.
-     * @param event The StoreEvent received.
-     */
     private handleStoreEvent;
-    /**
-     * Creates a new record.
-     *
-     * This method sends a request to the `baseStore` to create a new record. Upon successful creation,
-     * it updates the cache with the new record and invalidates relevant queries to ensure data consistency.
-     *
-     * @param params An object containing the data for the new record and optional create options.
-     * @returns A promise that resolves to the newly created record, or `undefined` if the creation fails.
-     * @throws An error if the create operation fails.
-     */
     create(params: {
         data: Partial<T>;
         options?: TCreateOptions;
     }): Promise<T | undefined>;
-    /**
-     * Updates an existing record.
-     *
-     * This method sends a request to the `baseStore` to update a record. If the update is successful,
-     * it updates the cache with the modified record and invalidates relevant queries.
-     *
-     * @param params An object containing the ID of the record to update, the partial data, and optional update options.
-     * @returns A promise that resolves to the updated record, or `undefined` if the update fails.
-     * @throws An error if the update operation fails.
-     */
     update(params: {
         data: Partial<T>;
         options?: TUpdateOptions;
     }): Promise<T | undefined>;
-    /**
-     * Deletes a record.
-     *
-     * This method sends a request to the `baseStore` to delete a record. Upon successful deletion,
-     * it removes the record from the cache and invalidates relevant queries.
-     *
-     * @param params The options for the delete operation, used to identify the record to be deleted.
-     * @returns A promise that resolves when the deletion is complete.
-     * @throws An error if the delete operation fails.
-     */
     delete(params: TDeleteOptions): Promise<void>;
-    /**
-     * Sends a notification event to the base store.
-     *
-     * This can be used to trigger server-side events or other custom actions in the `baseStore`.
-     *
-     * @param event The `StoreEvent` to be sent.
-     * @returns A promise that resolves when the notification has been processed.
-     */
     notify(event: StoreEvent): Promise<void>;
-    /**
-     * Establishes a real-time data stream.
-     *
-     * This method delegates to the `baseStore`'s `stream` method to create a persistent connection for
-     * receiving real-time updates. The provided callback will be invoked when new data is available.
-     *
-     * @param options The options for the stream operation.
-     * @param onStreamChange A callback function that is executed when the stream's data changes.
-     * @returns A promise that resolves with a function to close the stream.
-     */
-    stream(options: TStreamOptions, onStreamChange: () => void): Promise<{
+    stream(options: TStreamOptions, onStreamChange: () => void): {
         stream: () => AsyncIterable<T>;
         cancel: () => void;
         status: () => "active" | "cancelled" | "completed";
-    }>;
-    /**
-     * Uploads a file and creates a new record associated with it.
-     *
-     * This method handles file uploads through the `baseStore`. After a successful upload, it updates the cache
-     * with the new record and invalidates relevant queries.
-     *
-     * @param params An object containing the file to upload and optional upload options.
-     * @returns A promise that resolves to the newly created record, or `undefined` if the upload fails.
-     * @throws An error if the upload operation fails.
-     */
+    };
+    subscribe(scope: string, callback: (event: StoreEvent) => void): Promise<() => void>;
     upload(params: {
         file: File;
         options?: TUploadOptions;
     }): Promise<T | undefined>;
-    /**
-     * Forces a refresh of a specific query.
-     *
-     * This method bypasses the cache's staleness checks and forces a refetch of the data from the `baseStore`.
-     * The method is overloaded to support `read`, `list`, and `find` operations.
-     *
-     * @param operation The type of operation to refresh ('read', 'list', or 'find').
-     * @param params The parameters for the operation.
-     * @returns A promise that resolves to the refreshed data.
-     */
     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>;
-    /**
-     * Pre-fetches data for a query and caches it.
-     *
-     * This method is used to proactively fetch data that is likely to be needed soon. It fetches the data
-     * and stores it in the cache, so that subsequent requests for the same data can be served instantly.
-     * The method is overloaded for `read`, `list`, and `find` operations.
-     *
-     * @param operation The type of operation to prefetch ('read', 'list', or 'find').
-     * @param params The parameters for the operation.
-     */
     prefetch(operation: 'read', params: TReadOptions): void;
     prefetch(operation: 'list', params: TListOptions): void;
     prefetch(operation: 'find', params: TFindOptions): void;
-    /**
-     * Invalidates the cached data for a specific query.
-     *
-     * This marks the query's data as stale, forcing a refetch the next time it's accessed. This is useful
-     * when you know the data has changed on the server, but the change was not triggered by a mutation
-     * through this store.
-     *
-     * @param operation The type of operation to invalidate ('read', 'list', or 'find').
-     * @param params The parameters for the operation.
-     * @returns A promise that resolves when the invalidation is complete.
-     */
     invalidate(operation: string, params: any): Promise<void>;
-    /**
-     * Invalidates all active queries in the store.
-     *
-     * This method marks all currently active queries as stale, forcing them to be refetched the next time
-     * they are accessed. This is a more aggressive approach to cache invalidation.
-     *
-     * @returns A promise that resolves when all invalidations are complete.
-     */
     invalidateAll(): Promise<void>;
-    /**
-     * Retrieves statistics about the store and its cache.
-     *
-     * This method returns an object containing statistics from the underlying cache, plus the number of
-     * active subscriptions in the reactive store.
-     *
-     * @returns An object with cache statistics and the number of active subscriptions.
-     */
     getStats(): {
         activeSubscriptions: number;
         size: number;
@@ -564,12 +536,6 @@ declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<s
             error?: boolean;
         }>;
     };
-    /**
-     * Cleans up all resources used by the store.
-     *
-     * This method should be called when the store is no longer needed. It unsubscribes from all cache events,
-     * clears all query subscriptions, and unsubscribes from the base store's events.
-     */
     destroy(): void;
 }
 
@@ -580,4 +546,4 @@ declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<s
  */
 declare function hash(data: any): string;
 
-export { type ActiveQuery, type BaseStore, type Correlator, type MutationOperation, type Page, type PagedQueryResult, type PaginationInfo, type QueryResult, type QuerySubscription, type ReactivePagedQueryResult, type ReactiveQueryResult, ReactiveRemoteStore, type ResourceName, StoreError, type StoreErrorDetails, type StoreEvent, type StoreEventCorrelator, type StoreRecord, hash };
+export { type ActiveQuery, type BaseStore, type Correlator, type MutationOperation, type Page, type PagedQueryResult, type PaginationInfo, type QueryResult, type QuerySubscription, ReactiveRemoteStore, type ResourceName, StoreError, type StoreErrorDetails, type StoreEvent, type StoreEventCorrelator, type StoreRecord, type StoreResult, hash };

package/index.d.ts

@@ -1,5 +1,198 @@
-import { QueryCache, CacheMetrics } from '../cache/index.js';
-import '../types-DUZGkNEB.js';
+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 CacheOptions {
+    staleTime?: number;
+    cacheTime?: number;
+    retryAttempts?: number;
+    retryDelay?: number;
+    maxSize?: number;
+    enableMetrics?: boolean;
+    persistence?: SimplePersistence<SerializableCacheState>;
+    persistenceId?: string;
+    serializeValue?: (value: any) => any;
+    deserializeValue?: (value: any) => any;
+    persistenceDebounceTime?: number;
+}
+interface CacheMetrics {
+    hits: number;
+    misses: number;
+    fetches: number;
+    errors: number;
+    evictions: number;
+    staleHits: number;
+}
+interface SerializableCacheEntry {
+    data: any;
+    lastUpdated: number;
+    lastAccessed: number;
+    accessCount: number;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+type SerializableCacheState = Array<[string, SerializableCacheEntry]>;
+type CacheEventBase<Type extends string, Payload = {}> = {
+    type: Type;
+    key: string;
+    timestamp: number;
+} & Payload;
+type CacheReadHitEvent<T = any> = CacheEventBase<'cache:read:hit', {
+    data: T;
+    isStale: boolean;
+}>;
+type CacheReadMissEvent = CacheEventBase<'cache:read:miss'>;
+type CacheFetchStartEvent = CacheEventBase<'cache:fetch:start', {
+    attempt: number;
+}>;
+type CacheFetchSuccessEvent<T = any> = CacheEventBase<'cache:fetch:success', {
+    data: T;
+}>;
+type CacheFetchErrorEvent = CacheEventBase<'cache:fetch:error', {
+    error: Error;
+    attempt: number;
+}>;
+type CacheDataEvictEvent = CacheEventBase<'cache:data:evict', {
+    reason?: string;
+}>;
+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', {
+    message?: string;
+}>;
+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', {
+    message?: string;
+    error?: any;
+}>;
+type CachePersistenceClearSuccessEvent = CacheEventBase<'cache:persistence:clear:success'>;
+type CachePersistenceClearErrorEvent = CacheEventBase<'cache:persistence:clear:error', {
+    message?: string;
+    error?: any;
+}>;
+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'];
+
+declare class QueryCache {
+    private cache;
+    private queries;
+    private fetching;
+    private readonly defaultOptions;
+    private metrics;
+    private eventBus;
+    private gcTimer?;
+    private readonly persistenceId;
+    private persistenceUnsubscribe?;
+    private persistenceDebounceTimer?;
+    private isHandlingRemoteUpdate;
+    constructor(defaultOptions?: CacheOptions);
+    private initializePersistence;
+    private serializeCache;
+    private deserializeAndLoadCache;
+    private schedulePersistState;
+    private handleRemoteStateChange;
+    registerQuery<T>(key: string, fetchFunction: () => Promise<T>, options?: CacheOptions): void;
+    get<T>(key: string, options?: {
+        waitForFresh?: boolean;
+        throwOnError?: boolean;
+    }): Promise<T | undefined>;
+    peek<T>(key: string): T | undefined;
+    has(key: string): boolean;
+    private fetch;
+    private fetchAndWait;
+    private performFetchWithRetry;
+    private isStale;
+    invalidate(key: string, refetch?: boolean): Promise<void>;
+    invalidatePattern(pattern: RegExp, refetch?: boolean): Promise<void>;
+    prefetch(key: string): Promise<void>;
+    refresh<T>(key: string): Promise<T | undefined>;
+    setData<T>(key: string, data: T): void;
+    remove(key: string): boolean;
+    private enforceSizeLimit;
+    private startGarbageCollection;
+    garbageCollect(): number;
+    getStats(): {
+        size: number;
+        metrics: CacheMetrics;
+        hitRate: number;
+        staleHitRate: number;
+        entries: Array<{
+            key: string;
+            lastAccessed: number;
+            lastUpdated: number;
+            accessCount: number;
+            isStale: boolean;
+            isLoading?: boolean;
+            error?: boolean;
+        }>;
+    };
+    on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, {
+        type: EType;
+    }>) => void): () => void;
+    private emitEvent;
+    private updateMetrics;
+    private delay;
+    clear(): Promise<void>;
+    destroy(): void;
+}
 
 interface StoreErrorDetails {
     code: string;
@@ -205,7 +398,9 @@ interface PagedQueryResult<T> {
     /** Function to fetch a specific page of data.
      * @param page The page number to fetch.
      */
-    fetch: (page: number) => Promise<void>;
+    navigate: (page: number) => Promise<void>;
+    refresh: (delay?: number) => Promise<void>;
+    changeParams: (setter: (params: any) => any) => Promise<void>;
 }
 /**
  * Represents a basic record in the remote store.
@@ -230,26 +425,6 @@ type PaginationInfo = {
  * Represents the name of a resource in the store, e.g., 'todos', 'users'.
  */
 type ResourceName = string;
-/**
- * Represents the reactive result of a single record query.
- * @template T The type of the data being queried.
- */
-interface ReactiveQueryResult<T> {
-    /** The current query result, including data, loading state, and errors. */
-    value: () => QueryResult<T>;
-    /** A function to subscribe to changes in the query result. Returns an unsubscribe function. */
-    onValueChange: (callback: () => void) => () => void;
-}
-/**
- * Represents the reactive result of a paginated query (list or find).
- * @template T The type of the records in the page.
- */
-interface ReactivePagedQueryResult<T> {
-    /** The current paginated query result, including page data, loading state, and errors. */
-    value: () => PagedQueryResult<T>;
-    /** A function to subscribe to changes in the query result. Returns an unsubscribe function. */
-    onValueChange: (callback: () => void) => () => void;
-}
 /**
  * Internal interface representing an active subscription to a query.
  * @template T The type of the data being queried.
@@ -271,283 +446,80 @@ interface QuerySubscription<T> {
     result: QueryResult<T> | PagedQueryResult<T>;
 }
 
+/**
+ * Represents the result of a store query with stable React integration.
+ * @template T The type of the result data.
+ */
+interface StoreResult<T extends Record<string, any> = Record<string, any>, V = QueryResult<T> | PagedQueryResult<T>> {
+    /** Function that returns the current query state */
+    value: () => V;
+    /** Function to subscribe to state changes */
+    onValueChange: (callback: () => void) => () => void;
+}
 /**
  * A reactive remote store that provides cached and observable access to data
  * from a `BaseStore`. It handles caching, invalidation, and real-time updates
  * via server-sent events (SSE).
- *
- * @template T The type of the records managed by the store, extending Record.
- * @template TFindOptions Options for the find operation.
- * @template TReadOptions Options for the read operation.
- * @template TListOptions Options for the list operation.
- * @template TDeleteOptions Options for the delete operation.
- * @template TUpdateOptions Options for the update operation.
- * @template TCreateOptions Options for the create operation.
- * @template TUploadOptions Options for the upload operation.
- * @template TStreamOptions Options for the stream operation.
  */
 declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<string, unknown>, TReadOptions = Record<string, unknown>, TListOptions = Record<string, unknown>, TDeleteOptions = Record<string, unknown>, TUpdateOptions = Record<string, unknown>, TCreateOptions = Record<string, unknown>, TUploadOptions = Record<string, unknown>, TStreamOptions = Record<string, unknown>> {
     private cache;
     private baseStore;
     private correlator?;
     private storeEventCorrelator?;
-    private querySubscriptions;
+    private queryStates;
+    private stableResults;
+    private stablePaginationMethods;
+    private errorCache;
     private keyCache;
     private unsubscribeFromBaseStore;
-    /**
-     * Creates an instance of ReactiveRemoteStore.
-     * @param cache The QueryCache instance to use for caching data.
-     * @param baseStore The underlying BaseStore for actual data fetching and mutations.
-     * @param correlator Optional function to determine which queries to invalidate after a mutation.
-     * @param storeEventCorrelator Optional function to determine which queries to invalidate after a store event.
-     */
+    private cacheEventCleanups;
     constructor(cache: QueryCache, baseStore: BaseStore<T, TFindOptions, TReadOptions, TListOptions, TDeleteOptions, TUpdateOptions, TCreateOptions, TUploadOptions, TStreamOptions>, correlator?: Correlator | undefined, storeEventCorrelator?: StoreEventCorrelator | undefined);
-    /**
-     * Creates a new query subscription and registers it with the cache.
-     * @template T The type of the data for the subscription.
-     * @param queryKey The unique key for the query.
-     * @param operation The operation type (e.g., 'read', 'list').
-     * @param params The parameters for the query.
-     * @param selector A function that returns the current query result.
-     * @param notificationCondition A function to determine if a cache event should trigger a notification.
-     * @returns The created QuerySubscription.
-     */
-    private createSubscription;
-    /**
-     * Retrieves an existing subscription or creates a new one if it doesn't exist.
-     * @template T The type of the data for the subscription.
-     * @param queryKey The unique key for the query.
-     * @param operation The operation type (e.g., 'read', 'list').
-     * @param params The parameters for the query.
-     * @param selector A function that returns the current query result.
-     * @param notificationCondition A function to determine if a cache event should trigger a notification.
-     * @returns The existing or newly created QuerySubscription.
-     */
-    private getOrCreateSubscription;
-    /**
-     * Builds a unique cache key for a given operation and its parameters.
-     * Uses a WeakMap for caching keys of object parameters to avoid re-hashing.
-     * @param operation The name of the operation (e.g., 'read', 'list').
-     * @param params The parameters for the operation.
-     * @returns A unique string key for the operation and parameters.
-     */
+    private setupCacheEventListeners;
+    private handleCacheEvent;
     private buildKey;
-    /**
-     * Creates a selector function for a single record query.
-     * @template T The type of the data being queried.
-     * @param queryKey The unique key for the query.
-     * @returns A function that returns the current QueryResult for the given key.
-     */
-    private createSelector;
-    /**
-     * Reads a single record from the store.
-     * @param params The read options.
-     * @returns An object containing the current QueryResult and a function to subscribe to changes.
-     */
-    /**
-     * Retrieves a single record reactively.
-     *
-     * This method provides a reactive query result for a single record. The data is fetched from the cache if available,
-     * otherwise it's fetched from the underlying `baseStore`. The method returns an object containing the current
-     * query result and a function to subscribe to future updates.
-     *
-     * @param params The options for the read operation, used to identify the record.
-     * @returns A `ReactiveQueryResult` object containing the reactive value and an `onValueChange` subscription function.
-     */
-    read(params: TReadOptions): ReactiveQueryResult<T>;
-    /**
-     * Creates a selector function for a paginated query (list or find).
-     * @template TParams The type of the parameters for the query.
-     * @param baseQueryKey The base unique key for the query.
-     * @param baseParams The base parameters for the query.
-     * @param fetchFn The function to call to fetch a page of data.
-     * @returns A function that returns the current PagedQueryResult.
-     */
-    private createPagedSelector;
-    /**
-     * Sets up a paginated query (list or find) with caching and reactivity.
-     * @template TParams The type of the parameters for the query.
-     * @param type The type of the paginated query ('list' or 'find').
-     * @param params The parameters for the query.
-     * @param fetchFn The function to call to fetch a page of data.
-     * @returns An object containing the current PagedQueryResult and a function to subscribe to changes.
-     */
+    private getOrCreateError;
+    private getOrCreateStoreError;
+    private computeResult;
+    private scheduleBackgroundFetch;
+    private getCurrentPageForQuery;
+    private getOrCreatePaginationMethods;
+    private computeResultForParams;
+    hasActiveQuery(operation: string, params: any): boolean;
+    getActiveQuery<TResult extends Record<string, unknown> = T>(operation: string, params: any): StoreResult<TResult> | undefined;
+    read(params: TReadOptions): StoreResult<T, QueryResult<T>>;
+    list(params: TListOptions): StoreResult<T, PagedQueryResult<T>>;
+    find(params: TFindOptions): StoreResult<T, PagedQueryResult<T>>;
     private setupPagedQuery;
-    /**
-     * Lists records from the store with pagination and reactivity.
-     * @param params The list options.
-     * @returns An object containing the current PagedQueryResult and a function to subscribe to changes.
-     */
-    /**
-     * Retrieves a paginated list of records reactively.
-     *
-     * This method provides a reactive query result for a list of records. It supports pagination and automatically
-     * fetches data from the cache or the `baseStore`. The result includes methods for navigating to the next,
-     * previous, or a specific page.
-     *
-     * @param params The options for the list operation, including pagination details.
-     * @returns A `ReactivePagedQueryResult` object containing the reactive paged value and an `onValueChange` subscription function.
-     */
-    list(params: TListOptions): ReactivePagedQueryResult<T>;
-    /**
-     * Finds records from the store with pagination and reactivity.
-     * @param params The find options.
-     * @returns An object containing the current PagedQueryResult and a function to subscribe to changes.
-     */
-    /**
-     * Finds and retrieves a paginated list of records reactively based on a query.
-     *
-     * Similar to `list`, this method provides a reactive query result for a set of records that match the given
-     * find options. It supports pagination and provides methods for navigating through the pages.
-     *
-     * @param params The options for the find operation, used to query for specific records.
-     * @returns A `ReactivePagedQueryResult` object containing the reactive paged value and an `onValueChange` subscription function.
-     */
-    find(params: TFindOptions): ReactivePagedQueryResult<T>;
-    /**
-     * Invalidates relevant queries in the cache based on a mutation operation.
-     * If a correlator is provided, it will be used to determine which queries to invalidate.
-     * Otherwise, it invalidates all 'list' and 'find' queries.
-     * @param mutation An object describing the mutation operation and its parameters.
-     */
     private invalidateQueries;
-    /**
-     * Handles incoming store events, invalidating relevant queries if a `storeEventCorrelator` is provided.
-     * @param event The StoreEvent received.
-     */
     private handleStoreEvent;
-    /**
-     * Creates a new record.
-     *
-     * This method sends a request to the `baseStore` to create a new record. Upon successful creation,
-     * it updates the cache with the new record and invalidates relevant queries to ensure data consistency.
-     *
-     * @param params An object containing the data for the new record and optional create options.
-     * @returns A promise that resolves to the newly created record, or `undefined` if the creation fails.
-     * @throws An error if the create operation fails.
-     */
     create(params: {
         data: Partial<T>;
         options?: TCreateOptions;
     }): Promise<T | undefined>;
-    /**
-     * Updates an existing record.
-     *
-     * This method sends a request to the `baseStore` to update a record. If the update is successful,
-     * it updates the cache with the modified record and invalidates relevant queries.
-     *
-     * @param params An object containing the ID of the record to update, the partial data, and optional update options.
-     * @returns A promise that resolves to the updated record, or `undefined` if the update fails.
-     * @throws An error if the update operation fails.
-     */
     update(params: {
         data: Partial<T>;
         options?: TUpdateOptions;
     }): Promise<T | undefined>;
-    /**
-     * Deletes a record.
-     *
-     * This method sends a request to the `baseStore` to delete a record. Upon successful deletion,
-     * it removes the record from the cache and invalidates relevant queries.
-     *
-     * @param params The options for the delete operation, used to identify the record to be deleted.
-     * @returns A promise that resolves when the deletion is complete.
-     * @throws An error if the delete operation fails.
-     */
     delete(params: TDeleteOptions): Promise<void>;
-    /**
-     * Sends a notification event to the base store.
-     *
-     * This can be used to trigger server-side events or other custom actions in the `baseStore`.
-     *
-     * @param event The `StoreEvent` to be sent.
-     * @returns A promise that resolves when the notification has been processed.
-     */
     notify(event: StoreEvent): Promise<void>;
-    /**
-     * Establishes a real-time data stream.
-     *
-     * This method delegates to the `baseStore`'s `stream` method to create a persistent connection for
-     * receiving real-time updates. The provided callback will be invoked when new data is available.
-     *
-     * @param options The options for the stream operation.
-     * @param onStreamChange A callback function that is executed when the stream's data changes.
-     * @returns A promise that resolves with a function to close the stream.
-     */
-    stream(options: TStreamOptions, onStreamChange: () => void): Promise<{
+    stream(options: TStreamOptions, onStreamChange: () => void): {
         stream: () => AsyncIterable<T>;
         cancel: () => void;
         status: () => "active" | "cancelled" | "completed";
-    }>;
-    /**
-     * Uploads a file and creates a new record associated with it.
-     *
-     * This method handles file uploads through the `baseStore`. After a successful upload, it updates the cache
-     * with the new record and invalidates relevant queries.
-     *
-     * @param params An object containing the file to upload and optional upload options.
-     * @returns A promise that resolves to the newly created record, or `undefined` if the upload fails.
-     * @throws An error if the upload operation fails.
-     */
+    };
+    subscribe(scope: string, callback: (event: StoreEvent) => void): Promise<() => void>;
     upload(params: {
         file: File;
         options?: TUploadOptions;
     }): Promise<T | undefined>;
-    /**
-     * Forces a refresh of a specific query.
-     *
-     * This method bypasses the cache's staleness checks and forces a refetch of the data from the `baseStore`.
-     * The method is overloaded to support `read`, `list`, and `find` operations.
-     *
-     * @param operation The type of operation to refresh ('read', 'list', or 'find').
-     * @param params The parameters for the operation.
-     * @returns A promise that resolves to the refreshed data.
-     */
     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>;
-    /**
-     * Pre-fetches data for a query and caches it.
-     *
-     * This method is used to proactively fetch data that is likely to be needed soon. It fetches the data
-     * and stores it in the cache, so that subsequent requests for the same data can be served instantly.
-     * The method is overloaded for `read`, `list`, and `find` operations.
-     *
-     * @param operation The type of operation to prefetch ('read', 'list', or 'find').
-     * @param params The parameters for the operation.
-     */
     prefetch(operation: 'read', params: TReadOptions): void;
     prefetch(operation: 'list', params: TListOptions): void;
     prefetch(operation: 'find', params: TFindOptions): void;
-    /**
-     * Invalidates the cached data for a specific query.
-     *
-     * This marks the query's data as stale, forcing a refetch the next time it's accessed. This is useful
-     * when you know the data has changed on the server, but the change was not triggered by a mutation
-     * through this store.
-     *
-     * @param operation The type of operation to invalidate ('read', 'list', or 'find').
-     * @param params The parameters for the operation.
-     * @returns A promise that resolves when the invalidation is complete.
-     */
     invalidate(operation: string, params: any): Promise<void>;
-    /**
-     * Invalidates all active queries in the store.
-     *
-     * This method marks all currently active queries as stale, forcing them to be refetched the next time
-     * they are accessed. This is a more aggressive approach to cache invalidation.
-     *
-     * @returns A promise that resolves when all invalidations are complete.
-     */
     invalidateAll(): Promise<void>;
-    /**
-     * Retrieves statistics about the store and its cache.
-     *
-     * This method returns an object containing statistics from the underlying cache, plus the number of
-     * active subscriptions in the reactive store.
-     *
-     * @returns An object with cache statistics and the number of active subscriptions.
-     */
     getStats(): {
         activeSubscriptions: number;
         size: number;
@@ -564,12 +536,6 @@ declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<s
             error?: boolean;
         }>;
     };
-    /**
-     * Cleans up all resources used by the store.
-     *
-     * This method should be called when the store is no longer needed. It unsubscribes from all cache events,
-     * clears all query subscriptions, and unsubscribes from the base store's events.
-     */
     destroy(): void;
 }
 
@@ -580,4 +546,4 @@ declare class ReactiveRemoteStore<T extends StoreRecord, TFindOptions = Record<s
  */
 declare function hash(data: any): string;
 
-export { type ActiveQuery, type BaseStore, type Correlator, type MutationOperation, type Page, type PagedQueryResult, type PaginationInfo, type QueryResult, type QuerySubscription, type ReactivePagedQueryResult, type ReactiveQueryResult, ReactiveRemoteStore, type ResourceName, StoreError, type StoreErrorDetails, type StoreEvent, type StoreEventCorrelator, type StoreRecord, hash };
+export { type ActiveQuery, type BaseStore, type Correlator, type MutationOperation, type Page, type PagedQueryResult, type PaginationInfo, type QueryResult, type QuerySubscription, ReactiveRemoteStore, type ResourceName, StoreError, type StoreErrorDetails, type StoreEvent, type StoreEventCorrelator, type StoreRecord, type StoreResult, hash };

package/index.js

@@ -1 +1 @@
-"use strict";var e=class e extends Error{code;status;data;isRetryable;originalError;constructor(e,t){super(e.message),this.name="StoreError",this.code=e.code,this.status=e.status,this.data=e.data,this.isRetryable=e.isRetryable,this.originalError=t}static fromError(t,r){if(t.isAbort||"AbortError"===t.name)return new e({code:"ABORTED",message:"Request was cancelled",isRetryable:!1},t);if("NetworkError"===t.name||!navigator.onLine)return new e({code:"NETWORK_ERROR",message:"Network connection failed. Please check your internet connection.",isRetryable:!0},t);if(t.status)switch(t.status){case 400:return new e({code:"VALIDATION_ERROR",message:t.message||"Invalid request data",status:400,data:t.data,isRetryable:!1},t);case 401:return new e({code:"UNAUTHORIZED",message:"Authentication required or invalid credentials",status:401,isRetryable:!1},t);case 403:return new e({code:"FORBIDDEN",message:"Access denied for this resource",status:403,isRetryable:!1},t);case 404:return new e({code:"NOT_FOUND",message:"Resource not found",status:404,isRetryable:!1},t);case 409:return new e({code:"CONFLICT",message:t.message||"Resource conflict occurred",status:409,isRetryable:!1},t);case 429:return new e({code:"RATE_LIMITED",message:"Too many requests. Please try again later.",status:429,isRetryable:!0},t);case 500:case 502:case 503:case 504:return new e({code:"SERVER_ERROR",message:"Server error occurred. Please try again later.",status:t.status,isRetryable:!0},t);default:return new e({code:"HTTP_ERROR",message:t.message||`HTTP ${t.status} error occurred`,status:t.status,isRetryable:t.status>=500},t)}return"TimeoutError"===t.name||"TIMEOUT"===t.code?new e({code:"TIMEOUT",message:"Request timed out. Please try again.",isRetryable:!0},t):new e({code:"UNKNOWN_ERROR",message:t.message||`Unknown error occurred during ${r}`,isRetryable:!0},t)}};function t(e,r=new WeakMap){return void 0===e?"undefined":"function"==typeof e||"symbol"==typeof e?"":"string"==typeof e?`"${e}"`:"number"==typeof e||"boolean"==typeof e||null===e?String(e):Array.isArray(e)?`[${e.map((e=>t(e,r))).join(",")}]`:"object"==typeof e?r.has(e)?'"__circular__"':(r.set(e,!0),`{${Object.keys(e).sort().map((a=>`"${a}":${t(e[a],r)}`)).join(",")}}`):""}function r(e){let r=3421674724,a=2216829733;const s=t(e);for(let e=0;e<s.length;e++){a^=s.charCodeAt(e);const t=Math.imul(a,435),i=Math.imul(a,435)+Math.imul(r,435);a=t>>>0,r=i>>>0}return(r>>>0).toString(16)+(a>>>0).toString(16)}exports.ReactiveRemoteStore=class{constructor(e,t,r,a){if(this.cache=e,this.baseStore=t,this.correlator=r,this.storeEventCorrelator=a,this.storeEventCorrelator){queueMicrotask((async()=>{this.unsubscribeFromBaseStore=await this.baseStore.subscribe("*",this.handleStoreEvent.bind(this))}))}}querySubscriptions=new Map;keyCache=new WeakMap;unsubscribeFromBaseStore;createSubscription(e,t,r,a,s){const i=new Set,o={operation:t,params:r,subscribers:i},c=()=>{const e=a();var r,s;("read"===t?(r=o.result,s=e,r&&s?r.data===s.data&&r.loading===s.loading&&r.stale===s.stale&&(r.error===s.error||r.error?.message===s.error?.message):r===s):function(e,t){return e&&t?e.page===t.page&&e.loading===t.loading&&e.stale===t.stale&&(e.error===t.error||e.error?.message===t.error?.message)&&e.hasNext===t.hasNext&&e.hasPrevious===t.hasPrevious:e===t}(o.result,e))||(o.result=e,i.forEach((e=>{try{e()}catch(e){console.error("ReactiveRemoteStore: Subscriber callback error:",e)}})))};return o.unsubscribeCallbacks=[this.cache.on("cache:fetch:success",(e=>{s(e.key)&&c()})),this.cache.on("cache:fetch:error",(e=>{s(e.key)&&c()})),this.cache.on("cache:data:set",(e=>{s(e.key)&&c()})),this.cache.on("cache:data:invalidate",(e=>{s(e.key)&&c()})),this.cache.on("cache:read:hit",(e=>{s(e.key)&&e.isStale&&c()}))],o.cachedSubscribe=t=>(i.add(t),()=>{i.delete(t),0===i.size&&(o.unsubscribeCallbacks.forEach((e=>e())),this.querySubscriptions.delete(e))}),o.cachedSelector=()=>o.result,o.result=a(),this.querySubscriptions.set(e,o),o}getOrCreateSubscription(e,t,r,a,s){let i=this.querySubscriptions.get(e);return i||(i=this.createSubscription(e,t,r,a,s)),i}buildKey(e,t){if("object"==typeof t&&null!==t&&this.keyCache.has(t))return this.keyCache.get(t);const a=`${e}:${r(t)}`;return"object"==typeof t&&null!==t&&this.keyCache.set(t,a),a}createSelector(e){return()=>{const t=this.cache.getStats().entries.find((t=>t.key===e)),r=this.cache.peek(e);t?.isStale&&this.cache.get(e,{waitForFresh:!1}).catch((t=>{console.warn(`ReactiveRemoteStore: Background refetch failed for ${e}:`,t)})),void 0!==r&&this.cache.has(e)||this.cache.get(e,{waitForFresh:!1}).catch((t=>{console.warn(`ReactiveRemoteStore: Background fetch failed for ${e}:`,t)}));return{data:r,loading:t?.isLoading??void 0===r,error:t?.error?new Error("Query failed"):void 0,stale:t?.isStale??!0,updated:t?.lastUpdated??0}}}read(e){const t=this.buildKey("read",e);this.querySubscriptions.has(t)||this.cache.registerQuery(t,(async()=>await this.baseStore.read(e)));const r=this.createSelector(t),a=this.getOrCreateSubscription(t,"read",e,r,(e=>e===t));return{value:a.cachedSelector,onValueChange:a.cachedSubscribe}}createPagedSelector(t,r,a){let s=r;const i=this,o={next:async()=>{const e=s.page||1,r=i.buildKey(t.split(":")[0],s),o=i.cache.peek(r);if(o&&e<o.page.pages){const r={...s,page:e+1},o=i.buildKey(t.split(":")[0],r);s=r,i.querySubscriptions.has(o)||i.cache.registerQuery(o,(()=>a(r))),await i.cache.get(o,{waitForFresh:!0})}},previous:async()=>{const e=s.page||1;if(e>1){const r={...s,page:e-1},o=i.buildKey(t.split(":")[0],r);s=r,i.querySubscriptions.has(o)||i.cache.registerQuery(o,(()=>a(r))),await i.cache.get(o,{waitForFresh:!0})}},fetch:async e=>{const r={...s,page:e},o=i.buildKey(t.split(":")[0],r);s=r,i.querySubscriptions.has(o)||i.cache.registerQuery(o,(()=>a(r))),await i.cache.get(o,{waitForFresh:!0})}};return()=>{const r=this.buildKey(t.split(":")[0],s),a=this.cache.getStats().entries.find((e=>e.key===r)),i=this.cache.peek(r);a?.isStale&&this.cache.get(r,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background refetch failed for ${r}:`,e)})),void 0!==i&&this.cache.has(r)||this.cache.get(r,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background fetch failed for ${r}:`,e)}));const c=s.page||1;return{page:i,loading:a?.isLoading??void 0===i,error:a?.error?e.fromError(new Error("Query failed"),"query"):void 0,stale:a?.isStale??!0,updated:a?.lastUpdated??0,hasNext:!!i&&c<i.page.pages,hasPrevious:c>1,...o}}}setupPagedQuery(e,t,r){const a=this.buildKey(e,t);this.querySubscriptions.has(a)||this.cache.registerQuery(a,(async()=>r(t)));const s=this.createPagedSelector(a,t,r),i=this.getOrCreateSubscription(a,e,t,s,(t=>t.startsWith(`${e}:`)));return{value:i.cachedSelector,onValueChange:i.cachedSubscribe}}list(e){return this.setupPagedQuery("list",e,this.baseStore.list.bind(this.baseStore))}find(e){return this.setupPagedQuery("find",e,this.baseStore.find.bind(this.baseStore))}async invalidateQueries(e){if(this.correlator){const t=Array.from(this.querySubscriptions.entries()).map((([e,t])=>({queryKey:e,operation:t.operation,params:t.params}))),r=this.correlator(e,t).map((e=>this.cache.invalidate(e)));await Promise.all(r)}else await this.cache.invalidatePattern(/^list:/),await this.cache.invalidatePattern(/^find:/)}handleStoreEvent(e){if(console.log("ReactiveRemoteStore: Received store event:",e),this.storeEventCorrelator){const t=Array.from(this.querySubscriptions.entries()).map((([e,t])=>({queryKey:e,operation:t.operation,params:t.params})));console.log("ReactiveRemoteStore: Active queries:",t);const r=this.storeEventCorrelator(e,t);console.log("ReactiveRemoteStore: Queries to invalidate:",r),r.forEach((e=>this.cache.invalidate(e)))}else console.warn("ReactiveRemoteStore: handleStoreEvent called without _storeEventCorrelator.")}async create(e){try{const t=await this.baseStore.create(e);return t&&(this.cache.setData(this.buildKey("read",{id:t.id}),t),await this.invalidateQueries({operation:"create",params:e})),t}catch(e){throw console.error("ReactiveRemoteStore: Create operation failed:",e),e}}async update(e){try{const t=await this.baseStore.update(e);return t&&await this.invalidateQueries({operation:"update",params:e}),t}catch(e){throw console.error("ReactiveRemoteStore: Update operation failed:",e),e}}async delete(e){try{await this.baseStore.delete(e),await this.invalidateQueries({operation:"delete",params:e})}catch(e){throw console.error("ReactiveRemoteStore: Delete operation failed:",e),e}}async notify(e){return this.baseStore.notify(e)}async stream(e,t){return this.baseStore.stream(e,t)}async upload(e){try{const t=await this.baseStore.upload(e);return t&&(this.cache.setData(this.buildKey("read",{id:t.id}),t),await this.invalidateQueries({operation:"upload",params:e})),t}catch(e){throw console.error("ReactiveRemoteStore: Upload operation failed:",e),e}}async refresh(e,t){const r=this.buildKey(e,t);return this.cache.refresh(r)}prefetch(e,t){const r=this.buildKey(e,t);this.cache.prefetch(r).catch((e=>{console.warn(`ReactiveRemoteStore: Prefetch failed for ${r}:`,e)}))}async invalidate(e,t){const r=this.buildKey(e,t);await this.cache.invalidate(r)}async invalidateAll(){const e=Array.from(this.querySubscriptions.keys()).map((e=>this.cache.invalidate(e)));await Promise.all(e)}getStats(){return{...this.cache.getStats(),activeSubscriptions:this.querySubscriptions.size}}destroy(){this.querySubscriptions.forEach((e=>{e.unsubscribeCallbacks.forEach((e=>e()))})),this.querySubscriptions.clear(),this.keyCache=new WeakMap,this.unsubscribeFromBaseStore&&this.unsubscribeFromBaseStore()}},exports.StoreError=e,exports.hash=r;
+"use strict";var e=require("./store"),t=require("./hash"),r=require("./error"),o=require("./types");Object.keys(e).forEach((function(t){"default"===t||Object.prototype.hasOwnProperty.call(exports,t)||Object.defineProperty(exports,t,{enumerable:!0,get:function(){return e[t]}})})),Object.keys(t).forEach((function(e){"default"===e||Object.prototype.hasOwnProperty.call(exports,e)||Object.defineProperty(exports,e,{enumerable:!0,get:function(){return t[e]}})})),Object.keys(r).forEach((function(e){"default"===e||Object.prototype.hasOwnProperty.call(exports,e)||Object.defineProperty(exports,e,{enumerable:!0,get:function(){return r[e]}})})),Object.keys(o).forEach((function(e){"default"===e||Object.prototype.hasOwnProperty.call(exports,e)||Object.defineProperty(exports,e,{enumerable:!0,get:function(){return o[e]}})}));

package/index.mjs

@@ -1 +1 @@
-var e=class e extends Error{code;status;data;isRetryable;originalError;constructor(e,t){super(e.message),this.name="StoreError",this.code=e.code,this.status=e.status,this.data=e.data,this.isRetryable=e.isRetryable,this.originalError=t}static fromError(t,r){if(t.isAbort||"AbortError"===t.name)return new e({code:"ABORTED",message:"Request was cancelled",isRetryable:!1},t);if("NetworkError"===t.name||!navigator.onLine)return new e({code:"NETWORK_ERROR",message:"Network connection failed. Please check your internet connection.",isRetryable:!0},t);if(t.status)switch(t.status){case 400:return new e({code:"VALIDATION_ERROR",message:t.message||"Invalid request data",status:400,data:t.data,isRetryable:!1},t);case 401:return new e({code:"UNAUTHORIZED",message:"Authentication required or invalid credentials",status:401,isRetryable:!1},t);case 403:return new e({code:"FORBIDDEN",message:"Access denied for this resource",status:403,isRetryable:!1},t);case 404:return new e({code:"NOT_FOUND",message:"Resource not found",status:404,isRetryable:!1},t);case 409:return new e({code:"CONFLICT",message:t.message||"Resource conflict occurred",status:409,isRetryable:!1},t);case 429:return new e({code:"RATE_LIMITED",message:"Too many requests. Please try again later.",status:429,isRetryable:!0},t);case 500:case 502:case 503:case 504:return new e({code:"SERVER_ERROR",message:"Server error occurred. Please try again later.",status:t.status,isRetryable:!0},t);default:return new e({code:"HTTP_ERROR",message:t.message||`HTTP ${t.status} error occurred`,status:t.status,isRetryable:t.status>=500},t)}return"TimeoutError"===t.name||"TIMEOUT"===t.code?new e({code:"TIMEOUT",message:"Request timed out. Please try again.",isRetryable:!0},t):new e({code:"UNKNOWN_ERROR",message:t.message||`Unknown error occurred during ${r}`,isRetryable:!0},t)}};function t(e,r=new WeakMap){return void 0===e?"undefined":"function"==typeof e||"symbol"==typeof e?"":"string"==typeof e?`"${e}"`:"number"==typeof e||"boolean"==typeof e||null===e?String(e):Array.isArray(e)?`[${e.map((e=>t(e,r))).join(",")}]`:"object"==typeof e?r.has(e)?'"__circular__"':(r.set(e,!0),`{${Object.keys(e).sort().map((a=>`"${a}":${t(e[a],r)}`)).join(",")}}`):""}function r(e){let r=3421674724,a=2216829733;const s=t(e);for(let e=0;e<s.length;e++){a^=s.charCodeAt(e);const t=Math.imul(a,435),i=Math.imul(a,435)+Math.imul(r,435);a=t>>>0,r=i>>>0}return(r>>>0).toString(16)+(a>>>0).toString(16)}var a=class{constructor(e,t,r,a){if(this.cache=e,this.baseStore=t,this.correlator=r,this.storeEventCorrelator=a,this.storeEventCorrelator){queueMicrotask((async()=>{this.unsubscribeFromBaseStore=await this.baseStore.subscribe("*",this.handleStoreEvent.bind(this))}))}}querySubscriptions=new Map;keyCache=new WeakMap;unsubscribeFromBaseStore;createSubscription(e,t,r,a,s){const i=new Set,o={operation:t,params:r,subscribers:i},c=()=>{const e=a();var r,s;("read"===t?(r=o.result,s=e,r&&s?r.data===s.data&&r.loading===s.loading&&r.stale===s.stale&&(r.error===s.error||r.error?.message===s.error?.message):r===s):function(e,t){return e&&t?e.page===t.page&&e.loading===t.loading&&e.stale===t.stale&&(e.error===t.error||e.error?.message===t.error?.message)&&e.hasNext===t.hasNext&&e.hasPrevious===t.hasPrevious:e===t}(o.result,e))||(o.result=e,i.forEach((e=>{try{e()}catch(e){console.error("ReactiveRemoteStore: Subscriber callback error:",e)}})))};return o.unsubscribeCallbacks=[this.cache.on("cache:fetch:success",(e=>{s(e.key)&&c()})),this.cache.on("cache:fetch:error",(e=>{s(e.key)&&c()})),this.cache.on("cache:data:set",(e=>{s(e.key)&&c()})),this.cache.on("cache:data:invalidate",(e=>{s(e.key)&&c()})),this.cache.on("cache:read:hit",(e=>{s(e.key)&&e.isStale&&c()}))],o.cachedSubscribe=t=>(i.add(t),()=>{i.delete(t),0===i.size&&(o.unsubscribeCallbacks.forEach((e=>e())),this.querySubscriptions.delete(e))}),o.cachedSelector=()=>o.result,o.result=a(),this.querySubscriptions.set(e,o),o}getOrCreateSubscription(e,t,r,a,s){let i=this.querySubscriptions.get(e);return i||(i=this.createSubscription(e,t,r,a,s)),i}buildKey(e,t){if("object"==typeof t&&null!==t&&this.keyCache.has(t))return this.keyCache.get(t);const a=`${e}:${r(t)}`;return"object"==typeof t&&null!==t&&this.keyCache.set(t,a),a}createSelector(e){return()=>{const t=this.cache.getStats().entries.find((t=>t.key===e)),r=this.cache.peek(e);t?.isStale&&this.cache.get(e,{waitForFresh:!1}).catch((t=>{console.warn(`ReactiveRemoteStore: Background refetch failed for ${e}:`,t)})),void 0!==r&&this.cache.has(e)||this.cache.get(e,{waitForFresh:!1}).catch((t=>{console.warn(`ReactiveRemoteStore: Background fetch failed for ${e}:`,t)}));return{data:r,loading:t?.isLoading??void 0===r,error:t?.error?new Error("Query failed"):void 0,stale:t?.isStale??!0,updated:t?.lastUpdated??0}}}read(e){const t=this.buildKey("read",e);this.querySubscriptions.has(t)||this.cache.registerQuery(t,(async()=>await this.baseStore.read(e)));const r=this.createSelector(t),a=this.getOrCreateSubscription(t,"read",e,r,(e=>e===t));return{value:a.cachedSelector,onValueChange:a.cachedSubscribe}}createPagedSelector(t,r,a){let s=r;const i=this,o={next:async()=>{const e=s.page||1,r=i.buildKey(t.split(":")[0],s),o=i.cache.peek(r);if(o&&e<o.page.pages){const r={...s,page:e+1},o=i.buildKey(t.split(":")[0],r);s=r,i.querySubscriptions.has(o)||i.cache.registerQuery(o,(()=>a(r))),await i.cache.get(o,{waitForFresh:!0})}},previous:async()=>{const e=s.page||1;if(e>1){const r={...s,page:e-1},o=i.buildKey(t.split(":")[0],r);s=r,i.querySubscriptions.has(o)||i.cache.registerQuery(o,(()=>a(r))),await i.cache.get(o,{waitForFresh:!0})}},fetch:async e=>{const r={...s,page:e},o=i.buildKey(t.split(":")[0],r);s=r,i.querySubscriptions.has(o)||i.cache.registerQuery(o,(()=>a(r))),await i.cache.get(o,{waitForFresh:!0})}};return()=>{const r=this.buildKey(t.split(":")[0],s),a=this.cache.getStats().entries.find((e=>e.key===r)),i=this.cache.peek(r);a?.isStale&&this.cache.get(r,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background refetch failed for ${r}:`,e)})),void 0!==i&&this.cache.has(r)||this.cache.get(r,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background fetch failed for ${r}:`,e)}));const c=s.page||1;return{page:i,loading:a?.isLoading??void 0===i,error:a?.error?e.fromError(new Error("Query failed"),"query"):void 0,stale:a?.isStale??!0,updated:a?.lastUpdated??0,hasNext:!!i&&c<i.page.pages,hasPrevious:c>1,...o}}}setupPagedQuery(e,t,r){const a=this.buildKey(e,t);this.querySubscriptions.has(a)||this.cache.registerQuery(a,(async()=>r(t)));const s=this.createPagedSelector(a,t,r),i=this.getOrCreateSubscription(a,e,t,s,(t=>t.startsWith(`${e}:`)));return{value:i.cachedSelector,onValueChange:i.cachedSubscribe}}list(e){return this.setupPagedQuery("list",e,this.baseStore.list.bind(this.baseStore))}find(e){return this.setupPagedQuery("find",e,this.baseStore.find.bind(this.baseStore))}async invalidateQueries(e){if(this.correlator){const t=Array.from(this.querySubscriptions.entries()).map((([e,t])=>({queryKey:e,operation:t.operation,params:t.params}))),r=this.correlator(e,t).map((e=>this.cache.invalidate(e)));await Promise.all(r)}else await this.cache.invalidatePattern(/^list:/),await this.cache.invalidatePattern(/^find:/)}handleStoreEvent(e){if(console.log("ReactiveRemoteStore: Received store event:",e),this.storeEventCorrelator){const t=Array.from(this.querySubscriptions.entries()).map((([e,t])=>({queryKey:e,operation:t.operation,params:t.params})));console.log("ReactiveRemoteStore: Active queries:",t);const r=this.storeEventCorrelator(e,t);console.log("ReactiveRemoteStore: Queries to invalidate:",r),r.forEach((e=>this.cache.invalidate(e)))}else console.warn("ReactiveRemoteStore: handleStoreEvent called without _storeEventCorrelator.")}async create(e){try{const t=await this.baseStore.create(e);return t&&(this.cache.setData(this.buildKey("read",{id:t.id}),t),await this.invalidateQueries({operation:"create",params:e})),t}catch(e){throw console.error("ReactiveRemoteStore: Create operation failed:",e),e}}async update(e){try{const t=await this.baseStore.update(e);return t&&await this.invalidateQueries({operation:"update",params:e}),t}catch(e){throw console.error("ReactiveRemoteStore: Update operation failed:",e),e}}async delete(e){try{await this.baseStore.delete(e),await this.invalidateQueries({operation:"delete",params:e})}catch(e){throw console.error("ReactiveRemoteStore: Delete operation failed:",e),e}}async notify(e){return this.baseStore.notify(e)}async stream(e,t){return this.baseStore.stream(e,t)}async upload(e){try{const t=await this.baseStore.upload(e);return t&&(this.cache.setData(this.buildKey("read",{id:t.id}),t),await this.invalidateQueries({operation:"upload",params:e})),t}catch(e){throw console.error("ReactiveRemoteStore: Upload operation failed:",e),e}}async refresh(e,t){const r=this.buildKey(e,t);return this.cache.refresh(r)}prefetch(e,t){const r=this.buildKey(e,t);this.cache.prefetch(r).catch((e=>{console.warn(`ReactiveRemoteStore: Prefetch failed for ${r}:`,e)}))}async invalidate(e,t){const r=this.buildKey(e,t);await this.cache.invalidate(r)}async invalidateAll(){const e=Array.from(this.querySubscriptions.keys()).map((e=>this.cache.invalidate(e)));await Promise.all(e)}getStats(){return{...this.cache.getStats(),activeSubscriptions:this.querySubscriptions.size}}destroy(){this.querySubscriptions.forEach((e=>{e.unsubscribeCallbacks.forEach((e=>e()))})),this.querySubscriptions.clear(),this.keyCache=new WeakMap,this.unsubscribeFromBaseStore&&this.unsubscribeFromBaseStore()}};export{a as ReactiveRemoteStore,e as StoreError,r as hash};
+export*from"./store";export*from"./hash";export*from"./error";export*from"./types";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-remote-store",
-  "version": "1.1.0",
+  "version": "1.2.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": "2.1.0",
+    "@asaidimu/utils-cache": "2.1.1",
     "eventsource": "^4.0.0"
   },
   "exports": {