@asaidimu/utils-remote-store 1.3.10 → 1.3.12

package/index.d.cts

@@ -0,0 +1,549 @@
+//#region src/persistence/types.d.ts
+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;
+  };
+}
+//#endregion
+//#region src/cache/types.d.ts
+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"];
+//#endregion
+//#region src/cache/cache.d.ts
+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;
+}
+//#endregion
+//#region src/remote-store/error.d.ts
+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;
+}
+//#endregion
+//#region src/remote-store/types.d.ts
+/**
+ * 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.
+   */
+  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.
+ * 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;
+/**
+ * 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 stable reference to the operations results. */
+  result: QueryResult<T> | PagedQueryResult<T>;
+}
+//#endregion
+//#region src/remote-store/store.d.ts
+/**
+ * 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).
+ */
+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 queryStates;
+  private stableResults;
+  private stablePaginationMethods;
+  private errorCache;
+  private keyCache;
+  private unsubscribeFromBaseStore;
+  private cacheEventCleanups;
+  constructor(cache: QueryCache, baseStore: BaseStore<T, TFindOptions, TReadOptions, TListOptions, TDeleteOptions, TUpdateOptions, TCreateOptions, TUploadOptions, TStreamOptions>, correlator?: Correlator | undefined, storeEventCorrelator?: StoreEventCorrelator | undefined);
+  private setupCacheEventListeners;
+  private handleCacheEvent;
+  private buildKey;
+  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;
+  private invalidateQueries;
+  private handleStoreEvent;
+  create(params: {
+    data: Partial<T>;
+    options?: TCreateOptions;
+  }): Promise<T | undefined>;
+  update(params: {
+    data: Partial<T>;
+    options?: TUpdateOptions;
+  }): Promise<T | undefined>;
+  delete(params: TDeleteOptions): Promise<void>;
+  notify(event: StoreEvent): Promise<void>;
+  stream(options: TStreamOptions, onStreamChange: () => void): {
+    stream: () => AsyncIterable<T>;
+    cancel: () => void;
+    status: () => "active" | "cancelled" | "completed";
+  };
+  subscribe(scope: string, callback: (event: StoreEvent) => void): Promise<() => void>;
+  upload(params: {
+    file: File;
+    options?: TUploadOptions;
+  }): Promise<T | undefined>;
+  refresh(operation: "read", params: TReadOptions): Promise<T | undefined>;
+  refresh(operation: "list", params: TListOptions): Promise<Page<T> | undefined>;
+  refresh(operation: "find", query: TFindOptions): Promise<Page<T> | undefined>;
+  prefetch(operation: "read", params: TReadOptions): void;
+  prefetch(operation: "list", params: TListOptions): void;
+  prefetch(operation: "find", params: TFindOptions): void;
+  invalidate(operation: string, params: any): Promise<void>;
+  invalidateAll(): Promise<void>;
+  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;
+    }>;
+  };
+  destroy(): void;
+}
+//#endregion
+//#region src/remote-store/hash.d.ts
+/**
+ * Computes the FNV-1a 64-bit hash of the given data.
+ * @param {any} data - The data to hash. Can be any type that can be serialized.
+ * @returns {string} The FNV-1a 64-bit hash as a hexadecimal string.
+ */
+declare function hash(data: any): string;
+//#endregion
+export { ActiveQuery, BaseStore, Correlator, MutationOperation, Page, PagedQueryResult, PaginationInfo, QueryResult, QuerySubscription, ReactiveRemoteStore, ResourceName, StoreError, StoreErrorDetails, StoreEvent, StoreEventCorrelator, StoreRecord, StoreResult, hash };