@tanstack/solid-query 5.102.8 → 5.103.0

package/src/infiniteQueryOptions.ts

@@ -8,6 +8,20 @@ import type {
 import type { InfiniteQueryOptions } from './types'
 import type { Accessor } from 'solid-js'
 
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when no `initialData` is set — `data`
+ * may be `undefined` while the query is `pending`. `infiniteQueryOptions` itself accepts and returns a plain
+ * object (its parameter type is `ReturnType<UndefinedInitialDataInfiniteOptions<...>>`, i.e. this `Accessor`
+ * called); Solid's reactivity applies where the result is consumed instead, e.g.
+ * `useInfiniteQuery(() => options)`.
+ *
+ * @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 type UndefinedInitialDataInfiniteOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -20,6 +34,17 @@ export type UndefinedInitialDataInfiniteOptions<
   }
 >
 
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is set — `data` is
+ * never `undefined`.
+ *
+ * @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 type DefinedInitialDataInfiniteOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -34,6 +59,49 @@ export type DefinedInitialDataInfiniteOptions<
       | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
   }
 >
+
+/**
+ * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+ * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * This overload is selected when `initialData` is set.
+ *
+ * @see {@link useInfiniteQuery} to run an infinite query with these options.
+ * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { For } from 'solid-js'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/solid-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ *   initialData: { pages: [], pageParams: [] },
+ * })
+ *
+ * function Projects() {
+ *   // `projectsQuery.data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
+ *   const projectsQuery = useInfiniteQuery(() => projectsOptions)
+ *
+ *   return (
+ *     <div>
+ *       {projectsQuery.isError ? <span>Error: {projectsQuery.error.message}</span> : null}
+ *       <ul>
+ *         <For each={projectsQuery.data.pages}>
+ *           {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
+ *         </For>
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -60,6 +128,49 @@ export function infiniteQueryOptions<
   >
 > &
   QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
+
+/**
+ * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+ * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * @see {@link useInfiniteQuery} to run an infinite query with these options.
+ * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `postId`:
+ * ```tsx
+ * import { For, Match, Switch } from 'solid-js'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/solid-query'
+ *
+ * const commentsOptions = (postId: string) =>
+ *   infiniteQueryOptions({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ * function Comments(props: { postId: string }) {
+ *   const commentsQuery = useInfiniteQuery(() => commentsOptions(props.postId))
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={commentsQuery.isPending}>Loading...</Match>
+ *       <Match when={commentsQuery.isError}>Error: {commentsQuery.error.message}</Match>
+ *       <Match when={commentsQuery.isSuccess}>
+ *         <ul>
+ *           <For each={commentsQuery.data.pages}>
+ *             {(page) => <For each={page.comments}>{(c) => <li>{c.text}</li>}</For>}
+ *           </For>
+ *         </ul>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,

package/src/isRestoring.ts

@@ -3,5 +3,17 @@ import type { Accessor } from 'solid-js'
 
 const IsRestoringContext = createContext<Accessor<boolean>>(() => false)
 
+/**
+ * If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
+ * check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
+ * race conditions between the restore and mounting queries.
+ *
+ * @returns An accessor that reads `true` while a persisted client is being restored, `false` otherwise.
+ */
 export const useIsRestoring = () => useContext(IsRestoringContext)
+
+/**
+ * The Provider that `PersistQueryClientProvider` uses to signal whether a persisted client is currently
+ * being restored, read by `useIsRestoring`.
+ */
 export const IsRestoringProvider = IsRestoringContext.Provider

package/src/mutationOptions.ts

