@braine/quantum-query 1.2.5 → 1.2.6

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import React, { ReactNode } from 'react';
 
-declare function subscribe(store: object, callback: (target: any, prop: any, value: any) => void): () => boolean;
+declare function subscribe(store: object, callback: (target: object, prop: string | symbol, value: unknown) => void): () => boolean;
 declare function createState<T extends object>(initialState: T): T;
 
 interface StorageAdapter {
@@ -93,141 +93,156 @@ declare function getPromiseState(promise: Promise<any>): {
     error: any;
 };
 
-/**
- * Generic Schema Interface
- * Compatible with Zod, Valibot, ArkType, etc.
- */
-interface Schema<T> {
-    parse: (data: unknown) => T;
-}
-interface QueryClientConfig {
-    defaultStaleTime?: number;
-    defaultCacheTime?: number;
-}
 /**
  * Middleware Plugin Interface
  */
 interface QueryPlugin {
     name: string;
-    onFetchStart?: (queryKey: any[]) => void;
-    onFetchSuccess?: (queryKey: any[], data: any) => void;
-    onFetchError?: (queryKey: any[], error: Error) => void;
-    onInvalidate?: (queryKey: any[]) => void;
-    onQueryUpdated?: (queryKey: any[], data: any) => void;
+    onFetchStart?: (queryKey: unknown[]) => void;
+    onFetchSuccess?: (queryKey: unknown[], data: unknown) => void;
+    onFetchError?: (queryKey: unknown[], error: Error) => void;
+    onInvalidate?: (queryKey: unknown[]) => void;
+    onQueryUpdated?: (queryKey: unknown[], data: unknown) => void;
+}
+interface InfiniteData<T> {
+    pages: T[];
+    pageParams: unknown[];
 }
 
 /**
- * Micro-Signals with Batching (Zero Dependency Reactivity)
+ * Micro-Signals (Powered by @preact/signals-core)
  *
- * A minimal implementation of the Signals pattern with micro-batching for O(1) state updates.
- * Uses queueMicrotask to coalesce multiple updates into a single notification cycle.
+ * Industry-standard ultra-fast fine-grained reactivity.
+ * API adapted to match original interface for backward compatibility.
  */
+
 interface Signal<T> {
     get: () => T;
     set: (value: T) => void;
     subscribe: (fn: (value: T) => void) => () => void;
 }
 
-interface CacheEntry<T = any> {
-    data: T;
+type QueryStatus$1 = 'pending' | 'success' | 'error';
+type FetchDirection$1 = 'initial' | 'next' | 'previous' | 'idle';
+interface QueryKey {
+    key: readonly unknown[];
+    params?: Record<string, unknown>;
+}
+type QueryKeyInput = readonly unknown[] | QueryKey;
+interface CacheEntry<T = unknown> {
+    data: T | undefined;
+    status: QueryStatus$1;
+    error: Error | null;
+    isFetching: boolean;
+    fetchDirection: FetchDirection$1;
     timestamp: number;
     staleTime: number;
     cacheTime: number;
-    key: any[];
+    key: QueryKeyInput;
+    tags?: string[];
+    isInvalidated?: boolean;
 }
-interface QueryKey {
-    key: any[];
-    params?: Record<string, any>;
+
+type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
+interface MutationState<TData = unknown, TVariables = unknown, TContext = unknown> {
+    data: TData | undefined;
+    error: Error | null;
+    variables: TVariables | undefined;
+    context: TContext | undefined;
+    status: MutationStatus;
+    submittedAt: number;
 }
-type QueryKeyInput = any[] | QueryKey;
+declare class MutationCache {
+    private mutations;
+    private mutationKeys;
+    /**
+     * Get or Create a Signal for a specific mutation instance (ID)
+     */
+    getSignal: <TData, TVariables, TContext>(id: string) => Signal<MutationState<TData, TVariables, TContext>>;
+    /**
+     * Register a mutation ID with a Key (for tracking shared keys)
+     */
+    register: (id: string, key?: unknown[]) => void;
+    /**
+     * Unregister cleanup
+     */
+    unregister: (id: string, key?: unknown[]) => void;
+    notify: <TData, TVariables, TContext>(id: string, state: Partial<MutationState<TData, TVariables, TContext>>) => void;
+    /**
+     * Get number of mutations currently pending
+     */
+    isMutating: (filters?: {
+        mutationKey?: unknown[];
+    }) => number;
+}
+
 declare class QueryCache {
-    private signals;
-    private gcInterval;
+    private storage;
+    private remotes;
+    mutationCache: MutationCache;
+    private pluginManager;
     private readonly defaultStaleTime;
     private readonly defaultCacheTime;
     constructor(config?: {
-        enableGC?: boolean;
+        defaultStaleTime?: number;
+        defaultCacheTime?: number;
     });
     /**
-     * Generate cache key from query key array
-     */
-    private generateKey;
-    /**
-     * Get data (wrapper around signal.get)
+     * Get data from storage
      */
     get: <T>(queryKey: QueryKeyInput) => T | undefined;
     /**
-     * Get Signal for a key (Low level API for hooks)
-     * Automatically creates a signal if one doesn't exist
+     * Get Signal for reactivity (used by hooks)
      */
     getSignal: <T>(queryKey: QueryKeyInput) => Signal<CacheEntry<T> | undefined>;
     /**
-     * Check if data is stale
-     */
-    isStale: (queryKey: QueryKeyInput) => boolean;
-    /**
-     * Set cached data (updates signal)
+     * Set data manually (Optimistic updates / Prefetch)
      */
     set: <T>(queryKey: QueryKeyInput, data: T, options?: {
         staleTime?: number;
         cacheTime?: number;
+        fetchDirection?: FetchDirection$1;
+        tags?: string[];
     }) => void;
-    private deduplicationCache;
-    private plugins;
-    /**
-     * Register a middleware plugin
-     */
-    use: (plugin: QueryPlugin) => this;
-    /**
-     * Fetch data with deduplication.
-     * If a request for the same key is already in flight, returns the existing promise.
-     */
-    fetch: <T>(queryKey: QueryKeyInput, fn: () => Promise<T>) => Promise<T>;
     /**
-     * Invalidate all queries
+     * Restore cache entry (Hydration)
      */
-    invalidateAll: () => void;
+    restore: (queryKey: QueryKeyInput, entry: CacheEntry<any>) => void;
     /**
-     * Remove a specific query from cache
+     * Fetch data (Orchestration)
      */
-    remove: (queryKey: QueryKeyInput) => void;
+    fetch: <T>(queryKey: QueryKeyInput, fn: (context: {
+        signal?: AbortSignal;
+    }) => Promise<T>, options?: {
+        fetchDirection?: FetchDirection$1;
+        signal?: AbortSignal;
+        retry?: number | boolean;
+        retryDelay?: number | ((attemptIndex: number) => number);
+    }) => Promise<T>;
     /**
-     * Invalidate queries matching the key prefix
-     * Marks them as undefined to trigger refetches without breaking subscriptions
+     * Invalidate queries
      */
     invalidate: (queryKey: QueryKeyInput) => void;
-    /**
-     * Remove all cache entries
-     */
+    invalidateTags: (tags: string[]) => void;
+    use: (plugin: QueryPlugin) => this;
+    isStale: (queryKey: QueryKeyInput) => boolean;
+    getAll: () => Map<string, CacheEntry<unknown>>;
+    snapshot: () => Map<string, Signal<CacheEntry<unknown> | undefined>>;
     clear: () => void;
-    /**
-     * Prefetch data (same as set but explicit intent)
-     */
+    remove: (key: QueryKeyInput) => void;
     prefetch: <T>(queryKey: QueryKeyInput, data: T, options?: {
         staleTime?: number;
         cacheTime?: number;
     }) => void;
-    /**
-     * Garbage collection - remove expired entries
-     */
-    private startGarbageCollection;
-    /**
-     * Stop garbage collection
-     */
     destroy: () => void;
-    /**
-     * Get cache stats (for debugging)
-     */
     getStats: () => {
         size: number;
         keys: string[];
     };
-    /**
-     * Get all entries (wrapper for DevTools)
-     */
-    getAll: () => Map<string, CacheEntry>;
+    getSnapshot: () => Map<string, Signal<CacheEntry<unknown> | undefined>>;
+    invalidateAll: () => void;
+    private normalizeKey;
 }
-declare const queryCache: QueryCache;
 
 /**
  * Pagination Hook
@@ -240,6 +255,7 @@ interface UsePaginatedQueryOptions<T> {
     staleTime?: number;
     cacheTime?: number;
     enabled?: boolean;
+    retry?: number | boolean;
 }
 interface PaginatedQueryResult<T> {
     data: T | undefined;
@@ -254,75 +270,70 @@ interface PaginatedQueryResult<T> {
     hasPrevious: boolean;
     refetch: () => Promise<void>;
 }
-declare function usePaginatedQuery<T>({ queryKey, queryFn, pageSize, staleTime, cacheTime, enabled }: UsePaginatedQueryOptions<T>): PaginatedQueryResult<T>;
+declare function usePaginatedQuery<T>({ queryKey, queryFn, pageSize, staleTime, cacheTime, enabled, retry }: UsePaginatedQueryOptions<T>): PaginatedQueryResult<T>;
 
 /**
  * useQuery Hook
  * Base query hook with stale-while-revalidate and background refetching
+ *
+ * Refactored to use QueryObserver (Clean Architecture)
  */
 
-interface UseQueryOptions<T> {
-    queryKey: any[];
-    queryFn: () => Promise<unknown>;
-    schema?: Schema<T>;
+interface UseQueryOptions<T, TData = T> {
+    queryKey: unknown[];
+    queryFn: (context?: {
+        signal?: AbortSignal;
+    }) => Promise<T>;
     staleTime?: number;
     cacheTime?: number;
     enabled?: boolean;
     refetchOnWindowFocus?: boolean;
-    refetchOnReconnect?: boolean;
-    refetchInterval?: number;
+    retry?: number | boolean;
+    select?: (data: T) => TData;
+    tags?: string[];
 }
-interface QueryResult<T> {
-    data: T | undefined;
-    isLoading: boolean;
+type QueryStatus = 'pending' | 'error' | 'success';
+type FetchDirection = 'idle' | 'fetching';
+interface UseQueryResult<TData, TError = Error> {
+    data: TData | undefined;
+    status: QueryStatus;
+    fetchStatus: FetchDirection;
+    isPending: boolean;
+    isSuccess: boolean;
     isError: boolean;
     isFetching: boolean;
-    isStale: boolean;
-    error: Error | null;
-    refetch: () => Promise<void>;
+    error: TError | null;
+    refetch: () => void;
+    signal: Signal<CacheEntry<any> | undefined>;
 }
-declare function useQuery<T>({ queryKey, queryFn, schema, staleTime, cacheTime, enabled, refetchOnWindowFocus, refetchOnReconnect, refetchInterval }: UseQueryOptions<T>): QueryResult<T>;
+declare function useQuery<T, TData = T, TError = Error>(options: UseQueryOptions<T, TData>): UseQueryResult<TData, TError>;
 
-/**
- * useMutation Hook
- * Handles mutations with optimistic updates and rollback
- */
-interface UseMutationOptions<TData, TVariables, TContext = any> {
+interface UseMutationOptions<TData, TVariables, TContext = unknown> {
     mutationFn: (variables: TVariables) => Promise<TData>;
+    mutationKey?: unknown[];
     onMutate?: (variables: TVariables) => Promise<TContext> | TContext;
     onSuccess?: (data: TData, variables: TVariables, context: TContext | undefined) => void;
     onError?: (error: Error, variables: TVariables, context: TContext | undefined) => void;
     onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables, context: TContext | undefined) => void;
+    invalidatesTags?: string[];
+    optimistic?: {
+        queryKey: unknown[];
+        update: (variables: TVariables, oldData: unknown) => unknown;
+    };
 }
 interface MutationResult<TData, TVariables> {
-    mutate: (variables: TVariables) => Promise<void>;
+    mutate: (variables: TVariables) => void;
     mutateAsync: (variables: TVariables) => Promise<TData>;
     data: TData | undefined;
     error: Error | null;
     isLoading: boolean;
     isError: boolean;
     isSuccess: boolean;
+    isIdle: boolean;
+    status: 'idle' | 'pending' | 'success' | 'error';
     reset: () => void;
 }
-declare function useMutation<TData = unknown, TVariables = void, TContext = any>({ mutationFn, onMutate, onSuccess, onError, onSettled }: UseMutationOptions<TData, TVariables, TContext>): MutationResult<TData, TVariables>;
-declare const optimisticHelpers: {
-    /**
-     * Cancel ongoing queries for a key
-     */
-    cancelQueries(queryKey: any[]): Promise<void>;
-    /**
-     * Get current query data
-     */
-    getQueryData<T>(queryKey: any[]): T | undefined;
-    /**
-     * Set query data (for optimistic updates)
-     */
-    setQueryData<T>(queryKey: any[], updater: T | ((old: T | undefined) => T)): T | undefined;
-    /**
-     * Invalidate queries (trigger refetch)
-     */
-    invalidateQueries(queryKey: any[]): void;
-};
+declare function useMutation<TData = unknown, TVariables = void, TContext = unknown>(options: UseMutationOptions<TData, TVariables, TContext>): MutationResult<TData, TVariables>;
 
 type QueryClient = QueryCache;
 declare const QueryClientProvider: ({ client, children }: {
@@ -334,9 +345,15 @@ declare const useQueryClient: () => QueryClient;
 /**
  * Infinite Query Hook (Reactive)
  * Provides infinite scroll with Signal-based reactivity
+ *
+ * Refactored to "Senior Standards":
+ * - No local state (useReducer removed)
+ * - All state derived from Global QueryCache Signal
+ * - Manual signal updates for aggregate key to track fetching state of pages
  */
+
 interface UseInfiniteQueryOptions<T, TPageParam = any> {
-    queryKey: any[];
+    queryKey: unknown[];
     queryFn: (context: {
         pageParam: TPageParam;
     }) => Promise<T>;
@@ -346,10 +363,7 @@ interface UseInfiniteQueryOptions<T, TPageParam = any> {
     staleTime?: number;
     cacheTime?: number;
     enabled?: boolean;
-}
-interface InfiniteData<T> {
-    pages: T[];
-    pageParams: any[];
+    retry?: number | boolean;
 }
 interface InfiniteQueryResult<T> {
     data: InfiniteData<T> | undefined;
@@ -365,10 +379,53 @@ interface InfiniteQueryResult<T> {
     error: Error | null;
     refetch: () => Promise<void>;
 }
-declare function useInfiniteQuery<T, TPageParam = any>({ queryKey, queryFn, getNextPageParam, getPreviousPageParam, initialPageParam, staleTime, cacheTime, enabled }: UseInfiniteQueryOptions<T, TPageParam>): InfiniteQueryResult<T>;
+declare function useInfiniteQuery<T, TPageParam = any>({ queryKey, queryFn, getNextPageParam, getPreviousPageParam, initialPageParam, staleTime, cacheTime, enabled, retry }: UseInfiniteQueryOptions<T, TPageParam>): InfiniteQueryResult<T>;
+
+interface DehydratedState {
+    queries: Array<{
+        queryKey: unknown[];
+        queryHash: string;
+        state: CacheEntry<unknown>;
+    }>;
+}
+/**
+ * Serialize the query cache for transport.
+ */
+declare function dehydrate(client: QueryCache): DehydratedState;
+/**
+ * Hydrate the query cache from serialized state.
+ */
+declare function hydrate(client: QueryCache, state: DehydratedState): void;
+
+interface HydrationBoundaryProps {
+    state?: DehydratedState;
+    children: React.ReactNode;
+}
+declare function HydrationBoundary({ state, children }: HydrationBoundaryProps): react_jsx_runtime.JSX.Element;
 
-declare function QuantumDevTools(): react_jsx_runtime.JSX.Element;
+interface UseSuspenseQueryOptions<T> extends UseQueryOptions<T> {
+}
+type SuspenseQueryResult<T> = Omit<UseQueryResult<T>, 'data' | 'isLoading' | 'isError' | 'error'> & {
+    data: T;
+};
+declare function useSuspenseQuery<T>(options: UseSuspenseQueryOptions<T>): SuspenseQueryResult<T>;
 
-declare function useQueryCache(): Map<string, CacheEntry<any>>;
+/**
+ * Bridge: Signal -> Proxy (Readonly)
+ *
+ * Creates a reactive proxy object that mirrors a signal's value.
+ * Useful for using Query results inside a Store.
+ */
+type ProxyResult<T> = T extends object ? T : {
+    value: T;
+};
+declare function fromSignal<T>(signal: Signal<T>): ProxyResult<T>;
+/**
+ * Bridge: Proxy -> Signal
+ *
+ * Creates a Signal that updates whenever the accessed parts of the proxy change.
+ * Uses the Proxy's `activeListener` tracking mechanism.
+ */
+declare function toSignal<T>(selector: () => T): Signal<T>;
 
-export { type CacheEntry, type HttpClient, type InfiniteData, type InfiniteQueryResult, type MutationResult, type PaginatedQueryResult, QuantumDevTools, QueryCache, type QueryClient, type QueryClientConfig, QueryClientProvider, type QueryKey, type QueryKeyInput, type QueryResult, type Schema, type UseInfiniteQueryOptions, type UseMutationOptions, type UsePaginatedQueryOptions, type UseQueryOptions, computed, createHttpClient, createState, defineModel, enableDevTools, getPromiseState, handlePromise, isPromise, optimisticHelpers, queryCache, scheduleUpdate, subscribe, unwrapPromise, useInfiniteQuery, useMutation, usePaginatedQuery, useQuery, useQueryCache, useQueryClient, useStore };
+export { type CacheEntry, type HttpClient, HydrationBoundary, type MutationResult, type PaginatedQueryResult, QueryCache, QueryClientProvider, type QueryKey, type QueryKeyInput, type QueryPlugin, type QueryStatus$1 as QueryStatus, type Signal, type SuspenseQueryResult, type UseMutationOptions, type UsePaginatedQueryOptions, type UseQueryOptions, type UseQueryResult, type UseSuspenseQueryOptions, computed, createHttpClient, createState, defineModel, dehydrate, enableDevTools, fromSignal, getPromiseState, handlePromise, hydrate, isPromise, scheduleUpdate, subscribe, toSignal, unwrapPromise, useInfiniteQuery, useMutation, usePaginatedQuery, useQuery, useQueryClient, useStore, useSuspenseQuery };