@asaidimu/utils-remote-store 1.0.0

package/index.d.ts

@@ -0,0 +1,574 @@
+import { QueryCache, CacheMetrics } from '../cache/index.js';
+import '../types-DUZGkNEB.js';
+
+interface StoreErrorDetails {
+    code: string;
+    message: string;
+    status?: number;
+    data?: unknown;
+    isRetryable: boolean;
+}
+declare class StoreError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly data?: unknown;
+    readonly isRetryable: boolean;
+    readonly originalError?: Error;
+    constructor(details: StoreErrorDetails, originalError?: Error);
+    static fromError(error: any, operation: string): StoreError;
+}
+
+/**
+ * Represents a paginated response containing a list of records and pagination details.
+ * @template T The type of the records in the page.
+ */
+interface Page<T> {
+    /** The array of records for the current page. */
+    data: T[];
+    /** Pagination metadata. */
+    page: PaginationInfo;
+}
+/**
+ * Represents an event emitted by the store, typically for notifications or state changes.
+ */
+interface StoreEvent {
+    /** The scope of the event, indicating its type and context. Custom scopes are allowed. */
+    scope: string;
+    /** Optional payload carrying data related to the event. */
+    payload?: any;
+}
+/**
+ * Defines the types of mutation operations that can occur.
+ */
+type MutationOperation = 'create' | 'update' | 'delete' | 'upload';
+/**
+ * A correlator function that determines which active queries should be invalidated
+ * based on a mutation operation.
+ * @param mutation An object describing the mutation operation and its parameters.
+ * @param activeQueries An array of currently active queries.
+ * @returns An array of query keys to be invalidated.
+ */
+type Correlator = (mutation: {
+    operation: MutationOperation;
+    params: any;
+}, activeQueries: ActiveQuery[]) => string[];
+/**
+ * A correlator function that determines which active queries should be invalidated
+ * based on a store event.
+ * @param event The StoreEvent that occurred.
+ * @param activeQueries An array of currently active queries.
+ * @returns An array of query keys to be invalidated.
+ */
+type StoreEventCorrelator = (event: StoreEvent, activeQueries: ActiveQuery[]) => string[];
+/**
+ * Defines the core interface for interacting with a remote data store.
+ * @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.
+ */
+interface BaseStore<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>> {
+    /**
+     * Finds records based on provided options, returning a paginated result.
+     * @param options The options for the find operation.
+     * @returns A promise that resolves to a Page of records.
+     */
+    find: (options: TFindOptions) => Promise<Page<T>>;
+    /**
+     * Reads a single record by its identifier or other read options.
+     * @param options The options for the read operation, typically including an ID.
+     * @returns A promise that resolves to the record or undefined if not found.
+     */
+    read: (options: TReadOptions) => Promise<T | undefined>;
+    /**
+     * Lists records based on provided options, returning a paginated result.
+     * @param options The options for the list operation.
+     * @returns A promise that resolves to a Page of records.
+     */
+    list: (options: TListOptions) => Promise<Page<T>>;
+    /**
+     * Deletes a record based on provided options, typically including an ID.
+     * @param options The options for the delete operation.
+     * @returns A promise that resolves when the deletion is complete.
+     */
+    delete: (options: TDeleteOptions) => Promise<void>;
+    /**
+     * Updates an existing record.
+     * @param props 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 not found.
+     */
+    update: (props: {
+        data: Partial<T>;
+        options?: TUpdateOptions;
+    }) => Promise<T | undefined>;
+    /**
+     * Creates a new record.
+     * @param props 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 creation failed.
+     */
+    create: (props: {
+        data: Partial<T>;
+        options?: TCreateOptions;
+    }) => Promise<T | undefined>;
+    /**
+     * Uploads a file associated with a record. Optionally updates the record with upload details.
+     * @param props An object containing the file to upload and optional upload options.
+     * @returns A promise that resolves to the updated record after upload or undefined if upload failed.
+     */
+    upload: (props: {
+        file: File;
+        options?: TUploadOptions;
+    }) => Promise<T | undefined>;
+    /**
+     * Subscribes to store events for a given scope.
+     * @param scope The event scope to subscribe to (e.g., 'todos:created:success', '*').
+     * @param callback The function to call when an event matching the scope is received.
+     * @returns A promise that resolves to an unsubscribe function. Call this function to stop receiving events.
+     */
+    subscribe(scope: string, callback: (event: StoreEvent) => void): Promise<() => void>;
+    /**
+     * Notifies the store of an event, which can then be broadcast to subscribers.
+     * @param event The StoreEvent to notify.
+     * @returns A promise that resolves when the notification has been processed.
+     */
+    notify: (event: StoreEvent) => Promise<void>;
+    /**
+     * Establishes a stream of records based on provided options.
+     * @param options Options for configuring the stream (e.g., batch size, delay, filters).
+     * @param onStreamChange A callback function that is called when the stream's status changes.
+     * @returns An object containing the async iterable stream, a cancel function, and a status getter.
+     */
+    stream: (options: TStreamOptions, onStreamChange: () => void) => {
+        /** An async iterable that yields records as they become available in the stream. */
+        stream: () => AsyncIterable<T>;
+        /** 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';
+    };
+}
+/**
+ * Represents an active query in the cache, used for invalidation correlation.
+ */
+interface ActiveQuery {
+    /** The unique key identifying the query in the cache. */
+    queryKey: string;
+    /** The type of operation this query represents (e.g., 'read', 'list', 'find'). */
+    operation: string;
+    /** The parameters used to make this query. */
+    params: any;
+}
+/**
+ * Represents the result of a single record query.
+ * @template T The type of the data being queried.
+ */
+interface QueryResult<T> {
+    /** The data returned by the query, or undefined if not found or still loading. */
+    data: T | undefined;
+    /** Indicates if the query is currently loading data. */
+    loading: boolean;
+    /** An error object if the query failed, otherwise undefined. */
+    error: Error | undefined;
+    /** Indicates if the cached data is stale and a refetch is needed. */
+    stale: boolean;
+    /** Timestamp of the last update to the data. */
+    updated: number;
+}
+/**
+ * Represents the result of a paginated query (list or find).
+ * @template T The type of the records in the page.
+ */
+interface PagedQueryResult<T> {
+    /** The paginated data, or undefined if not found or still loading. */
+    page: Page<T> | undefined;
+    /** Indicates if the query is currently loading data. */
+    loading: boolean;
+    /** An error object if the query failed, otherwise undefined. */
+    error: StoreError | undefined;
+    /** Indicates if the cached data is stale and a refetch is needed. */
+    stale: boolean;
+    /** Timestamp of the last update to the data. */
+    updated: number;
+    /** True if there is a next page, false otherwise. */
+    hasNext: boolean;
+    /** True if there is a previous page, false otherwise. */
+    hasPrevious: boolean;
+    /** Function to fetch the next page of data. */
+    next: () => Promise<void>;
+    /** Function to fetch the previous page of data. */
+    previous: () => Promise<void>;
+    /** Function to fetch a specific page of data.
+     * @param page The page number to fetch.
+     */
+    fetch: (page: number) => Promise<void>;
+}
+/**
+ * Represents a basic record in the remote store.
+ * All records must have a unique `id` of type string.
+ * Other properties can be of any type.
+ */
+type StoreRecord<BaseProps extends Record<string, unknown> = Record<string, unknown>> = BaseProps;
+/**
+ * Provides pagination information for a collection of records.
+ */
+type PaginationInfo = {
+    /** The current page number (1-based). */
+    number: number;
+    /** The number of items per page. */
+    size: number;
+    /** The total count of items across all pages. */
+    count: number;
+    /** The total number of available pages. */
+    pages: number;
+};
+/**
+ * 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.
+ */
+interface QuerySubscription<T> {
+    /** Callbacks to unsubscribe from cache events. */
+    unsubscribeCallbacks: (() => void)[];
+    /** Set of functions to notify when the query data changes. */
+    subscribers: Set<() => void>;
+    /** A cached function to subscribe to changes for this query. */
+    cachedSubscribe: (callback: () => void) => () => void;
+    /** A cached selector function to get the current query result. */
+    cachedSelector: () => QueryResult<T> | PagedQueryResult<T>;
+    /** The operation type of the query (e.g., 'read', 'list'). */
+    operation: string;
+    /** The parameters for the query. */
+    params: any;
+}
+
+/**
+ * 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 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.
+     */
+    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 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 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: () => 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.
+     */
+    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;
+        metrics: CacheMetrics;
+        hitRate: number;
+        staleHitRate: number;
+        entries: Array<{
+            key: string;
+            lastAccessed: number;
+            lastUpdated: number;
+            accessCount: number;
+            isStale: boolean;
+            isLoading?: boolean;
+            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;
+}
+
+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 };

package/index.js

@@ -0,0 +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=()=>{i.forEach((e=>{try{e()}catch(e){console.error("ReactiveRemoteStore: Subscriber callback error:",e)}}))},c=[this.cache.on("cache:fetch:success",(e=>{s(e.key)&&o()})),this.cache.on("cache:fetch:error",(e=>{s(e.key)&&o()})),this.cache.on("cache:data:set",(e=>{s(e.key)&&o()})),this.cache.on("cache:data:invalidate",(e=>{s(e.key)&&o()})),this.cache.on("cache:read:hit",(e=>{s(e.key)&&e.isStale&&o()}))],n={unsubscribeCallbacks:c,subscribers:i,cachedSubscribe:t=>(i.add(t),()=>{i.delete(t),0===i.size&&(c.forEach((e=>e())),this.querySubscriptions.delete(e))}),cachedSelector:a,operation:t,params:r};return this.querySubscriptions.set(e,n),n}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);return 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)})),{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){return()=>{const s=this.cache.getStats().entries.find((e=>e.key===t)),i=this.cache.peek(t);s?.isStale&&this.cache.get(t,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background refetch failed for ${t}:`,e)})),void 0!==i&&this.cache.has(t)||this.cache.get(t,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background fetch failed for ${t}:`,e)}));const o=r.page||1;return{page:i,loading:s?.isLoading??void 0===i,error:s?.error?e.fromError(new Error("Query failed"),"query"):void 0,stale:s?.isStale??!0,updated:s?.lastUpdated??0,hasNext:!!i&&o<i.page.pages,hasPrevious:o>1,next:async()=>{if(i&&o<i.page.pages){const e={...r,page:o+1},s=this.buildKey(t.split(":")[0],e);this.querySubscriptions.has(s)||this.cache.registerQuery(s,(()=>a(e))),await this.cache.get(s,{waitForFresh:!0})}},previous:async()=>{if(o>1){const e={...r,page:o-1},s=this.buildKey(t.split(":")[0],e);this.querySubscriptions.has(s)||this.cache.registerQuery(s,(()=>a(e))),await this.cache.get(s,{waitForFresh:!0})}},fetch:async e=>{const s={...r,page:e},i=this.buildKey(t.split(":")[0],s);this.querySubscriptions.has(i)||this.cache.registerQuery(i,(()=>a(s))),await this.cache.get(i,{waitForFresh:!0})}}}}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),this.cache.remove(this.buildKey("read",{id:e.id})),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;

