@tanstack/query-core 5.103.1 → 5.103.2

package/src/types.ts

@@ -34,6 +34,25 @@ export type Override<TTargetA, TTargetB> = {
     : TTargetA[AKey]
 }
 
+/**
+ * The interface to augment via declaration merging to override Query's default types repository-wide.
+ * Each field it declares replaces the default of the matching type: `defaultError` for {@link DefaultError},
+ * `queryKey` for {@link QueryKey}, `mutationKey` for {@link MutationKey}, `queryMeta` for {@link QueryMeta} and
+ * `mutationMeta` for {@link MutationMeta}. Leave a field out to keep that type's default.
+ * Augment the module you install — `@tanstack/react-query`, `@tanstack/vue-query`,
+ * `@tanstack/solid-query`, `@tanstack/svelte-query`, `@tanstack/preact-query`,
+ * `@tanstack/angular-query-experimental` or `@tanstack/lit-query`. Augmenting `@tanstack/query-core`
+ * works too and covers every adapter at once.
+ * @example
+ * ```ts
+ * // Use the module you installed — here, the React adapter.
+ * declare module '@tanstack/react-query' {
+ *   interface Register {
+ *     defaultError: AxiosError
+ *   }
+ * }
+ * ```
+ */
 export interface Register {
   // defaultError: Error
   // queryMeta: Record<string, unknown>
@@ -42,12 +61,20 @@ export interface Register {
   // mutationKey: ReadonlyArray<unknown>
 }
 
+/**
+ * The error type used wherever an error is not given an explicit type parameter.
+ * Defaults to `Error`; declare `defaultError` on {@link Register} to change it everywhere at once.
+ */
 export type DefaultError = Register extends {
   defaultError: infer TError
 }
   ? TError
   : Error
 
+/**
+ * The type of a query key — the serializable array that identifies a query in the cache.
+ * Defaults to `ReadonlyArray<unknown>`; declare `queryKey` on {@link Register} to narrow it repository-wide.
+ */
 export type QueryKey = Register extends {
   queryKey: infer TQueryKey
 }
@@ -99,14 +126,17 @@ export type InferErrorFromTag<TError, TTaggedQueryKey extends QueryKey> =
       : TaggedError
     : TError
 
+/** @inline */
 export type QueryFunction<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = never,
 > = (context: QueryFunctionContext<TQueryKey, TPageParam>) => T | Promise<T>
 
+/** @inline */
 export type StaleTime = number | 'static'
 
+/** @inline */
 export type StaleTimeFunction<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -116,6 +146,7 @@ export type StaleTimeFunction<
   | StaleTime
   | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => StaleTime)
 
+/** @inline */
 export type QueryBooleanOption<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -125,6 +156,7 @@ export type QueryBooleanOption<
   | boolean
   | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean)
 
+/** @inline */
 export type QueryPersister<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
@@ -170,10 +202,12 @@ export type QueryFunctionContext<
       meta: QueryMeta | undefined
     }
 
+/** @inline */
 export type InitialDataFunction<T> = () => T | undefined
 
 type NonFunctionGuard<T> = T extends Function ? never : T
 
+/** @inline */
 export type PlaceholderDataFunction<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -189,10 +223,12 @@ export type QueriesPlaceholderDataFunction<TQueryData> = (
   previousQuery: undefined,
 ) => TQueryData | undefined
 
+/** @inline */
 export type QueryKeyHashFunction<TQueryKey extends QueryKey> = (
   queryKey: TQueryKey,
 ) => string
 
+/** @inline */
 export type GetPreviousPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   firstPage: TQueryFnData,
   allPages: Array<TQueryFnData>,
@@ -200,6 +236,7 @@ export type GetPreviousPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   allPageParams: Array<TPageParam>,
 ) => TPageParam | undefined | null
 
+/** @inline */
 export type GetNextPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   lastPage: TQueryFnData,
   allPages: Array<TQueryFnData>,
@@ -207,11 +244,19 @@ export type GetNextPageParamFunction<TPageParam, TQueryFnData = unknown> = (
   allPageParams: Array<TPageParam>,
 ) => TPageParam | undefined | null
 
+/**
+ * The data shape of an infinite query: every page fetched so far, plus the page param each one was fetched with.
+ * `pages` and `pageParams` are index-aligned — `pageParams[i]` is the param that produced `pages[i]`.
+ */
 export interface InfiniteData<TData, TPageParam = unknown> {
   pages: Array<TData>
   pageParams: Array<TPageParam>
 }
 
