@tanstack/preact-query 5.102.8 → 5.103.1

package/src/queryOptions.ts

@@ -59,7 +59,9 @@ export type UnusedSkipTokenOptions<
 > & {
   /**
    * `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.
+   * you don't intend to run the query yet, set `enabled: false` — omitting `queryFn` alone still triggers a
+   * fetch that fails with "Missing queryFn" unless `enabled` is `false` or a default query function has been
+   * defined. A default query function only supplies `queryFn`; it doesn't defer the fetch on its own.
    */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
@@ -108,6 +110,7 @@ export type DefinedInitialDataOptions<
  * 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.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
  * @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.
  *
@@ -122,9 +125,18 @@ export type DefinedInitialDataOptions<
  * })
  *
  * 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>)}</>
+ *   // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
+ *   // so the list stays visible alongside the error.
+ *   const { data, isError, error } = useQuery(postsOptions)
+ *
+ *   return (
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
  * }
  * ```
  */
@@ -144,23 +156,14 @@ export function queryOptions<
  * is the query key to generate options for.
  *
  * @see {@link useQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
  * @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
+ * A parameterized factory, so the same options object can be reused per `id`:
  * ```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'
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * export const postOptions = (id: string) =>
  *   queryOptions({
@@ -169,33 +172,13 @@ export function queryOptions<
  *   })
  *
  * 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 { data, isPending, isError, error } = useQuery(postOptions(id))
  *
- * const todosOptions = queryOptions({
- *   queryKey: ['todos'],
- *   queryFn: fetchTodos,
- * })
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
  *
- * useQuery(todosOptions)
- * useSuspenseQuery(todosOptions)
- * queryClient.query(todosOptions).catch(noop)
- * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ *   return <h1>{data.title}</h1>
+ * }
  * ```
  */
 export function queryOptions<
@@ -214,23 +197,15 @@ export function queryOptions<
  * is the query key to generate options for.
  *
  * @see {@link useQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
  * @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.
+ * @remarks This is the only overload that accepts `queryFn: skipToken`, shown below.
  *
  * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
  * ```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'
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * export const postOptions = (id: string) =>
  *   queryOptions({
@@ -239,33 +214,35 @@ export function queryOptions<
  *   })
  *
  * function Post({ id }: { id: string }) {
- *   const { data } = useQuery(postOptions(id))
- *   return <h1>{data?.title}</h1>
- * }
+ *   const { data, isPending, isError, error } = useQuery(postOptions(id))
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
  *
- * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
- * queryClient.query(postOptions(id)).catch(noop)
+ *   return <h1>{data.title}</h1>
+ * }
  * ```
  *
  * @example
- * The same options object works with every API that accepts query options:
+ * A factory that disables the query, type safe, until `postId` is set:
  * ```tsx
- * import {
- *   noop,
- *   queryOptions,
- *   useQuery,
- *   useSuspenseQuery,
- * } from '@tanstack/preact-query'
+ * import { queryOptions, skipToken, useQuery } from '@tanstack/preact-query'
  *
