@tanstack/query-core 5.103.1 → 5.103.3

package/src/queryObserver.ts

@@ -409,8 +409,7 @@ export class QueryObserver<
 
     let unsubscribe = () => {}
     let resolveEarly:
-      | ((result: QueryObserverResult<TData, TError>) => void)
-      | undefined
+      ((result: QueryObserverResult<TData, TError>) => void) | undefined
 
     const cachePromise = new Promise<QueryObserverResult<TData, TError>>(
       (resolve) => {
@@ -569,8 +568,7 @@ export class QueryObserver<
     const prevQuery = this.#currentQuery
     const prevOptions = this.options
     const prevResult = this.#currentResult as
-      | QueryObserverResult<TData, TError>
-      | undefined
+      QueryObserverResult<TData, TError> | undefined
     const prevResultState = this.#currentResultState
     const prevResultOptions = this.#currentResultOptions
     const queryChange = query !== prevQuery
@@ -734,8 +732,7 @@ export class QueryObserver<
    */
   updateResult(): void {
     const prevResult = this.#currentResult as
-      | QueryObserverResult<TData, TError>
-      | undefined
+      QueryObserverResult<TData, TError> | undefined
 
     const nextResult = this.createResult(this.#currentQuery, this.options)
 
@@ -813,8 +810,7 @@ export class QueryObserver<
     }
 
     const prevQuery = this.#currentQuery as
-      | Query<TQueryFnData, TError, TQueryData, TQueryKey>
-      | undefined
+      Query<TQueryFnData, TError, TQueryData, TQueryKey> | undefined
     this.#currentQuery = query
     this.#currentQueryInitialState = query.state
 

package/src/removable.ts

@@ -3,10 +3,19 @@ import { isServer as isServerEnvironment } from './environmentManager'
 import { isValidTimeout } from './utils'
 import type { ManagedTimerId } from './timeoutManager'
 
+/**
+ * The base class for cache entries that are garbage collected once nothing is using them —
+ * `Query` and `Mutation` both extend it. `gcTime` controls how long an unused entry is kept.
+ */
 export abstract class Removable {
   gcTime!: number
   #gcTimeout?: ManagedTimerId
 
+  /**
+   * Clears the pending garbage collection timeout, so the entry is no longer scheduled for removal.
+   * A subclass may override this to release what it holds on to as well — `Query` also cancels any
+   * in-flight fetch.
+   */
   destroy(): void {
     this.clearGcTimeout()
   }

package/src/retryer.ts

@@ -32,15 +32,19 @@ export interface Retryer<TData = unknown> {
 
 type RetryerStatus = 'pending' | 'resolved' | 'rejected'
 
+/** @inline */
 export type RetryValue<TError> = boolean | number | ShouldRetryFunction<TError>
 
+/** @inline */
 type ShouldRetryFunction<TError = DefaultError> = (
   failureCount: number,
   error: TError,
 ) => boolean
 
+/** @inline */
 export type RetryDelayValue<TError> = number | RetryDelayFunction<TError>
 
+/** @inline */
 type RetryDelayFunction<TError = DefaultError> = (
   failureCount: number,
   error: TError,

package/src/streamedQuery.ts

@@ -55,13 +55,6 @@ type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> =
  * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.
  * The query will stay in fetchStatus 'fetching' until the stream ends.
  * @param streamFn - The function that returns an AsyncIterable to stream data from.
- * @param refetchMode - Defines how re-fetches are handled.
- * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.
- * Set to `'append'` to append new data to the existing data.
- * Set to `'replace'` to write all data to the cache once the stream ends.
- * @param reducer - A function to reduce the streamed chunks into the final data.
- * Defaults to a function that appends chunks to the end of the array.
- * @param initialValue - Initial value to be used while the first chunk is being fetched, and returned if the stream yields no values.
  * @example
  * ```ts
  * await queryClient.query({

package/src/subscribable.ts

@@ -1,3 +1,8 @@
+/**
+ * The base class behind everything in Query that you can subscribe to: `QueryCache`, `MutationCache`,
+ * the observers, and the `FocusManager`/`OnlineManager` behind `focusManager` and `onlineManager`.
+ * Subclasses decide what a listener receives and when it is called.
+ */
 export class Subscribable<TListener extends Function> {
   protected listeners = new Set<TListener>()
 
@@ -5,6 +10,20 @@ export class Subscribable<TListener extends Function> {
     this.subscribe = this.subscribe.bind(this)
   }
 
+  /**
+   * Registers a listener to be called on every update this object notifies about. Returns a function
+   * that removes the listener again — call it to stop listening. The base class never drops a listener
+   * on its own, though some subclasses clear all of theirs in `destroy()`.
+   * @param listener - Called on each update, with whatever the subclass passes to its subscribers.
+   * @example
+   * ```ts
+   * const unsubscribe = subscribable.subscribe(() => {
+   *   // react to the update
+   * })
+   *
+   * unsubscribe()
+   * ```
+   */
   subscribe(listener: TListener): () => void {
     this.listeners.add(listener)
 
@@ -16,6 +35,9 @@ export class Subscribable<TListener extends Function> {
     }
   }
 
+  /**
+   * Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
+   */
   hasListeners(): boolean {
     return this.listeners.size > 0
   }

package/src/types.ts

@@ -18,13 +18,12 @@ export type DistributiveOmit<
 
 export type OmitKeyof<
   TObject,
-  TKey extends TStrictly extends 'safely'
-    ?
-        | keyof TObject
-        | (string & Record<never, never>)
-        | (number & Record<never, never>)
-        | (symbol & Record<never, never>)
-    : keyof TObject,
+  TKey extends (TStrictly extends 'safely'
+    ? | keyof TObject
+      | (string & Record<never, never>)
+      | (number & Record<never, never>)
+      | (symbol & Record<never, never>)
+    : keyof TObject),
   TStrictly extends 'strictly' | 'safely' = 'strictly',
 > = Omit<TObject, TKey>
 
@@ -34,6 +33,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 +60,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 +125,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,15 +145,16 @@ export type StaleTimeFunction<
   | StaleTime
   | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => StaleTime)
 
+/** @inline */
 export type QueryBooleanOption<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > =
-  | boolean
-  | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean)
+  boolean | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean)
 
+/** @inline */
 export type QueryPersister<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
@@ -170,10 +200,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 +221,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 +234,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 +242,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 +263,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 +304,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,11 +370,10 @@ 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
-    | ((oldData: unknown | undefined, newData: unknown) => unknown)
+    boolean | ((oldData: unknown | undefined, newData: unknown) => unknown)
   /** @internal */
   _defaulted?: boolean
   /** @internal */
@@ -346,6 +390,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 +416,7 @@ export interface InfiniteQueryPageParamsOptions<
   getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>
 }
 
+/** @inline */
 export type ThrowOnError<
   TQueryFnData,
   TError,
@@ -393,7 +445,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 +454,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 +472,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 +481,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 +509,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 +521,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 +540,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 +554,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 +635,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 +750,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 +763,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 +774,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 +798,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 +810,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<
@@ -984,10 +1043,7 @@ export interface QueryObserverPlaceholderResult<
   status: 'success'
 }
 
-export type DefinedQueryObserverResult<
-  TData = unknown,
-  TError = DefaultError,
-> =
+export type DefinedQueryObserverResult<TData = unknown, TError = DefaultError> =
   | QueryObserverRefetchErrorResult<TData, TError>
   | QueryObserverSuccessResult<TData, TError>
 
@@ -1162,6 +1218,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 +1232,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 +1262,7 @@ export type MutationFunctionContext = {
   mutationKey?: MutationKey
 }
 
+/** @inline */
 export type MutationFunction<TData = unknown, TVariables = unknown> = (
   variables: TVariables,
   context: MutationFunctionContext,
@@ -1203,24 +1274,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 +1338,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 +1351,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 +1364,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 +1390,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 +1632,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
   /**