+/**
+ * The type of the `meta` object that can be attached to a query and read back from `queryFn`, callbacks and
+ * cache-level handlers. Defaults to `Record<string, unknown>`; declare `queryMeta` on {@link Register} to narrow it.
+ */
 export type QueryMeta = Register extends {
   queryMeta: infer TQueryMeta
 }
@@ -220,8 +265,10 @@ export type QueryMeta = Register extends {
     : Record<string, unknown>
   : Record<string, unknown>
 
+/** @inline */
 export type NetworkMode = 'online' | 'always' | 'offlineFirst'
 
+/** @inline */
 export type NotifyOnChangeProps =
   | Array<keyof InfiniteQueryObserverResult>
   | 'all'
@@ -259,7 +306,7 @@ export interface QueryOptions<
   /**
    * Controls whether a query is allowed to run based on the current network connectivity.
    *
-   * Defaults to `'online'`.
+   * @defaultValue 'online'
    * @see [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
    */
   networkMode?: NetworkMode
@@ -325,7 +372,7 @@ export interface QueryOptions<
    * 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.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   structuralSharing?:
     | boolean
@@ -346,6 +393,13 @@ export interface QueryOptions<
 }
 
 export interface InitialPageParam<TPageParam = unknown> {
+  /**
+   * The page param to start from when an infinite query has no pages yet.
+   * It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the
+   * value returned by `getNextPageParam` or `getPreviousPageParam`.
+   * It only applies while the query has no pages: once a first page exists, refetching starts from
+   * that page's own param instead.
+   */
   initialPageParam: TPageParam
 }
 
@@ -365,6 +419,7 @@ export interface InfiniteQueryPageParamsOptions<
   getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>
 }
 
+/** @inline */
 export type ThrowOnError<
   TQueryFnData,
   TError,
@@ -393,7 +448,7 @@ export interface QueryObserverOptions<
    * To refetch the query, use the `refetch` method returned from the `useQuery` instance.
    * Accepts a boolean or function that returns a boolean.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   enabled?: QueryBooleanOption<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
@@ -402,14 +457,14 @@ export interface QueryObserverOptions<
    * If set to `'static'`, the data will never be considered stale.
    * If set to a function, the function will be executed with the query to compute a `staleTime`.
    *
-   * Defaults to `0`.
+   * @defaultValue 0
    */
   staleTime?: StaleTimeFunction<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
    * If set to a number, the query will continuously refetch at this frequency in milliseconds.
    * If set to a function, the function will be executed with the latest data and query to compute a frequency
    *
-   * Defaults to `false`.
+   * @defaultValue false
    */
   refetchInterval?:
     | number
@@ -420,7 +475,7 @@ export interface QueryObserverOptions<
   /**
    * If set to `true`, the query will continue to refetch while their tab/window is in the background.
    *
-   * Defaults to `false`.
+   * @defaultValue false
    */
   refetchIntervalInBackground?: boolean
   /**
@@ -429,7 +484,7 @@ export interface QueryObserverOptions<
    * If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used).
    * If set to a function, the function will be executed with the latest data and query to compute the value.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   refetchOnWindowFocus?:
     | boolean
@@ -457,7 +512,7 @@ export interface QueryObserverOptions<
    * If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used).
    * If set to a function, the function will be executed with the latest data and query to compute the value
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   refetchOnMount?:
     | boolean
@@ -469,7 +524,7 @@ export interface QueryObserverOptions<
    * If set to `false`, the query will not be retried on mount if it contains an error.
    * If set to a function, the function will be executed with the query to compute the value.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   retryOnMount?: QueryBooleanOption<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
@@ -488,7 +543,7 @@ export interface QueryObserverOptions<
    * If set to `false` and `suspense` is `false`, errors are returned as state.
    * 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`.
+   * @defaultValue false
    */
   throwOnError?: ThrowOnError<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
@@ -502,7 +557,7 @@ export interface QueryObserverOptions<
    * If set to `true`, the query will suspend when `status === 'pending'`
    * and throw errors when `status === 'error'`.
    *