@@ -1,6 +1,35 @@
 import type { DefaultError, WithRequired } from '@tanstack/query-core'
 import type { MutationOptions } from './types'
 
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A
+ * `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
+ * `useMutationState`.
+ *
+ * @see {@link useMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, with a
+ * required `mutationKey`.
+ * @returns The same options object, unchanged.
+ *
+ * @example
+ * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
+ * ```tsx
+ * import { mutationOptions, useMutationState } from '@tanstack/solid-query'
+ *
+ * const createPostOptions = mutationOptions({
+ *   mutationKey: ['posts', 'create'],
+ *   mutationFn: createPost,
+ * })
+ *
+ * function SavingIndicator() {
+ *   const isCreatingPost = useMutationState(() => ({
+ *     filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+ *   }))
+ *
+ *   return isCreatingPost().length > 0 ? <span>Saving…</span> : null
+ * }
+ * ```
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -15,6 +44,32 @@ export function mutationOptions<
   MutationOptions<TData, TError, TVariables, TOnMutateResult>,
   'mutationKey'
 >
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
+ * `mutationKey` is required on this overload — use this when you don't need to target the mutation via a
+ * `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters,
+ * such as `status`.
+ *
+ * @see {@link useMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
+ * `mutationKey`.
+ * @returns The same options object, unchanged.
+ * @remarks See the other overload's example for looking a mutation up via `useMutationState`.
+ *
+ * @example
+ * ```tsx
+ * import { mutationOptions, useMutation } from '@tanstack/solid-query'
+ *
+ * const createPostOptions = mutationOptions({
+ *   mutationFn: createPost,
+ * })
+ *
+ * function CreatePost() {
+ *   const createPostMutation = useMutation(() => createPostOptions)
+ *   return <button onClick={() => createPostMutation.mutate({ title: 'Hello' })}>Create</button>
+ * }
+ * ```
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,

package/src/queryOptions.ts

@@ -6,6 +6,17 @@ import type {
 import type { QueryOptions } from './types'
 import type { Accessor } from 'solid-js'
 
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set — `data` may be
+ * `undefined` while the query is `pending`. `queryOptions` itself accepts and returns a plain object (its
+ * parameter type is `ReturnType<UndefinedInitialDataOptions<...>>`, i.e. this `Accessor` called); Solid's
+ * reactivity applies where the result is consumed instead, e.g. `useQuery(() => options)`.
+ *
+ * @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,
@@ -17,6 +28,15 @@ export type UndefinedInitialDataOptions<
   }
 >
 
+/**
+ * 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,
@@ -28,6 +48,44 @@ export type DefinedInitialDataOptions<
   }
 >
 
+/**
+ * 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 { For } from 'solid-js'
+ * import { queryOptions, useQuery } from '@tanstack/solid-query'
+ *
+ * const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ *   initialData: [],
+ * })
+ *
+ * function Posts() {
+ *   // `postsQuery.data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
+ *   // so the list stays visible alongside the error.
+ *   const postsQuery = useQuery(() => postsOptions)
+ *
+ *   return (
+ *     <div>
+ *       {postsQuery.isError ? <span>Error: {postsQuery.error.message}</span> : null}
+ *       <ul>
+ *         <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -35,13 +93,49 @@ export function queryOptions<
   TQueryKey extends QueryKey = QueryKey,
 >(
   options: ReturnType<
-    UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+    DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
   >,
 ): ReturnType<
-  UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+  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 UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
+ * ```tsx
+ * import { Match, Switch } from 'solid-js'
+ * import { queryOptions, useQuery } from '@tanstack/solid-query'
+ *
+ * const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post(props: { id: string }) {
+ *   const postQuery = useQuery(() => postOptions(props.id))
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={postQuery.isPending}>Loading...</Match>
+ *       <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
+ *       <Match when={postQuery.isSuccess}>
+ *         <h1>{postQuery.data.title}</h1>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -49,10 +143,10 @@ export function queryOptions<
   TQueryKey extends QueryKey = QueryKey,
 >(
   options: ReturnType<
-    DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+    UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
   >,
 ): ReturnType<
-  DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+  UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
 > &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 

package/src/types.ts

@@ -19,6 +19,18 @@ import type {
 } from './QueryClient'
 import type { Accessor } from 'solid-js'
 
+/**
+ * The options accepted by `useQuery`. Extends {@link QueryObserverOptions} from `@tanstack/query-core` with
+ * the `solid-query`-specific `deferStream` and `suspense` options.
+ *
+ * @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,
@@ -44,6 +56,15 @@ export interface UseBaseQueryOptions<
   suspense?: boolean
 }
 
+/**
+ * The options accepted by `useQuery` and `queryOptions`.
+ *
+ * @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 QueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -57,6 +78,16 @@ export interface QueryOptions<
   TQueryKey
 > {}
 
+/**
+ * The accessor `useQuery` expects as its first argument — Solid re-evaluates it reactively, so `queryKey` and
+ * other options can depend on signals.
+ *
+ * @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 type UseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -66,27 +97,63 @@ export type UseQueryOptions<
 
 /* --- Create Query and Create Base Query  Types --- */
 
+/**
+ * The object `useQuery` returns when `initialData` isn't set — `data`/`error` may still be `undefined`/`null`
+ * 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 (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 export type UseBaseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = QueryObserverResult<TData, TError>
 
+/**
+ * The object `useQuery` returns — `data`/`error` may still be `undefined`/`null` while the query is
+ * `pending`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 export type UseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = UseBaseQueryResult<TData, TError>
 
+/**
+ * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 export type DefinedUseBaseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = DefinedQueryObserverResult<TData, TError>
 
+/**
+ * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 export type DefinedUseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = DefinedUseBaseQueryResult<TData, TError>
 
 /* --- Create Infinite Queries Types --- */
+/**
+ * The options accepted by `useInfiniteQuery`.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export interface InfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -119,6 +186,16 @@ export interface InfiniteQueryOptions<
   suspense?: boolean
 }
 
+/**
+ * The accessor `useInfiniteQuery` expects as its first argument — Solid re-evaluates it reactively, so
+ * `queryKey` and other options can depend on signals.
+ *
+ * @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.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export type UseInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -129,17 +206,38 @@ export type UseInfiniteQueryOptions<
   InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
 >
 
+/**
+ * The object `useInfiniteQuery` returns — `data`/`error` may still be `undefined`/`null` while the query is
+ * `pending`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 export type UseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = InfiniteQueryObserverResult<TData, TError>
 
+/**
+ * The object `useInfiniteQuery` returns when `initialData` guarantees `data` is never `undefined`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 export type DefinedUseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = DefinedInfiniteQueryObserverResult<TData, TError>
 
 /* --- Create Mutation Types --- */
+/**
+ * The options accepted by `useMutation` and `mutationOptions`.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` may throw.
+ * @template TVariables - The type of the variables your `mutationFn` accepts.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
+ */
 export interface MutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -150,6 +248,15 @@ export interface MutationOptions<
   '_defaulted'
 > {}
 
+/**
+ * The accessor `useMutation` expects as its first argument — Solid re-evaluates it reactively, so callbacks
+ * and other options can depend on signals.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` may throw.
+ * @template TVariables - The type of the variables your `mutationFn` accepts.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
+ */
 export type UseMutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -168,6 +275,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 `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` 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,
@@ -175,6 +292,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 `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` 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,
@@ -184,6 +311,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,
@@ -192,6 +322,15 @@ export type UseBaseMutationResult<
   >
 }
 
+/**
+ * The result of `useMutation`. Same as {@link UseBaseMutationResult}.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` 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,