@tanstack/query-core 4.24.10 → 5.0.0-alpha.0

package/src/types.ts

@@ -6,42 +6,66 @@ import type { RetryValue, RetryDelayValue } from './retryer'
 import type { QueryFilters, QueryTypeFilter } from './utils'
 import type { QueryCache } from './queryCache'
 import type { MutationCache } from './mutationCache'
-import type { Logger } from './logger'
+
+export interface Register {
+  // defaultError: Error
+}
+
+export type RegisteredError = Register extends {
+  defaultError: infer TError
+}
+  ? TError
+  : Error
 
 export type QueryKey = readonly unknown[]
 
 export type QueryFunction<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
-> = (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>
+  TPageParam = never,
+> = (context: QueryFunctionContext<TQueryKey, TPageParam>) => T | Promise<T>
 
-export interface QueryFunctionContext<
+export type QueryFunctionContext<
   TQueryKey extends QueryKey = QueryKey,
-  TPageParam = any,
-> {
-  queryKey: TQueryKey
-  signal?: AbortSignal
-  pageParam?: TPageParam
-  meta: QueryMeta | undefined
-}
+  TPageParam = never,
+> = [TPageParam] extends [never]
+  ? {
+      queryKey: TQueryKey
+      signal: AbortSignal
+      meta: QueryMeta | undefined
+    }
+  : {
+      queryKey: TQueryKey
+      signal: AbortSignal
+      pageParam: TPageParam
+      meta: QueryMeta | undefined
+    }
 
 export type InitialDataFunction<T> = () => T | undefined
 
-export type PlaceholderDataFunction<TResult> = () => TResult | undefined
+type NonFunctionGuard<T> = T extends Function ? never : T
+
+export type PlaceholderDataFunction<TQueryData> = (
+  previousData: TQueryData | undefined,
+) => TQueryData | undefined
+
+export type QueriesPlaceholderDataFunction<TQueryData> = () =>
+  | TQueryData
+  | undefined
 
 export type QueryKeyHashFunction<TQueryKey extends QueryKey> = (
   queryKey: TQueryKey,
 ) => string
 
-export type GetPreviousPageParamFunction<TQueryFnData = unknown> = (
+export type GetPreviousPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   firstPage: TQueryFnData,
   allPages: TQueryFnData[],
-) => unknown
+) => TPageParam | undefined
 
