@tanstack/preact-query 5.102.2 → 5.102.4

package/src/queryOptions.ts

@@ -11,18 +11,43 @@ import type {
 
 import type { UseQueryOptions } from './types'
 
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set — `data` may be
+ * `undefined` while the query is `pending`.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UndefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData?:
     | undefined
     | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
     | NonUndefinedGuard<TQueryFnData>
 }
 
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set and `queryFn` is
+ * not `skipToken` — same as {@link UndefinedInitialDataOptions}, but `queryFn` may not be `skipToken`.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UnusedSkipTokenOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -32,24 +57,77 @@ export type UnusedSkipTokenOptions<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
+   * you don't intend to run the query yet, omit `queryFn` or use a default query function instead.
+   */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
     SkipToken | undefined
   >
 }
 
+/**
+ * The options accepted by the `queryOptions` overload selected when `initialData` is set — `data` is never
+ * `undefined`.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type DefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryFn'> & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData:
     | NonUndefinedGuard<TQueryFnData>
     | (() => NonUndefinedGuard<TQueryFnData>)
+  /**
+   * Optional here, but omitting it is only safe when no fetch will be attempted — for example with
+   * `enabled: false`, or when a default query function has been defined. Otherwise, an enabled query with no
+   * `queryFn` still tries to fetch and fails with a "Missing queryFn" error; `initialData` does not prevent this.
+   */
   queryFn?: QueryFunction<TQueryFnData, TQueryKey>
 }
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ *   initialData: [],
+ * })
+ *
+ * function Posts() {
+ *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
+ *   const { data } = useQuery(postsOptions)
+ *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ * }
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -60,6 +138,66 @@ export function queryOptions<
 ): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @param options - The {@link UnusedSkipTokenOptions} to use — everything you can pass to `useQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions } from '@tanstack/preact-query'
+ *
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ * })
+ * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { noop, queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data } = useQuery(postOptions(id))
+ *   return <h1>{data?.title}</h1>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+ * queryClient.query(postOptions(id)).catch(noop)
+ * ```
+ *
+ * @example
+ * The same options object works with every API that accepts query options:
+ * ```tsx
+ * import {
+ *   noop,
+ *   queryOptions,
+ *   useQuery,
+ *   useSuspenseQuery,
+ * } from '@tanstack/preact-query'
+ *
+ * const todosOptions = queryOptions({
+ *   queryKey: ['todos'],
+ *   queryFn: fetchTodos,
+ * })
+ *
+ * useQuery(todosOptions)
+ * useSuspenseQuery(todosOptions)
+ * queryClient.query(todosOptions).catch(noop)
+ * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -70,6 +208,66 @@ export function queryOptions<
 ): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions } from '@tanstack/preact-query'
+ *
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ * })
+ * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { noop, queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data } = useQuery(postOptions(id))
+ *   return <h1>{data?.title}</h1>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+ * queryClient.query(postOptions(id)).catch(noop)
+ * ```
+ *
+ * @example
+ * The same options object works with every API that accepts query options:
+ * ```tsx
+ * import {
+ *   noop,
+ *   queryOptions,
+ *   useQuery,
+ *   useSuspenseQuery,
+ * } from '@tanstack/preact-query'
+ *
+ * const todosOptions = queryOptions({
+ *   queryKey: ['todos'],
+ *   queryFn: fetchTodos,
+ * })
+ *
+ * useQuery(todosOptions)
+ * useSuspenseQuery(todosOptions)
+ * queryClient.query(todosOptions).catch(noop)
+ * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,

package/src/types.ts

@@ -20,6 +20,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,
@@ -27,6 +31,18 @@ export type AnyUseBaseQueryOptions = UseBaseQueryOptions<
   any,
   any
 >
+/**
+ * The options shared by `useQuery` and `useSuspenseQuery`. Extends {@link QueryObserverOptions} from
+ * `@tanstack/query-core` with the `preact-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,
@@ -42,11 +58,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,
@@ -57,6 +86,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,
@@ -69,6 +102,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 `TQueryFnData` (a single page)
+ * here, since a prefetch never reads `data` back out — 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,
@@ -85,6 +130,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,
@@ -97,7 +146,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
+ * `preact-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,
@@ -108,12 +171,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,
@@ -123,12 +201,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,
@@ -136,6 +222,18 @@ export type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<
   any,
   any
 >
+/**
+ * The options accepted by `useInfiniteQuery`. Extends {@link InfiniteQueryObserverOptions} from
+ * `@tanstack/query-core` with the `preact-query`-specific `subscribed` option, minus `suspense` (which
+ * `preact-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,
@@ -154,13 +252,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,
@@ -171,6 +286,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,
@@ -183,16 +302,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,
@@ -201,21 +341,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,
@@ -224,7 +393,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,
@@ -235,6 +418,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,
@@ -246,6 +440,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,
@@ -253,6 +457,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,
@@ -262,6 +476,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,
@@ -270,6 +487,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,