@tanstack/react-query 5.102.8 → 5.103.0

package/src/types.ts

@@ -21,6 +21,10 @@ import type {
   SkipToken,
 } from '@tanstack/query-core'
 
+/**
+ * {@link UseBaseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseBaseQueryOptions = UseBaseQueryOptions<
   any,
   any,
@@ -28,6 +32,18 @@ export type AnyUseBaseQueryOptions = UseBaseQueryOptions<
   any,
   any
 >
+/**
+ * The options shared by `useQuery` and `useSuspenseQuery`. Extends {@link QueryObserverOptions} from
+ * `@tanstack/query-core` with the `react-query`-specific `subscribed` option.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryData - The type of the data actually held in the query cache — the input to `select` and
+ * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface UseBaseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -43,11 +59,24 @@ export interface UseBaseQueryOptions<
 > {
   /**
    * Set this to `false` to unsubscribe this observer from updates to the query cache.
-   * Defaults to `true`.
+   *
+   * @defaultValue true
    */
   subscribed?: boolean
 }
 
+/**
+ * The options accepted by `usePrefetchQuery` — everything you can pass to `queryClient.query`, except `queryFn`
+ * is required unless a default query function has been defined.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryData - The type of the data actually held in the query cache — the input to `select` and
+ * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UsePrefetchQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -58,6 +87,10 @@ export type UsePrefetchQueryOptions<
   QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+   * unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     QueryExecuteOptions<
       TQueryFnData,
@@ -70,6 +103,18 @@ export type UsePrefetchQueryOptions<
   >
 }
 
+/**
+ * The options accepted by `usePrefetchInfiniteQuery` — everything you can pass to `queryClient.infiniteQuery`,
+ * except `queryFn` is required unless a default query function has been defined.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `InfiniteData<TQueryFnData>`,
+ * the shape of all fetched pages plus their page params — a prefetch never reads `data` back out, so this
+ * parameter only matters if you reuse these options elsewhere with `select` applied.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export type UsePrefetchInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -86,6 +131,10 @@ export type UsePrefetchInfiniteQueryOptions<
   >,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+   * unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     InfiniteQueryExecuteOptions<
       TQueryFnData,
@@ -98,7 +147,21 @@ export type UsePrefetchInfiniteQueryOptions<
   >
 }
 
+/**
+ * {@link UseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseQueryOptions = UseQueryOptions<any, any, any, any>
+/**
+ * The options accepted by `useQuery`. Same as {@link UseBaseQueryOptions}, minus `suspense` (which
+ * `react-query` derives from which hook you call rather than exposing as an option).
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface UseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -109,12 +172,27 @@ export interface UseQueryOptions<
   'suspense'
 > {}
 
+/**
+ * {@link UseSuspenseQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseSuspenseQueryOptions = UseSuspenseQueryOptions<
   any,
   any,
   any,
   any
 >
+/**
+ * The options accepted by `useSuspenseQuery`. Same as {@link UseQueryOptions}, minus `enabled`, `throwOnError`,
+ * and `placeholderData` — Suspense hooks cannot render a "disabled" or "placeholder" state, so those options
+ * don't apply.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface UseSuspenseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -124,12 +202,20 @@ export interface UseSuspenseQueryOptions<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
 > {
+  /**
+   * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+   * must always be provided, unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
     SkipToken
   >
 }
 
+/**
+ * {@link UseInfiniteQueryOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<
   any,
   any,
@@ -137,6 +223,18 @@ export type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<
   any,
   any
 >
+/**
+ * The options accepted by `useInfiniteQuery`. Extends {@link InfiniteQueryObserverOptions} from
+ * `@tanstack/query-core` with the `react-query`-specific `subscribed` option, minus `suspense` (which
+ * `react-query` derives from which hook you call rather than exposing as an option).
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs — defaults to `InfiniteData<TQueryFnData>`,
+ * the shape of all fetched pages plus their page params.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export interface UseInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -155,13 +253,30 @@ export interface UseInfiniteQueryOptions<
 > {
   /**
    * Set this to `false` to unsubscribe this observer from updates to the query cache.
-   * Defaults to `true`.
+   *
+   * @defaultValue true
    */
   subscribed?: boolean
 }
 
+/**
+ * {@link UseSuspenseInfiniteQueryOptions} with all type parameters set to `any`, useful when the specific types
+ * aren't relevant, e.g. when accepting options for any query in a helper function.
+ */
 export type AnyUseSuspenseInfiniteQueryOptions =
   UseSuspenseInfiniteQueryOptions<any, any, any, any, any>