- * const todosOptions = queryOptions({
- *   queryKey: ['todos'],
- *   queryFn: fetchTodos,
- * })
+ * export const postOptions = (postId: number | undefined) =>
+ *   queryOptions({
+ *     queryKey: ['post', postId],
+ *     queryFn: postId != null ? () => fetchPost(postId) : skipToken,
+ *   })
+ *
+ * function Post({ postId }: { postId: number | undefined }) {
+ *   const { data, isLoading, isError, error } = useQuery(postOptions(postId))
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
  *
- * useQuery(todosOptions)
- * useSuspenseQuery(todosOptions)
- * queryClient.query(todosOptions).catch(noop)
- * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ *   return <h1>{data?.title}</h1>
+ * }
  * ```
  */
 export function queryOptions<

package/src/useInfiniteQuery.ts

@@ -19,7 +19,7 @@ import type {
 import { useBaseQuery } from './useBaseQuery'
 
 /**
- * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
  * This overload is selected when `initialData` is set.
@@ -31,16 +31,19 @@ import { useBaseQuery } from './useBaseQuery'
  * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
- * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
- * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
- * `isFetchingPreviousPage`.
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
+ * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
+ * `InfiniteData<TQueryFnData>` shape.
  *
  * @example
  * ```tsx
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data } = useInfiniteQuery({
+ *   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
+ *   const { data, isError, error } = useInfiniteQuery({
  *     queryKey: ['projects'],
  *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
  *     initialPageParam: 0,
@@ -48,7 +51,14 @@ import { useBaseQuery } from './useBaseQuery'
  *     initialData: { pages: [], pageParams: [] },
  *   })
  *
- *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ *   return (
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       </ul>
+ *     </div>
+ *   )
  * }
  * ```
  */
@@ -70,7 +80,7 @@ export function useInfiniteQuery<
 ): DefinedUseInfiniteQueryResult<TData, TError>
 
 /**
- * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
  * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
@@ -80,16 +90,18 @@ export function useInfiniteQuery<
  * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
- * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
- * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
- * `isFetchingPreviousPage`.
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
+ * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
+ * `InfiniteData<TQueryFnData>` shape.
  *
  * @example
+ * Fetching the next page from a "Load More" button click:
  * ```tsx
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
  *     useInfiniteQuery({
  *       queryKey: ['projects'],
  *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
@@ -97,17 +109,81 @@ export function useInfiniteQuery<
  *       getNextPageParam: (lastPage) => lastPage.nextId,
  *     })
  *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
- *     <button
- *       onClick={() => fetchNextPage()}
- *       disabled={!hasNextPage || isFetching}
- *     >
- *       {isFetchingNextPage
- *         ? 'Loading more...'
- *         : hasNextPage
- *           ? 'Load More'
- *           : 'Nothing more to load'}
- *     </button>
+ *     <>
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
+ *       </button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
+ * sentinel element after the list:
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ * import { useEffect, useRef } from 'preact/hooks'
+ *
+ * function Projects() {
+ *   const {
+ *     data,
+ *     isPending,
+ *     isError,
+ *     error,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetching,
+ *     isFetchingNextPage,
+ *   } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   const sentinelRef = useRef<HTMLDivElement>(null)
+ *
+ *   useEffect(() => {
+ *     const sentinel = sentinelRef.current
+ *     if (sentinel == null || !hasNextPage || isFetching) return
+ *
+ *     const observer = new IntersectionObserver(([entry]) => {
+ *       if (entry?.isIntersecting) fetchNextPage()
+ *     })
+ *     observer.observe(sentinel)
+ *
+ *     return () => observer.disconnect()
+ *   }, [hasNextPage, isFetching, fetchNextPage])
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <>
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
+ *       <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>
+ *     </>
  *   )
  * }
  * ```
@@ -130,7 +206,7 @@ export function useInfiniteQuery<
 ): UseInfiniteQueryResult<TData, TError>
 
 /**
- * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
  * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
@@ -140,16 +216,18 @@ export function useInfiniteQuery<
  * @param options - The {@link UseInfiniteQueryOptions} to use — everything you can pass to `useInfiniteQuery`.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
- * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
- * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
- * `isFetchingPreviousPage`.
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
+ * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
+ * `InfiniteData<TQueryFnData>` shape.
  *
  * @example
+ * Fetching the next page from a "Load More" button click:
  * ```tsx
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
  *     useInfiniteQuery({
  *       queryKey: ['projects'],
  *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
@@ -157,17 +235,111 @@ export function useInfiniteQuery<
  *       getNextPageParam: (lastPage) => lastPage.nextId,
  *     })
  *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <>
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
+ *       </button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
+ * sentinel element after the list:
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ * import { useEffect, useRef } from 'preact/hooks'
+ *
+ * function Projects() {
+ *   const {
+ *     data,
+ *     isPending,
+ *     isError,
+ *     error,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetching,
+ *     isFetchingNextPage,
+ *   } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   const sentinelRef = useRef<HTMLDivElement>(null)
+ *
+ *   useEffect(() => {
+ *     const sentinel = sentinelRef.current
+ *     if (sentinel == null || !hasNextPage || isFetching) return
+ *
+ *     const observer = new IntersectionObserver(([entry]) => {
+ *       if (entry?.isIntersecting) fetchNextPage()
+ *     })
+ *     observer.observe(sentinel)
+ *
+ *     return () => observer.disconnect()
+ *   }, [hasNextPage, isFetching, fetchNextPage])
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <>
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
+ *       <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * A query that's disabled, type safe, until `postId` is set — pass `skipToken` as `queryFn`
+ * instead of setting `enabled: false`:
+ * ```tsx
+ * import { skipToken, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Comments({ postId }: { postId: string | undefined }) {
+ *   // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
+ *   const { data, isLoading, isError, error } = useInfiniteQuery({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn:
+ *       postId != null
+ *         ? ({ pageParam }) => fetchComments(postId, pageParam)
+ *         : skipToken,
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
- *     <button
- *       onClick={() => fetchNextPage()}
- *       disabled={!hasNextPage || isFetching}
- *     >
- *       {isFetchingNextPage
- *         ? 'Loading more...'
- *         : hasNextPage
- *           ? 'Load More'
- *           : 'Nothing more to load'}
- *     </button>
+ *     <ul>
+ *       {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
  *   )
  * }
  * ```

package/src/useIsFetching.ts

@@ -6,8 +6,8 @@ import { useQueryClient } from './QueryClientProvider'
 import { useSyncExternalStore } from './utils'
 
 /**
- * `useIsFetching` is an optional hook that returns the `number` of the queries that your application is loading or
- * fetching in the background (useful for app-wide loading indicators).
+ * The `useIsFetching` hook returns the `number` of the queries that your application is loading or fetching in
+ * the background (useful for app-wide loading indicators).
  *
  * @param filters - The {@link QueryFilters} to narrow down the matched queries.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
@@ -19,10 +19,12 @@ import { useSyncExternalStore } from './utils'
  * ```tsx
  * import { useIsFetching } from '@tanstack/preact-query'
  *
- * // How many queries are fetching?
- * const isFetching = useIsFetching()
- * // How many queries matching the posts prefix are fetching?
- * const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+ * function PostsFetchingIndicator() {
+ *   // How many queries matching the posts prefix are fetching?
+ *   const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+ *
+ *   return isFetchingPosts ? <span>Refreshing posts...</span> : null
+ * }
  * ```
  *
  * @example

package/src/useMutation.ts

@@ -21,14 +21,16 @@ import { useSyncExternalStore } from './utils'
  * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
  * `useMutation` is the hook for that.
  *
- * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites.
+ * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites, or to look
+ * the mutation up elsewhere via its `mutationKey` (e.g. with `useMutationState`).
  * @param options - The {@link UseMutationOptions} to use — everything you can pass to `useMutation`.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
  * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
  * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
- * mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
- * made.
+ * mutation definition. Hook-level callbacks (passed to `options`) fire for every mutation; per-call callbacks
+ * fire only for the latest call you've made, and only while the component is still mounted — unmounting before
+ * the mutation settles removes the subscription and prevents them from firing.
  *
  * @example
  * ```tsx
@@ -105,11 +107,11 @@ import { useSyncExternalStore } from './utils'
  *         newTodo,
  *       ])
  *
- *       // Passed to `onError` as `context` if the mutation fails.
+ *       // Passed to `onError` as `onMutateResult` if the mutation fails.
  *       return { previousTodos }
  *     },
- *     onError: (_err, _newTodo, context) => {
- *       queryClient.setQueryData(['todos'], context?.previousTodos)
+ *     onError: (_err, _newTodo, onMutateResult) => {
+ *       queryClient.setQueryData(['todos'], onMutateResult?.previousTodos)
  *     },
  *     onSettled: () => {
  *       queryClient.invalidateQueries({ queryKey: ['todos'] })
@@ -124,7 +126,7 @@ import { useSyncExternalStore } from './utils'
  *
  * @example
  * Callbacks passed per call to `mutate` only fire for the last call — `mutateAsync` gives you a
- * promise per call instead, so you can wait for all of them:
+ * promise per call instead, so you can wait for all of them when they succeed:
  * ```tsx
  * import { useMutation, useQueryClient } from '@tanstack/preact-query'
  *
@@ -168,13 +170,13 @@ import { useSyncExternalStore } from './utils'
  *   })
  *
  *   async function handleAddAll(todos: Array<string>) {
- *     const results = await Promise.allSettled(
+ *     const addResults = await Promise.allSettled(
  *       todos.map((todo) => addMutation.mutateAsync(todo)),
  *     )
  *
- *     results.forEach((result, index) => {
- *       if (result.status === 'rejected') {
- *         console.error(`Failed to add "${todos[index]}":`, result.reason)
+ *     addResults.forEach((addResult, index) => {
+ *       if (addResult.status === 'rejected') {
+ *         console.error(`Failed to add "${todos[index]}":`, addResult.reason)
  *       }
  *     })
  *   }