-   * Defaults to `false`.
+   * @defaultValue false
    */
   suspense?: boolean
   /**
@@ -583,6 +638,10 @@ export interface QueryExecuteOptions<
   'queryKey'
 > {
   initialPageParam?: never
+  /**
+   * This option can be used to transform or select a part of the data returned by the query function. It affects
+   * the value this call resolves with, but does not affect what gets stored in the query cache.
+   */
   select?: (data: TQueryData) => TData
   /**
    * The time in milliseconds after data is considered stale.
@@ -694,9 +753,9 @@ export type FetchInfiniteQueryOptions<
 export interface ResultOptions {
   /**
    * If set to `true`, the method throws if any of the underlying query refetch tasks fail.
+   * If set to `false`, failed refetches are swallowed and not surfaced to the caller.
    *
-   * Defaults to `false`, in which case failed refetches are swallowed and not surfaced to the
-   * caller.
+   * @defaultValue false
    */
   throwOnError?: boolean
 }
@@ -707,7 +766,7 @@ export interface RefetchOptions extends ResultOptions {
    *
    * If set to `false`, no refetch will be made if there is already a request running.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   cancelRefetch?: boolean
 }
@@ -718,11 +777,12 @@ export interface InvalidateQueryFilters<
   /**
    * Controls which of the matched (now-invalidated) queries are refetched in the background.
    *
-   * Defaults to `'active'`.
    * - `'active'`: only queries with at least one active observer are refetched.
    * - `'inactive'`: only queries with no active observer are refetched.
    * - `'all'`: every matched query is refetched, active or not.
    * - `'none'`: no query is refetched; matched queries are only marked as invalidated.
+   *
+   * @defaultValue 'active'
    */
   refetchType?: QueryTypeFilter | 'none'
 }
@@ -741,7 +801,7 @@ export interface FetchNextPageOptions extends ResultOptions {
    *
    * If set to `false`, calling `fetchNextPage` repeatedly won't have any effect until the first invocation has resolved.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   cancelRefetch?: boolean
 }
@@ -753,12 +813,14 @@ export interface FetchPreviousPageOptions extends ResultOptions {
    *
    * If set to `false`, calling `fetchPreviousPage` repeatedly won't have any effect until the first invocation has resolved.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    */
   cancelRefetch?: boolean
 }
 
+/** @inline */
 export type QueryStatus = 'pending' | 'error' | 'success'
+/** @inline */
 export type FetchStatus = 'fetching' | 'paused' | 'idle'
 
 export interface QueryObserverBaseResult<
@@ -1162,6 +1224,10 @@ export type InfiniteQueryObserverResult<
   | InfiniteQueryObserverPendingResult<TData, TError>
   | InfiniteQueryObserverPlaceholderResult<TData, TError>
 
+/**
+ * The type of a mutation key — the serializable array used to identify and filter mutations.
+ * Defaults to `ReadonlyArray<unknown>`; declare `mutationKey` on {@link Register} to narrow it repository-wide.
+ */
 export type MutationKey = Register extends {
   mutationKey: infer TMutationKey
 }
