@braine/quantum-query 1.2.6 → 1.2.8

package/dist/index.d.ts

@@ -1,40 +1,57 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React, { ReactNode } from 'react';
+import React$1, { ReactNode } from 'react';
 
-declare function subscribe(store: object, callback: (target: object, prop: string | symbol, value: unknown) => void): () => boolean;
-declare function createState<T extends object>(initialState: T): T;
+/**
+ * Micro-Signals (Quantum Reactive Engine)
+ *
+ * Industry-standard ultra-fast fine-grained reactivity.
+ * API encapsulated to prevent abstraction leaks and ensure safety.
+ */
+interface Signal<T> {
+    get: () => T;
+    set: (value: T) => void;
+    subscribe: (fn: (value: T) => void) => () => void;
+    isWatched: () => boolean;
+}
 
 interface StorageAdapter {
     getItem(key: string): string | null | Promise<string | null>;
     setItem(key: string, value: string): void | Promise<void>;
     removeItem(key: string): void | Promise<void>;
 }
-type PersistOptions<S> = {
-    key: string;
+interface AtomOptions<T> {
+    key?: string;
     storage?: 'local' | 'session' | StorageAdapter;
-    paths?: (keyof S)[];
+    validate?: (data: unknown) => T;
     debug?: boolean;
-};
-type ModelDefinition<S, A, C> = {
-    state: S;
-    actions?: A & ThisType<S & A & C>;
-    computed?: C & ThisType<S & A & C>;
-    persist?: PersistOptions<S>;
-};
-type ComputedValues<T> = {
-    [K in keyof T]: T[K] extends (...args: any[]) => infer R ? R : never;
-};
-declare function defineModel<S extends object, A extends object, C extends object>(def: ModelDefinition<S, A, C>): S & A & ComputedValues<C>;
+}
+/**
+ * createAtom (Unified Client State)
+ * A Signal with built-in persistence powers.
+ */
+declare function atom<T>(initialValue: T, options?: AtomOptions<T>): Signal<T>;
 
-declare function useStore<T extends object>(store: T): T;
+interface SignalValueProps<T> {
+    signal: Signal<T>;
+    render?: (value: T) => React.ReactNode;
+    children?: (value: T) => React.ReactNode;
+}
+/**
+ * SignalValue
+ * A component that renders the value of a signal directly.
+ * The component subscribes to the signal and updates ONLY itself when the signal changes.
+ * This prevents re-rendering the parent component.
+ *
+ * Usage:
+ * <SignalValue signal={count$} render={count => <span>{count}</span>} />
+ * or
+ * <SignalValue signal={count$}>{count => <span>{count}</span>}</SignalValue>
+ */
+declare function SignalValue<T>({ signal, render, children }: SignalValueProps<T>): react_jsx_runtime.JSX.Element | null;
 
 declare function scheduleUpdate(callback: () => void): void;
 