package/index.mjs

@@ -0,0 +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=()=>{i.forEach((e=>{try{e()}catch(e){console.error("ReactiveRemoteStore: Subscriber callback error:",e)}}))},c=[this.cache.on("cache:fetch:success",(e=>{s(e.key)&&o()})),this.cache.on("cache:fetch:error",(e=>{s(e.key)&&o()})),this.cache.on("cache:data:set",(e=>{s(e.key)&&o()})),this.cache.on("cache:data:invalidate",(e=>{s(e.key)&&o()})),this.cache.on("cache:read:hit",(e=>{s(e.key)&&e.isStale&&o()}))],n={unsubscribeCallbacks:c,subscribers:i,cachedSubscribe:t=>(i.add(t),()=>{i.delete(t),0===i.size&&(c.forEach((e=>e())),this.querySubscriptions.delete(e))}),cachedSelector:a,operation:t,params:r};return this.querySubscriptions.set(e,n),n}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);return 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)})),{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){return()=>{const s=this.cache.getStats().entries.find((e=>e.key===t)),i=this.cache.peek(t);s?.isStale&&this.cache.get(t,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background refetch failed for ${t}:`,e)})),void 0!==i&&this.cache.has(t)||this.cache.get(t,{waitForFresh:!1}).catch((e=>{console.warn(`ReactiveRemoteStore: Background fetch failed for ${t}:`,e)}));const o=r.page||1;return{page:i,loading:s?.isLoading??void 0===i,error:s?.error?e.fromError(new Error("Query failed"),"query"):void 0,stale:s?.isStale??!0,updated:s?.lastUpdated??0,hasNext:!!i&&o<i.page.pages,hasPrevious:o>1,next:async()=>{if(i&&o<i.page.pages){const e={...r,page:o+1},s=this.buildKey(t.split(":")[0],e);this.querySubscriptions.has(s)||this.cache.registerQuery(s,(()=>a(e))),await this.cache.get(s,{waitForFresh:!0})}},previous:async()=>{if(o>1){const e={...r,page:o-1},s=this.buildKey(t.split(":")[0],e);this.querySubscriptions.has(s)||this.cache.registerQuery(s,(()=>a(e))),await this.cache.get(s,{waitForFresh:!0})}},fetch:async e=>{const s={...r,page:e},i=this.buildKey(t.split(":")[0],s);this.querySubscriptions.has(i)||this.cache.registerQuery(i,(()=>a(s))),await this.cache.get(i,{waitForFresh:!0})}}}}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),this.cache.remove(this.buildKey("read",{id:e.id})),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};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@asaidimu/utils-remote-store",
+  "version": "1.0.0",
+  "description": "A reactive store for remote data, built on top of @asaidimu/utils-cache",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "files": [
+    "./*"
+  ],
+  "dependencies": {
+    "@asaidimu/utils-cache": "2.0.5",
+    "eventsource": "^4.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/npm",
+        {
+          "pkgRoot": "./dist"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md",
+            "package.json"
+          ],
+          "message": "chore(release): Release @asaidimu/utils-remote-store v\n{nextRelease.version} [skip ci]\n\n{nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}