@@ -1172,12 +1238,22 @@ export type MutationKey = Register extends {
       : ReadonlyArray<unknown>
   : ReadonlyArray<unknown>
 
+/** @inline */
 export type MutationStatus = 'idle' | 'pending' | 'success' | 'error'
 
+/**
+ * Groups mutations so they run one after another instead of in parallel.
+ * Mutations that share the same `id` form a queue: while one is running, the others wait in `isPaused: true`
+ * state and resume automatically when their turn comes. Mutations with no scope always run in parallel.
+ */
 export type MutationScope = {
   id: string
 }
 
+/**
+ * The type of the `meta` object that can be attached to a mutation and read back from `mutationFn`, callbacks and
+ * cache-level handlers. Defaults to `Record<string, unknown>`; declare `mutationMeta` on {@link Register} to narrow it.
+ */
 export type MutationMeta = Register extends {
   mutationMeta: infer TMutationMeta
 }
@@ -1192,6 +1268,7 @@ export type MutationFunctionContext = {
   mutationKey?: MutationKey
 }
 
+/** @inline */
 export type MutationFunction<TData = unknown, TVariables = unknown> = (
   variables: TVariables,
   context: MutationFunctionContext,
@@ -1203,24 +1280,57 @@ export interface MutationOptions<
   TVariables = void,
   TOnMutateResult = unknown,
 > {
+  /**
+   * The function that performs the asynchronous task this mutation runs.
+   * Required, unless a default mutation function has been set for the matching `mutationKey` via
+   * `queryClient.setMutationDefaults`.
+   * Receives the `variables` passed to `mutate`, and a {@link MutationFunctionContext} holding the
+   * `QueryClient`, the `mutationKey` and `meta`.
+   * Must return a promise that resolves the mutation's data.
+   */
   mutationFn?: MutationFunction<TData, TVariables>
+  /**
+   * The key to use for this mutation. Optional, but required to inherit defaults registered with
+   * `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or
+   * `queryClient.isMutating`.
+   */
   mutationKey?: MutationKey
+  /**
+   * This function fires before the mutation function runs, and receives the same variables.
+   * Useful for optimistic updates applied in the hope that the mutation succeeds.
+   * The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`,
+   * which is where an optimistic update is usually rolled back.
+   * If a promise is returned, it is awaited before the mutation function runs.
+   */
   onMutate?: (
     variables: TVariables,
     context: MutationFunctionContext,
   ) => Promise<TOnMutateResult> | TOnMutateResult
+  /**
+   * This function fires when the mutation succeeds, and is passed the mutation's result.
+   * If a promise is returned, it is awaited before `onSettled` runs.
+   */
   onSuccess?: (
     data: TData,
     variables: TVariables,
     onMutateResult: TOnMutateResult,
     context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
+  /**
+   * This function fires when the mutation encounters an error, and is passed the error.
+   * If a promise is returned, it is awaited before `onSettled` runs.
+   */
   onError?: (
     error: TError,
     variables: TVariables,
     onMutateResult: TOnMutateResult | undefined,
     context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
+  /**
+   * This function fires when the mutation either succeeds or errors, and is passed either the data
+   * or the error.
+   * If a promise is returned, it is awaited before the mutation settles.
+   */
   onSettled?: (
     data: TData | undefined,
     error: TError | null,
@@ -1234,7 +1344,7 @@ export interface MutationOptions<
    * If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number.
    * If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false.
    *
-   * Defaults to `0`.
+   * @defaultValue 0
    */
   retry?: RetryValue<TError>
   /**
@@ -1247,7 +1357,7 @@ export interface MutationOptions<
   /**
    * Controls whether a mutation is allowed to run based on the current network connectivity.
    *
-   * Defaults to `'online'`.
+   * @defaultValue 'online'
    * @see [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
    */
   networkMode?: NetworkMode
@@ -1260,7 +1370,17 @@ export interface MutationOptions<
   gcTime?: number
   /** @internal */
   _defaulted?: boolean
+  /**
+   * Additional payload to be stored on the mutation cache entry.
+   * Use it to pass information that can be read wherever the `mutation` is available, such as the
+   * `onError` and `onSuccess` callbacks of the `MutationCache`.
+   */
   meta?: MutationMeta
+  /**
+   * Controls whether this mutation runs alongside others or waits its turn.
+   * Mutations sharing the same `scope.id` run serially, in the order they were started.
+   * Without a scope, a mutation runs as soon as it is triggered.
+   */
   scope?: MutationScope
 }
 
@@ -1276,7 +1396,7 @@ export interface MutationObserverOptions<
    * If set to a function, it will be passed the error and should return a boolean indicating whether to throw the
    * error (`true`) or return it as state (`false`).
    *
-   * Defaults to `false`.
+   * @defaultValue false
    */
   throwOnError?: boolean | ((error: TError) => boolean)
 }
@@ -1518,15 +1638,25 @@ export interface DefaultOptions<TError = DefaultError> {
   dehydrate?: DehydrateOptions
 }
 
+/**
+ * Options for cancelling an in-flight fetch, e.g. via `query.cancel()`.
+ * They are carried on the {@link CancelledError} that the cancelled fetch rejects with.
+ */
 export interface CancelOptions {
   revert?: boolean
   silent?: boolean
 }
 
+/**
+ * Options for writing data into the cache, e.g. via `queryClient.setQueryData()`.
+ * `updatedAt` overrides the timestamp the data is recorded with, which is what staleness is measured from;
+ * omit it to use the current time.
+ */
 export interface SetDataOptions {
   updatedAt?: number
 }
 
+/** @inline */
 export type NotifyEventType =
   | 'added'
   | 'removed'

package/src/utils.ts

@@ -32,7 +32,7 @@ export interface QueryFilters<TQueryKey extends QueryKey = QueryKey> {
   /**
    * Filter to active queries, inactive queries or all queries
    *
-   * Defaults to `'all'`.
+   * @defaultValue 'all'
    */
   type?: QueryTypeFilter
   /**