-export type GetNextPageParamFunction<TQueryFnData = unknown> = (
+export type GetNextPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   lastPage: TQueryFnData,
   allPages: TQueryFnData[],
-) => unknown
+) => TPageParam | undefined
 
 export interface InfiniteData<TData> {
   pages: TData[]
@@ -56,9 +80,10 @@ export type NetworkMode = 'online' | 'always' | 'offlineFirst'
 
 export interface QueryOptions<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = never,
 > {
   /**
    * If `false`, failed queries will not retry by default.
@@ -69,15 +94,14 @@ export interface QueryOptions<
   retry?: RetryValue<TError>
   retryDelay?: RetryDelayValue<TError>
   networkMode?: NetworkMode
-  cacheTime?: number
-  isDataEqual?: (oldData: TData | undefined, newData: TData) => boolean
-  queryFn?: QueryFunction<TQueryFnData, TQueryKey>
+  gcTime?: number
+  queryFn?: QueryFunction<TQueryFnData, TQueryKey, TPageParam>
   queryHash?: string
   queryKey?: TQueryKey
   queryKeyHashFn?: QueryKeyHashFunction<TQueryKey>
   initialData?: TData | InitialDataFunction<TData>
   initialDataUpdatedAt?: number | (() => number | undefined)
-  behavior?: QueryBehavior<TQueryFnData, TError, TData>
+  behavior?: QueryBehavior<TQueryFnData, TError, TData, TQueryKey>
   /**
    * Set this to `false` to disable structural sharing between query results.
    * Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic.
@@ -86,25 +110,39 @@ export interface QueryOptions<
   structuralSharing?:
     | boolean
     | ((oldData: TData | undefined, newData: TData) => TData)
+  _defaulted?: boolean
+  /**
+   * Additional payload to be stored on each query.
+   * Use this property to pass information that can be used in other places.
+   */
+  meta?: QueryMeta
+  /**
+   * Maximum number of pages to store in the data of an infinite query.
+   */
+  maxPages?: number
+}
+
+export interface DefaultPageParam<TPageParam = unknown> {
+  defaultPageParam: TPageParam
+}
+
+export interface InfiniteQueryPageParamsOptions<
+  TQueryFnData = unknown,
+  TPageParam = unknown,
+> extends DefaultPageParam<TPageParam> {
   /**
    * This function can be set to automatically get the previous cursor for infinite queries.
    * The result will also be used to determine the value of `hasPreviousPage`.
    */
-  getPreviousPageParam?: GetPreviousPageParamFunction<TQueryFnData>
+  getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TQueryFnData>
   /**
    * This function can be set to automatically get the next cursor for infinite queries.
    * The result will also be used to determine the value of `hasNextPage`.
    */
-  getNextPageParam?: GetNextPageParamFunction<TQueryFnData>
-  _defaulted?: boolean
-  /**
-   * Additional payload to be stored on each query.
-   * Use this property to pass information that can be used in other places.
-   */
-  meta?: QueryMeta
+  getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>
 }
 
-export type UseErrorBoundary<
+export type ThrowErrors<
   TQueryFnData,
   TError,
   TQueryData,
@@ -118,11 +156,18 @@ export type UseErrorBoundary<
 
 export interface QueryObserverOptions<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
-> extends QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey> {
+  TPageParam = never,
+> extends QueryOptions<
+    TQueryFnData,
+    TError,
+    TQueryData,
+    TQueryKey,
+    TPageParam
+  > {
   /**
    * Set this to `false` to disable automatic refetching when the query mounts or changes query keys.
    * To refetch the query, use the `refetch` method returned from the `useQuery` instance.
@@ -221,31 +266,23 @@ export interface QueryObserverOptions<
    * If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`).
    * Defaults to `false`.
    */
-  useErrorBoundary?: UseErrorBoundary<
-    TQueryFnData,
-    TError,
-    TQueryData,
-    TQueryKey
-  >
+  throwErrors?: ThrowErrors<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
    * This option can be used to transform or select a part of the data returned by the query function.
    */
   select?: (data: TQueryData) => TData
   /**
-   * If set to `true`, the query will suspend when `status === 'loading'`
+   * If set to `true`, the query will suspend when `status === 'pending'`
    * and throw errors when `status === 'error'`.
    * Defaults to `false`.
    */
   suspense?: boolean
-  /**
-   * Set this to `true` to keep the previous `data` when fetching based on a new query key.
-   * Defaults to `false`.
-   */
-  keepPreviousData?: boolean
   /**
    * If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided.
    */
-  placeholderData?: TQueryData | PlaceholderDataFunction<TQueryData>
+  placeholderData?:
+    | NonFunctionGuard<TQueryData>
+    | PlaceholderDataFunction<NonFunctionGuard<TQueryData>>
 
   _optimisticResults?: 'optimistic' | 'isRestoring'
 }
@@ -254,32 +291,35 @@ export type WithRequired<T, K extends keyof T> = Omit<T, K> &
   Required<Pick<T, K>>
 export type DefaultedQueryObserverOptions<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = WithRequired<
   QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
-  'useErrorBoundary' | 'refetchOnReconnect'
+  'throwErrors' | 'refetchOnReconnect'
 >
 
 export interface InfiniteQueryObserverOptions<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
 > extends QueryObserverOptions<
-    TQueryFnData,
-    TError,
-    InfiniteData<TData>,
-    InfiniteData<TQueryData>,
-    TQueryKey
-  > {}
+      TQueryFnData,
+      TError,
+      TData,
+      InfiniteData<TQueryData>,
+      TQueryKey,
+      TPageParam
+    >,
+    InfiniteQueryPageParamsOptions<TQueryFnData, TPageParam> {}
 
 export type DefaultedInfiniteQueryObserverOptions<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
@@ -291,15 +331,19 @@ export type DefaultedInfiniteQueryObserverOptions<
     TQueryData,
     TQueryKey
   >,
-  'useErrorBoundary' | 'refetchOnReconnect'
+  'throwErrors' | 'refetchOnReconnect'
 >
 
 export interface FetchQueryOptions<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
-> extends QueryOptions<TQueryFnData, TError, TData, TQueryKey> {
+  TPageParam = never,
+> extends WithRequired<
+    QueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
+    'queryKey'
+  > {
   /**
    * The time in milliseconds after data is considered stale.
    * If the data is fresh it will be returned from the cache.
@@ -309,63 +353,51 @@ export interface FetchQueryOptions<
 
 export interface FetchInfiniteQueryOptions<
   TQueryFnData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
 > extends FetchQueryOptions<
-    TQueryFnData,
-    TError,
-    InfiniteData<TData>,
-    TQueryKey
-  > {}
+      TQueryFnData,
+      TError,
+      InfiniteData<TData>,
+      TQueryKey,
+      TPageParam
+    >,
+    DefaultPageParam<TPageParam> {}
 
 export interface ResultOptions {
   throwOnError?: boolean
 }
 
-export interface RefetchPageFilters<TPageData = unknown> {
-  refetchPage?: (
-    lastPage: TPageData,
-    index: number,
-    allPages: TPageData[],
-  ) => boolean
-}
-
 export interface RefetchOptions extends ResultOptions {
   cancelRefetch?: boolean
 }
 
-export interface InvalidateQueryFilters<TPageData = unknown>
-  extends QueryFilters,
-    RefetchPageFilters<TPageData> {
+export interface InvalidateQueryFilters extends QueryFilters {
   refetchType?: QueryTypeFilter | 'none'
 }
 
-export interface RefetchQueryFilters<TPageData = unknown>
-  extends QueryFilters,
-    RefetchPageFilters<TPageData> {}
-
-export interface ResetQueryFilters<TPageData = unknown>
-  extends QueryFilters,
-    RefetchPageFilters<TPageData> {}
+export interface RefetchQueryFilters extends QueryFilters {}
 
 export interface InvalidateOptions extends RefetchOptions {}
 export interface ResetOptions extends RefetchOptions {}
 
 export interface FetchNextPageOptions extends ResultOptions {
   cancelRefetch?: boolean
-  pageParam?: unknown
 }
 
 export interface FetchPreviousPageOptions extends ResultOptions {
   cancelRefetch?: boolean
-  pageParam?: unknown
 }
 
-export type QueryStatus = 'loading' | 'error' | 'success'
+export type QueryStatus = 'pending' | 'error' | 'success'
 export type FetchStatus = 'fetching' | 'paused' | 'idle'
 
-export interface QueryObserverBaseResult<TData = unknown, TError = unknown> {
+export interface QueryObserverBaseResult<
+  TData = unknown,
+  TError = RegisteredError,
+> {
   data: TData | undefined
   dataUpdatedAt: number
   error: TError | null
@@ -378,43 +410,48 @@ export interface QueryObserverBaseResult<TData = unknown, TError = unknown> {
   isFetchedAfterMount: boolean
   isFetching: boolean
   isLoading: boolean
+  isPending: boolean
   isLoadingError: boolean
+  /**
+   * @deprecated isInitialLoading is being deprecated in favor of isLoading
+   * and will be removed in the next major version.
+   */
   isInitialLoading: boolean
   isPaused: boolean
   isPlaceholderData: boolean
-  isPreviousData: boolean
   isRefetchError: boolean
   isRefetching: boolean
   isStale: boolean
   isSuccess: boolean
-  refetch: <TPageData>(
-    options?: RefetchOptions & RefetchQueryFilters<TPageData>,
+  refetch: (
+    options?: RefetchOptions,
   ) => Promise<QueryObserverResult<TData, TError>>
-  remove: () => void
   status: QueryStatus
   fetchStatus: FetchStatus
 }
 
-export interface QueryObserverLoadingResult<TData = unknown, TError = unknown>
-  extends QueryObserverBaseResult<TData, TError> {
+export interface QueryObserverLoadingResult<
+  TData = unknown,
+  TError = RegisteredError,
+> extends QueryObserverBaseResult<TData, TError> {
   data: undefined
   error: null
   isError: false
-  isLoading: true
+  isPending: true
   isLoadingError: false
   isRefetchError: false
   isSuccess: false
-  status: 'loading'
+  status: 'pending'
 }
 
 export interface QueryObserverLoadingErrorResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
 > extends QueryObserverBaseResult<TData, TError> {
   data: undefined
   error: TError
   isError: true
-  isLoading: false
+  isPending: false
   isLoadingError: true
   isRefetchError: false
   isSuccess: false
@@ -423,77 +460,82 @@ export interface QueryObserverLoadingErrorResult<
 
 export interface QueryObserverRefetchErrorResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
 > extends QueryObserverBaseResult<TData, TError> {
   data: TData
   error: TError
   isError: true
-  isLoading: false
+  isPending: false
   isLoadingError: false
   isRefetchError: true
   isSuccess: false
   status: 'error'
 }
 
-export interface QueryObserverSuccessResult<TData = unknown, TError = unknown>
-  extends QueryObserverBaseResult<TData, TError> {
+export interface QueryObserverSuccessResult<
+  TData = unknown,
+  TError = RegisteredError,
+> extends QueryObserverBaseResult<TData, TError> {
   data: TData
   error: null
   isError: false
-  isLoading: false
+  isPending: false
   isLoadingError: false
   isRefetchError: false
   isSuccess: true
   status: 'success'
 }
 
-export type DefinedQueryObserverResult<TData = unknown, TError = unknown> =
+export type DefinedQueryObserverResult<
+  TData = unknown,
+  TError = RegisteredError,
+> =
   | QueryObserverRefetchErrorResult<TData, TError>
   | QueryObserverSuccessResult<TData, TError>
 
-export type QueryObserverResult<TData = unknown, TError = unknown> =
+export type QueryObserverResult<TData = unknown, TError = RegisteredError> =
   | DefinedQueryObserverResult<TData, TError>
   | QueryObserverLoadingErrorResult<TData, TError>
   | QueryObserverLoadingResult<TData, TError>
 
 export interface InfiniteQueryObserverBaseResult<
   TData = unknown,
-  TError = unknown,
-> extends QueryObserverBaseResult<InfiniteData<TData>, TError> {
+  TError = RegisteredError,
+> extends QueryObserverBaseResult<TData, TError> {
   fetchNextPage: (
     options?: FetchNextPageOptions,
   ) => Promise<InfiniteQueryObserverResult<TData, TError>>
   fetchPreviousPage: (
     options?: FetchPreviousPageOptions,
   ) => Promise<InfiniteQueryObserverResult<TData, TError>>
-  hasNextPage?: boolean
-  hasPreviousPage?: boolean
+  hasNextPage: boolean
+  hasPreviousPage: boolean
   isFetchingNextPage: boolean
   isFetchingPreviousPage: boolean
 }
 
 export interface InfiniteQueryObserverLoadingResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
 > extends InfiniteQueryObserverBaseResult<TData, TError> {
   data: undefined
   error: null
   isError: false
-  isLoading: true
+  isPending: true
   isLoadingError: false
   isRefetchError: false
   isSuccess: false
-  status: 'loading'
+  status: 'pending'
 }
 
 export interface InfiniteQueryObserverLoadingErrorResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
 > extends InfiniteQueryObserverBaseResult<TData, TError> {
   data: undefined
   error: TError
   isError: true
-  isLoading: false
+  isPending: false
   isLoadingError: true
   isRefetchError: false
   isSuccess: false
@@ -502,12 +544,12 @@ export interface InfiniteQueryObserverLoadingErrorResult<
 
 export interface InfiniteQueryObserverRefetchErrorResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
 > extends InfiniteQueryObserverBaseResult<TData, TError> {
-  data: InfiniteData<TData>
+  data: TData
   error: TError
   isError: true
-  isLoading: false
+  isPending: false
   isLoadingError: false
   isRefetchError: true
   isSuccess: false
@@ -516,19 +558,22 @@ export interface InfiniteQueryObserverRefetchErrorResult<
 
 export interface InfiniteQueryObserverSuccessResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
 > extends InfiniteQueryObserverBaseResult<TData, TError> {
-  data: InfiniteData<TData>
+  data: TData
   error: null
   isError: false
-  isLoading: false
+  isPending: false
   isLoadingError: false
   isRefetchError: false
   isSuccess: true
   status: 'success'
 }
 
-export type InfiniteQueryObserverResult<TData = unknown, TError = unknown> =
+export type InfiniteQueryObserverResult<
+  TData = unknown,
+  TError = RegisteredError,
+> =
   | InfiniteQueryObserverLoadingErrorResult<TData, TError>
   | InfiniteQueryObserverLoadingResult<TData, TError>
   | InfiniteQueryObserverRefetchErrorResult<TData, TError>
@@ -536,7 +581,7 @@ export type InfiniteQueryObserverResult<TData = unknown, TError = unknown> =
 
 export type MutationKey = readonly unknown[]
 
-export type MutationStatus = 'idle' | 'loading' | 'success' | 'error'
+export type MutationStatus = 'idle' | 'pending' | 'success' | 'error'
 
 export interface MutationMeta {
   [index: string]: unknown
@@ -548,13 +593,12 @@ export type MutationFunction<TData = unknown, TVariables = unknown> = (
 
 export interface MutationOptions<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > {
   mutationFn?: MutationFunction<TData, TVariables>
   mutationKey?: MutationKey
-  variables?: TVariables
   onMutate?: (
     variables: TVariables,
   ) => Promise<TContext | undefined> | TContext | undefined
@@ -577,23 +621,23 @@ export interface MutationOptions<
   retry?: RetryValue<TError>
   retryDelay?: RetryDelayValue<TError>
   networkMode?: NetworkMode
-  cacheTime?: number
+  gcTime?: number
   _defaulted?: boolean
   meta?: MutationMeta
 }
 
 export interface MutationObserverOptions<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends MutationOptions<TData, TError, TVariables, TContext> {
-  useErrorBoundary?: boolean | ((error: TError) => boolean)
+  throwErrors?: boolean | ((error: TError) => boolean)
 }
 
 export interface MutateOptions<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > {
@@ -613,7 +657,7 @@ export interface MutateOptions<
 
 export type MutateFunction<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > = (
@@ -623,13 +667,13 @@ export type MutateFunction<
 
 export interface MutationObserverBaseResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends MutationState<TData, TError, TVariables, TContext> {
   isError: boolean
   isIdle: boolean
-  isLoading: boolean
+  isPending: boolean
   isSuccess: boolean
   mutate: MutateFunction<TData, TError, TVariables, TContext>
   reset: () => void
@@ -637,67 +681,71 @@ export interface MutationObserverBaseResult<
 
 export interface MutationObserverIdleResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
   data: undefined
+  variables: undefined
   error: null
   isError: false
   isIdle: true
-  isLoading: false
+  isPending: false
   isSuccess: false
   status: 'idle'
 }
 
 export interface MutationObserverLoadingResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
   data: undefined
+  variables: TVariables
   error: null
   isError: false
   isIdle: false
-  isLoading: true
+  isPending: true
   isSuccess: false
-  status: 'loading'
+  status: 'pending'
 }
 
 export interface MutationObserverErrorResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
   data: undefined
   error: TError
+  variables: TVariables
   isError: true
   isIdle: false
-  isLoading: false
+  isPending: false
   isSuccess: false
   status: 'error'
 }
 
 export interface MutationObserverSuccessResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
   data: TData
   error: null
+  variables: TVariables
   isError: false
   isIdle: false
-  isLoading: false
+  isPending: false
   isSuccess: true
   status: 'success'
 }
 
 export type MutationObserverResult<
   TData = unknown,
-  TError = unknown,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > =
@@ -709,11 +757,10 @@ export type MutationObserverResult<
 export interface QueryClientConfig {
   queryCache?: QueryCache
   mutationCache?: MutationCache
-  logger?: Logger
   defaultOptions?: DefaultOptions
 }
 
-export interface DefaultOptions<TError = unknown> {
+export interface DefaultOptions<TError = RegisteredError> {
   queries?: QueryObserverOptions<unknown, TError>
   mutations?: MutationObserverOptions<unknown, TError, unknown, unknown>
 }