+/**
+ * The options accepted by `useSuspenseInfiniteQuery`. Same as {@link UseInfiniteQueryOptions}, minus `enabled`,
+ * `throwOnError`, and `placeholderData` — Suspense hooks cannot render a "disabled" or "placeholder" state, so
+ * those options don't apply.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs — defaults to `InfiniteData<TQueryFnData>`,
+ * the shape of all fetched pages plus their page params.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export interface UseSuspenseInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -172,6 +287,10 @@ export interface UseSuspenseInfiniteQueryOptions<
   UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
   'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
 > {
+  /**
+   * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+   * must always be provided, unless a default query function has been defined.
+   */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
       TQueryFnData,
@@ -184,16 +303,37 @@ export interface UseSuspenseInfiniteQueryOptions<
   >
 }
 
+/**
+ * The result of `useQuery` when `initialData` isn't set — `data` may be `undefined` while the query is
+ * `pending`. Re-exports {@link QueryObserverResult} from `@tanstack/query-core`. `useInfiniteQuery` returns
+ * {@link UseInfiniteQueryResult} instead.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseBaseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = QueryObserverResult<TData, TError>
 
+/**
+ * The result of `useQuery`. Same as {@link UseBaseQueryResult}.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = UseBaseQueryResult<TData, TError>
 
+/**
+ * The result of `useSuspenseQuery`. Same as {@link DefinedUseQueryResult}, minus `isPlaceholderData` — always
+ * `false` on that type, so this drops the dead field rather than an active state.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseSuspenseQueryResult<
   TData = unknown,
   TError = DefaultError,
@@ -202,21 +342,50 @@ export type UseSuspenseQueryResult<
   'isPlaceholderData'
 >
 
+/**
+ * The result of `useQuery` when `initialData` is set, or of `useSuspenseQuery` before the `isPlaceholderData`
+ * omission — `data` is never `undefined`. Re-exports {@link DefinedQueryObserverResult} from
+ * `@tanstack/query-core`.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type DefinedUseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = DefinedQueryObserverResult<TData, TError>
 
+/**
+ * The result of `useInfiniteQuery` when `initialData` isn't set — `data` may be `undefined` while the query is
+ * `pending`. Re-exports {@link InfiniteQueryObserverResult} from `@tanstack/query-core`.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = InfiniteQueryObserverResult<TData, TError>
 
+/**
+ * The result of `useInfiniteQuery` when `initialData` is set — `data` is never `undefined`. Re-exports
+ * {@link DefinedInfiniteQueryObserverResult} from `@tanstack/query-core`.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type DefinedUseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = DefinedInfiniteQueryObserverResult<TData, TError>
 
+/**
+ * The result of `useSuspenseInfiniteQuery`. Same as {@link DefinedUseInfiniteQueryResult}, minus
+ * `isPlaceholderData` — Suspense hooks never render placeholder data.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type UseSuspenseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
@@ -225,7 +394,21 @@ export type UseSuspenseInfiniteQueryResult<
   'isPlaceholderData'
 >
 
+/**
+ * {@link UseMutationOptions} with all type parameters set to `any`, useful when the specific types aren't
+ * relevant, e.g. when accepting options for any mutation in a helper function.
+ */
 export type AnyUseMutationOptions = UseMutationOptions<any, any, any, any>
+/**
+ * The options accepted by `useMutation`. Same as {@link MutationObserverOptions} from `@tanstack/query-core`,
+ * minus the internal `_defaulted` flag.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export interface UseMutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -236,6 +419,17 @@ export interface UseMutationOptions<
   '_defaulted'
 > {}
 
+/**
+ * The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call
+ * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced
+ * through the mutation result, not thrown.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseMutateFunction<
   TData = unknown,
   TError = DefaultError,
@@ -247,6 +441,16 @@ export type UseMutateFunction<
   >
 ) => void
 
+/**
+ * The type of `mutateAsync`, as returned by `useMutation`. Similar to {@link UseMutateFunction}, but returns a
+ * promise which can be awaited.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseMutateAsyncFunction<
   TData = unknown,
   TError = DefaultError,
@@ -254,6 +458,16 @@ export type UseMutateAsyncFunction<
   TOnMutateResult = unknown,
 > = MutateFunction<TData, TError, TVariables, TOnMutateResult>
 
+/**
+ * The result of `useMutation`. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with
+ * `mutate` narrowed to the fire-and-forget {@link UseMutateFunction} signature, plus the added `mutateAsync`.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseBaseMutationResult<
   TData = unknown,
   TError = DefaultError,
@@ -263,6 +477,9 @@ export type UseBaseMutationResult<
   MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
   { mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult> }
 > & {
+  /**
+   * Similar to `mutate`, but returns a promise which can be awaited.
+   */
   mutateAsync: UseMutateAsyncFunction<
     TData,
     TError,
@@ -271,6 +488,15 @@ export type UseBaseMutationResult<
   >
 }
 
+/**
+ * The result of `useMutation`. Same as {@link UseBaseMutationResult}.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type UseMutationResult<
   TData = unknown,
   TError = DefaultError,