-declare function enableDevTools(store: any, name?: string): void;
-
-declare function computed<T>(fn: () => T): {
-    readonly value: T;
-};
+declare function enableDevTools(store: object, name?: string): void;
 
 type RetryConfig = {
     retries: number;
@@ -46,7 +63,15 @@ type CacheConfig = {
     ttl: number;
     force?: boolean;
 };
-type HttpClient$1 = any;
+interface HttpClient {
+    get: <T>(url: string, config?: RequestConfig<T>) => Promise<T>;
+    post: <T>(url: string, data?: unknown, config?: RequestConfig<T>) => Promise<T>;
+    put: <T>(url: string, data?: unknown, config?: RequestConfig<T>) => Promise<T>;
+    delete: <T>(url: string, config?: RequestConfig<T>) => Promise<T>;
+    patch: <T>(url: string, data?: unknown, config?: RequestConfig<T>) => Promise<T>;
+    request: <T>(url: string, config?: RequestConfig<T>) => Promise<T>;
+    config: HttpClientConfig;
+}
 type HttpClientConfig = {
     baseURL?: string;
     headers?: Record<string, string>;
@@ -54,7 +79,7 @@ type HttpClientConfig = {
     retry?: number | RetryConfig;
     auth?: {
         getToken: () => string | Promise<string | null>;
-        onTokenExpired: (client: HttpClient$1) => Promise<string | null>;
+        onTokenExpired: (client: HttpClient) => Promise<string | null>;
         onAuthFailed?: () => void;
     };
     interceptors?: {
@@ -66,33 +91,38 @@ type Validator<T> = {
     parse?: (data: unknown) => T;
     validateSync?: (data: unknown) => T;
 };
-type RequestConfig<T> = RequestInit & {
+type RequestConfig<T> = Omit<RequestInit, 'cache'> & {
     schema?: Validator<T> | undefined;
     timeout?: number | undefined;
     retry?: number | RetryConfig | undefined;
-    cache?: CacheConfig;
+    cache?: CacheConfig | RequestCache;
 };
 
-type HttpClient = {
-    get: <T>(url: string, config?: RequestConfig<T>) => Promise<T>;
-    post: <T>(url: string, data?: unknown, config?: RequestConfig<T>) => Promise<T>;
-    put: <T>(url: string, data?: unknown, config?: RequestConfig<T>) => Promise<T>;
-    delete: <T>(url: string, config?: RequestConfig<T>) => Promise<T>;
-    patch: <T>(url: string, data?: unknown, config?: RequestConfig<T>) => Promise<T>;
-    request: <T>(url: string, config?: RequestConfig<T>) => Promise<T>;
-    config: HttpClientConfig;
-};
 declare function createHttpClient(config: HttpClientConfig): HttpClient;
 
-declare function isPromise(value: any): value is Promise<any>;
-declare function handlePromise(promise: Promise<any>, triggerUpdate: () => void): void;
-declare function unwrapPromise(promise: Promise<any>): any;
-declare function getPromiseState(promise: Promise<any>): {
+declare function isPromise(value: unknown): value is Promise<unknown>;
+declare function handlePromise(promise: Promise<unknown>, triggerUpdate: () => void): void;
+declare function unwrapPromise(promise: Promise<unknown>): unknown;
+declare function getPromiseState(promise: Promise<unknown>): {
     status: "pending" | "fulfilled" | "rejected";
-    value: any;
-    error: any;
+    value: unknown;
+    error: unknown;
 };
 
+/**
+ * Generic Schema Interface
+ * Compatible with Zod, Valibot, ArkType, etc.
+ */
+interface Schema<T> {
+    parse: (data: unknown) => T;
+}
+interface QueryClientConfig {
+    defaultStaleTime?: number;
+    defaultCacheTime?: number;
+    defaultSchema?: Schema<unknown>;
+    enableGC?: boolean;
+    maxCacheSize?: number;
+}
 /**
  * Middleware Plugin Interface
  */
@@ -109,21 +139,8 @@ interface InfiniteData<T> {
     pageParams: unknown[];
 }
 
-/**
- * Micro-Signals (Powered by @preact/signals-core)
- *
- * 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;
-}
-
-type QueryStatus$1 = 'pending' | 'success' | 'error';
-type FetchDirection$1 = 'initial' | 'next' | 'previous' | 'idle';
+type QueryStatus = 'pending' | 'success' | 'error';
+type FetchDirection = 'initial' | 'next' | 'previous' | 'idle';
 interface QueryKey {
     key: readonly unknown[];
     params?: Record<string, unknown>;
@@ -131,10 +148,10 @@ interface QueryKey {
 type QueryKeyInput = readonly unknown[] | QueryKey;
 interface CacheEntry<T = unknown> {
     data: T | undefined;
-    status: QueryStatus$1;
+    status: QueryStatus;
     error: Error | null;
     isFetching: boolean;
-    fetchDirection: FetchDirection$1;
+    fetchDirection: FetchDirection;
     timestamp: number;
     staleTime: number;
     cacheTime: number;
@@ -176,17 +193,15 @@ declare class MutationCache {
     }) => number;
 }
 
-declare class QueryCache {
+declare class QueryClient {
     private storage;
     private remotes;
     mutationCache: MutationCache;
     private pluginManager;
     private readonly defaultStaleTime;
     private readonly defaultCacheTime;
-    constructor(config?: {
-        defaultStaleTime?: number;
-        defaultCacheTime?: number;
-    });
+    private readonly defaultSchema?;
+    constructor(config?: QueryClientConfig);
     /**
      * Get data from storage
      */
@@ -201,23 +216,25 @@ declare class QueryCache {
     set: <T>(queryKey: QueryKeyInput, data: T, options?: {
         staleTime?: number;
         cacheTime?: number;
-        fetchDirection?: FetchDirection$1;
+        fetchDirection?: FetchDirection;
         tags?: string[];
     }) => void;
     /**
      * Restore cache entry (Hydration)
      */
-    restore: (queryKey: QueryKeyInput, entry: CacheEntry<any>) => void;
+    restore: (queryKey: QueryKeyInput, entry: CacheEntry<unknown>) => void;
     /**
      * Fetch data (Orchestration)
      */
     fetch: <T>(queryKey: QueryKeyInput, fn: (context: {
         signal?: AbortSignal;
     }) => Promise<T>, options?: {
-        fetchDirection?: FetchDirection$1;
+        fetchDirection?: FetchDirection;
         signal?: AbortSignal;
         retry?: number | boolean;
         retryDelay?: number | ((attemptIndex: number) => number);
+        tags?: string[];
+        schema?: Schema<T>;
     }) => Promise<T>;
     /**
      * Invalidate queries
@@ -227,7 +244,7 @@ declare class QueryCache {
     use: (plugin: QueryPlugin) => this;
     isStale: (queryKey: QueryKeyInput) => boolean;
     getAll: () => Map<string, CacheEntry<unknown>>;
-    snapshot: () => Map<string, Signal<CacheEntry<unknown> | undefined>>;
+    snapshot: () => Map<string, CacheEntry<unknown>>;
     clear: () => void;
     remove: (key: QueryKeyInput) => void;
     prefetch: <T>(queryKey: QueryKeyInput, data: T, options?: {
@@ -238,10 +255,14 @@ declare class QueryCache {
     getStats: () => {
         size: number;
         keys: string[];
+        tags: number;
     };
-    getSnapshot: () => Map<string, Signal<CacheEntry<unknown> | undefined>>;
+    getSnapshot: () => Map<string, CacheEntry<unknown>>;
     invalidateAll: () => void;
     private normalizeKey;
+    private isCacheEntry;
+    debugSet: <T>(key: QueryKeyInput, data: T) => void;
+    debugInvalidate: (key: QueryKeyInput) => void;
 }
 
 /**
@@ -272,41 +293,42 @@ interface 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, TData = T> {
-    queryKey: unknown[];
+interface QueryObserverOptions<T, TData = T> {
+    queryKey: QueryKeyInput;
     queryFn: (context?: {
         signal?: AbortSignal;
-    }) => Promise<T>;
+    }) => Promise<unknown>;
+    schema?: Schema<T>;
     staleTime?: number;
     cacheTime?: number;
     enabled?: boolean;
     refetchOnWindowFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    refetchInterval?: number;
+    tags?: string[];
     retry?: number | boolean;
+    retryDelay?: number | ((attemptIndex: number) => number);
     select?: (data: T) => TData;
-    tags?: string[];
 }
-type QueryStatus = 'pending' | 'error' | 'success';
-type FetchDirection = 'idle' | 'fetching';
-interface UseQueryResult<TData, TError = Error> {
+interface QueryObserverResult<TData> {
     data: TData | undefined;
-    status: QueryStatus;
-    fetchStatus: FetchDirection;
-    isPending: boolean;
-    isSuccess: boolean;
+    isLoading: boolean;
     isError: boolean;
+    isSuccess: boolean;
+    isPending: boolean;
     isFetching: boolean;
-    error: TError | null;
-    refetch: () => void;
-    signal: Signal<CacheEntry<any> | undefined>;
+    isStale: boolean;
+    error: Error | null;
+    status: QueryStatus;
+    refetch: () => Promise<void>;
+}
+
+interface UseQueryOptions<T, TData = T> extends QueryObserverOptions<T, TData> {
+}
+interface UseQueryResult<TData, T> extends QueryObserverResult<TData> {
+    signal: Signal<QueryObserverResult<TData>>;
 }
-declare function useQuery<T, TData = T, TError = Error>(options: UseQueryOptions<T, TData>): UseQueryResult<TData, TError>;
+declare function useQuery<T, TData = T>(options: UseQueryOptions<T, TData>): UseQueryResult<TData, T>;
 
 interface UseMutationOptions<TData, TVariables, TContext = unknown> {
     mutationFn: (variables: TVariables) => Promise<TData>;
@@ -335,24 +357,13 @@ interface MutationResult<TData, TVariables> {
 }
 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 }: {
     client: QueryClient;
-    children: ReactNode;
+    children: ReactNode | undefined;
 }) => react_jsx_runtime.JSX.Element;
 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> {
+interface InfiniteQueryObserverOptions<T, TPageParam = unknown> {
     queryKey: unknown[];
     queryFn: (context: {
         pageParam: TPageParam;
@@ -363,23 +374,27 @@ interface UseInfiniteQueryOptions<T, TPageParam = any> {
     staleTime?: number;
     cacheTime?: number;
     enabled?: boolean;
+    refetchOnWindowFocus?: boolean;
+    refetchOnReconnect?: boolean;
     retry?: number | boolean;
 }
-interface InfiniteQueryResult<T> {
+interface InfiniteQueryObserverResult<T> {
     data: InfiniteData<T> | undefined;
-    fetchNextPage: () => Promise<void>;
-    fetchPreviousPage: () => Promise<void>;
-    hasNextPage: boolean;
-    hasPreviousPage: boolean;
     isFetching: boolean;
     isFetchingNextPage: boolean;
     isFetchingPreviousPage: boolean;
     isLoading: boolean;
     isError: boolean;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
     error: Error | null;
+    status: 'pending' | 'success' | 'error';
+    fetchNextPage: () => Promise<void>;
+    fetchPreviousPage: () => Promise<void>;
     refetch: () => Promise<void>;
 }
-declare function useInfiniteQuery<T, TPageParam = any>({ queryKey, queryFn, getNextPageParam, getPreviousPageParam, initialPageParam, staleTime, cacheTime, enabled, retry }: UseInfiniteQueryOptions<T, TPageParam>): InfiniteQueryResult<T>;
+
+declare function useInfiniteQuery<T, TPageParam = unknown>(options: InfiniteQueryObserverOptions<T, TPageParam>): InfiniteQueryObserverResult<T>;
 
 interface DehydratedState {
     queries: Array<{
@@ -391,41 +406,36 @@ interface DehydratedState {
 /**
  * Serialize the query cache for transport.
  */
-declare function dehydrate(client: QueryCache): DehydratedState;
+declare function dehydrate(client: QueryClient): DehydratedState;
 /**
  * Hydrate the query cache from serialized state.
  */
-declare function hydrate(client: QueryCache, state: DehydratedState): void;
+declare function hydrate(client: QueryClient, state: DehydratedState): void;
 
 interface HydrationBoundaryProps {
     state?: DehydratedState;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }
 declare function HydrationBoundary({ state, children }: HydrationBoundaryProps): react_jsx_runtime.JSX.Element;
 
 interface UseSuspenseQueryOptions<T> extends UseQueryOptions<T> {
 }
-type SuspenseQueryResult<T> = Omit<UseQueryResult<T>, 'data' | 'isLoading' | 'isError' | 'error'> & {
+type SuspenseQueryResult<T> = Omit<UseQueryResult<T, T>, 'data' | 'isLoading' | 'isError' | 'error'> & {
     data: T;
 };
 declare function useSuspenseQuery<T>(options: UseSuspenseQueryOptions<T>): SuspenseQueryResult<T>;
 
+declare function useQueryStore(): Map<string, CacheEntry<unknown>>;
+
 /**
- * Bridge: Signal -> Proxy (Readonly)
+ * useQuery$ (The Quantum Hook)
  *
- * 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
+ * Returns a reactive SIGNAL of the query result.
+ * Accessing .value (or .get()) inside a tracked context (like <SignalValue>) will update fine-grained.
+ * Accessing it in a standard component render will NOT trigger re-renders when data changes.
  *
- * Creates a Signal that updates whenever the accessed parts of the proxy change.
- * Uses the Proxy's `activeListener` tracking mechanism.
+ * This is the "Zero-Render" primitive.
  */
-declare function toSignal<T>(selector: () => T): Signal<T>;
+declare function useQuery$<T>(options: QueryObserverOptions<T>): Signal<QueryObserverResult<T>>;
 
-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 };
+export { type CacheEntry, HydrationBoundary, type MutationResult, type PaginatedQueryResult, QueryClient, QueryClientProvider, type QueryKey, type QueryKeyInput, type QueryPlugin, type QueryStatus, type Signal, SignalValue, type SuspenseQueryResult, type UseMutationOptions, type UsePaginatedQueryOptions, type UseQueryOptions, type UseQueryResult, type UseSuspenseQueryOptions, atom, createHttpClient, dehydrate, enableDevTools, getPromiseState, handlePromise, hydrate, isPromise, scheduleUpdate, unwrapPromise, useInfiniteQuery, useMutation, usePaginatedQuery, useQuery, useQuery$, useQueryClient, useQueryStore, useSuspenseQuery };