@tanstack/preact-query 5.102.8 → 5.103.0

package/src/useMutationState.ts

@@ -12,22 +12,24 @@ import { useQueryClient } from './QueryClientProvider'
 import { useSyncExternalStore } from './utils'
 
 /**
- * `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+ * The `useIsMutating` hook returns the `number` of mutations that your application currently has `pending`
  * (useful for app-wide loading indicators).
  *
  * @param filters - The {@link MutationFilters} to narrow down the matched mutations.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
- * @returns Will be the `number` of the mutations that your application is currently fetching.
+ * @returns Will be the `number` of the mutations that your application currently has `pending`.
  *
  * @example
  * ```tsx
  * import { useIsMutating } from '@tanstack/preact-query'
  *
- * // How many mutations are fetching?
- * const isMutating = useIsMutating()
- * // How many mutations matching the posts prefix are fetching?
- * const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ * function PostsMutatingIndicator() {
+ *   // How many mutations matching the posts prefix are in progress?
+ *   const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ *
+ *   return isMutatingPosts ? <span>Saving posts...</span> : null
+ * }
  * ```
  */
 export function useIsMutating(
@@ -95,10 +97,14 @@ function getResult<
  * ```tsx
  * import { useMutationState } from '@tanstack/preact-query'
  *
- * const variables = useMutationState({
- *   filters: { status: 'pending' },
- *   select: (mutation) => mutation.state.variables,
- * })
+ * function PendingPosts() {
+ *   const pendingVariables = useMutationState({
+ *     filters: { status: 'pending' },
+ *     select: (mutation) => mutation.state.variables,
+ *   })
+ *
+ *   return <>{pendingVariables.length} posts saving...</>
+ * }
  * ```
  *
  * @example
@@ -108,30 +114,44 @@ function getResult<
  *
  * const mutationKey = ['posts']
  *
- * // Some mutation that we want to get the state for
- * const mutation = useMutation({
- *   mutationKey,
- *   mutationFn: createPosts,
- * })
- *
- * const data = useMutationState({
- *   // this mutation key needs to match the mutation key of the given mutation (see above)
- *   filters: { mutationKey },
- *   select: (mutation) => mutation.state.data,
- * })
+ * function Posts() {
+ *   // Some mutation that we want to get the state for
+ *   const mutation = useMutation({
+ *     mutationKey,
+ *     mutationFn: createPosts,
+ *   })
+ *
+ *   const savedPosts = useMutationState({
+ *     // this mutation key needs to match the mutation key of the given mutation (see above)
+ *     filters: { mutationKey, status: 'success' },
+ *     select: (mutation) => mutation.state.data,
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => mutation.mutate(['New Post'])}>
+ *       Create post ({savedPosts.length} saved so far)
+ *     </button>
+ *   )
+ * }
  * ```
  *
  * @example
- * Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
- * mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
- * latest invocation:
+ * Access the latest successful mutation data via the `mutationKey`. Each invocation of `mutate` adds a new
+ * entry to the mutation cache for `gcTime` milliseconds — with the `status: 'success'` filter below, check the
+ * last item that `useMutationState` returns to get the latest successful invocation:
  * ```tsx
- * const data = useMutationState({
- *   filters: { mutationKey: ['posts'] },
- *   select: (mutation) => mutation.state.data,
- * })
+ * import { useMutationState } from '@tanstack/preact-query'
+ *
+ * function LatestPost() {
+ *   const savedPosts = useMutationState({
+ *     filters: { mutationKey: ['posts'], status: 'success' },
+ *     select: (mutation) => mutation.state.data,
+ *   })
+ *
+ *   const latestSavedPost = savedPosts[savedPosts.length - 1]
  *
- * const latest = data[data.length - 1]
+ *   return <>{latestSavedPost ? 'Saved' : 'Nothing saved yet'}</>
+ * }
  * ```
  */
 export function useMutationState<

package/src/useQueries.ts

@@ -225,8 +225,9 @@ export type QueriesResults<
 /**
  * The `useQueries` hook can be used to fetch a variable number of queries.
  *
- * The `queries` key accepts an array with query option objects identical to `useQuery` (excluding the
- * `queryClient` option - because the `QueryClient` can be passed in on the top level).
+ * The `queries` key accepts an array with query option objects mostly identical to `useQuery` — see the
+ * `queries` parameter below for the differences. A custom `QueryClient` is supplied once, as `useQueries`' own
+ * top-level second argument, rather than per query.
  *
  * Having the same query key more than once in the array of query objects may cause some data to be shared
  * between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired
@@ -244,32 +245,58 @@ export type QueriesResults<
  * ```tsx
  * import { useQueries } from '@tanstack/preact-query'
  *
- * const ids = [1, 2, 3]
- * const results = useQueries({
- *   queries: ids.map((id) => ({
- *     queryKey: ['post', id],
- *     queryFn: () => fetchPost(id),
- *     staleTime: Infinity,
- *   })),
- * })
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   const postQueries = useQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *       staleTime: Infinity,
+ *     })),
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {postQueries.map((query, index) => {
+ *         if (query.isPending) return <li key={ids[index]}>Loading...</li>
+ *         if (query.isError) return <li key={ids[index]}>Error: {query.error.message}</li>
+ *         return <li key={ids[index]}>{query.data.title}</li>
+ *       })}
+ *     </ul>
+ *   )
+ * }
  * ```
  *
  * @example
  * Combining results into a single value:
  * ```tsx
- * const ids = [1, 2, 3]
- * const combinedQueries = useQueries({
- *   queries: ids.map((id) => ({
- *     queryKey: ['post', id],
- *     queryFn: () => fetchPost(id),
- *   })),
- *   combine: (results) => {
- *     return {
- *       data: results.map((result) => result.data),
- *       pending: results.some((result) => result.isPending),
- *     }
- *   },
- * })
+ * import { useQueries } from '@tanstack/preact-query'
+ *
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   const { data, isPending, isError } = useQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *     combine: (postQueries) => {
+ *       return {
+ *         data: postQueries.map((query) => query.data),
+ *         isPending: postQueries.some((query) => query.isPending),
+ *         isError: postQueries.some((query) => query.isError),
+ *       }
+ *     },
+ *   })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return 'Error loading posts'
+ *
+ *   return (
+ *     <ul>
+ *       {data.map((post) => (
+ *         <li key={post?.id}>{post?.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
  * ```
  */
 export function useQueries<

package/src/useQuery.ts

@@ -28,14 +28,22 @@ import { useBaseQuery } from './useBaseQuery'
  * import { useQuery } from '@tanstack/preact-query'
  *
  * function Posts() {
- *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
- *   const { data } = useQuery({
+ *   // `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({
  *     queryKey: ['posts'],
  *     queryFn: fetchPosts,
  *     initialData: [],
  *   })
  *
- *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ *   return (
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
  * }
  * ```
  */
@@ -54,30 +62,30 @@ export function useQuery<
  * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
- * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
- * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
- * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if
+ * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError`
+ * are derived booleans for convenience.
  *
  * @example
  * ```tsx
- * import { queryOptions, useQuery } from '@tanstack/preact-query'
- *
- * const postsOptions = queryOptions({
- *   queryKey: ['posts'],
- *   queryFn: fetchPosts,
- * })
+ * import { useQuery } from '@tanstack/preact-query'
  *
  * function Posts() {
- *   const { status, data, error, isFetching } = useQuery(postsOptions)
+ *   const { status, data, error, isFetching } = useQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
  *
  *   if (status === 'pending') return 'Loading...'
  *   if (status === 'error') return <span>Error: {error.message}</span>
  *
  *   return (
  *     <div>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
  *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
  *     </div>
  *   )
@@ -98,7 +106,11 @@ export function useQuery<
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *
- *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *     </ul>
+ *   )
  * }
  * ```
  */
@@ -117,30 +129,30 @@ export function useQuery<
  * @param options - The {@link UseQueryOptions} to use — everything you can pass to `useQuery`.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
- * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
- * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
- * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ * @returns The current query result. `status` is `pending` if there is no cached data to display, `error` if
+ * the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError`
+ * are derived booleans for convenience.
  *
  * @example
  * ```tsx
- * import { queryOptions, useQuery } from '@tanstack/preact-query'
- *
- * const postsOptions = queryOptions({
- *   queryKey: ['posts'],
- *   queryFn: fetchPosts,
- * })
+ * import { useQuery } from '@tanstack/preact-query'
  *
  * function Posts() {
- *   const { status, data, error, isFetching } = useQuery(postsOptions)
+ *   const { status, data, error, isFetching } = useQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
  *
  *   if (status === 'pending') return 'Loading...'
  *   if (status === 'error') return <span>Error: {error.message}</span>
  *
  *   return (
  *     <div>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
  *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
  *     </div>
  *   )
@@ -148,6 +160,26 @@ export function useQuery<
  * ```
  *
  * @example
+ * `select` derives whatever `data` a component needs from the cached value, without changing what's
+ * actually stored in the cache — the cache still holds the full `Post[]`, but `data` here is a `number`:
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function PostCount() {
+ *   const { data, isPending, isError, error } = useQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     select: (posts) => posts.length,
+ *   })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <span>{data} posts</span>
+ * }
+ * ```
+ *
+ * @example
  * A dependent query, only enabled once `postId` is set — use `isLoading`, not `isPending`, so the
  * loading state doesn't show while the query is disabled:
  * ```tsx
@@ -169,6 +201,28 @@ export function useQuery<
  * ```
  *
  * @example
+ * The same dependent query, type safe: `skipToken` disables the query without needing the
+ * non-null assertion above, since `queryFn` is only ever called when `postId` is defined.
+ * `refetch` doesn't work while `queryFn` is `skipToken` — use `enabled: false` instead if you
+ * need to trigger the query manually:
+ * ```tsx
+ * import { skipToken, useQuery } from '@tanstack/preact-query'
+ *
+ * function Post({ postId }: { postId: number | undefined }) {
+ *   const { data, isLoading, isError, error } = useQuery({
+ *     queryKey: ['post', postId],
+ *     queryFn: postId != null ? () => fetchPost(postId) : skipToken,
+ *   })
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
+ *
+ * @example
  * Seeding a detail query from an already-cached list, to skip the loading state:
  * ```tsx
  * import { useQuery, useQueryClient } from '@tanstack/preact-query'
@@ -176,7 +230,7 @@ export function useQuery<
  * function Post({ postId }: { postId: number }) {
  *   const queryClient = useQueryClient()
  *
- *   const { data } = useQuery({
+ *   const { data, isError, error } = useQuery({
  *     queryKey: ['post', postId],
  *     queryFn: () => fetchPost(postId),
  *     initialData: () =>
@@ -185,6 +239,8 @@ export function useQuery<
  *         ?.find((post) => post.id === postId),
  *   })
  *
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return <h1>{data?.title}</h1>
  * }
  * ```
@@ -198,15 +254,19 @@ export function useQuery<
  * function Posts() {
  *   const [page, setPage] = useState(0)
  *
- *   const { data, isPlaceholderData } = useQuery({
+ *   const { data, isPlaceholderData, isError, error } = useQuery({
  *     queryKey: ['posts', page],
  *     queryFn: () => fetchPosts(page),
  *     placeholderData: keepPreviousData,
  *   })
  *
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <div>
- *       {data?.map((post) => <p key={post.id}>{post.title}</p>)}
+ *       <ul>
+ *         {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
  *       <button
  *         disabled={isPlaceholderData}
  *         onClick={() => setPage((old) => old + 1)}

package/src/useSuspenseInfiniteQuery.ts

@@ -21,6 +21,13 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * Caveat: cancellation does not work.
  *
+ * @remarks Multiple suspenseful query calls in the same component suspend serially, causing a request
+ * waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until
+ * then. There's no way to parallelize multiple infinite queries under Suspense. Also keep in mind that
+ * imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch behavior,
+ * resulting in outdated data. Make sure to call these functions only in response to user actions, or add
+ * conditions like `hasNextPage && !isFetching`.
+ * @see {@link useInfiniteQuery} for the non-Suspense version of this hook.
  * @param options - The {@link UseSuspenseInfiniteQueryOptions} to use — the same options as `useInfiniteQuery`, minus the ones listed above.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
@@ -29,9 +36,17 @@ import { useBaseQuery } from './useBaseQuery'
  * accordingly).
  *
  * @example
+ * The query error is thrown if a fetch fails and no cached data exists yet, so an error boundary is
+ * required around `<Suspense>`. A failed background refetch instead continues to render the cached data.
+ * Use {@link QueryErrorResetBoundary} to let the user retry after such an error:
  * ```tsx
  * import { Suspense } from 'preact/compat'
- * import { useSuspenseInfiniteQuery } from '@tanstack/preact-query'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import {
+ *   QueryErrorResetBoundary,
+ *   useSuspenseInfiniteQuery,
+ * } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
  *
  * function Projects() {
  *   // `data` is guaranteed to be defined here — no `isPending` check needed.
@@ -45,9 +60,11 @@ import { useBaseQuery } from './useBaseQuery'
  *
  *   return (
  *     <div>
- *       {data.pages.map((page) =>
- *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
- *       )}
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
  *       <button
  *         onClick={() => fetchNextPage()}
  *         disabled={!hasNextPage || isFetching}
@@ -64,11 +81,44 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading projects...</h1>}>
- *       <Projects />
- *     </Suspense>
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading projects...</h1>}>
+ *             <Projects />
+ *           </Suspense>
+ *         </ErrorBoundary>
+ *       )}
+ *     </QueryErrorResetBoundary>
  *   )
  * }
+ *
+ * function ErrorBoundary({
+ *   children,
+ *   onReset,
+ *   fallbackRender,
+ * }: {
+ *   children: ComponentChildren
+ *   onReset: () => void
+ *   fallbackRender: (props: {
+ *     error: Error
+ *     resetErrorBoundary: () => void
+ *   }) => ComponentChildren
+ * }) {
+ *   const [error, resetErrorBoundary] = useErrorBoundary(() => onReset())
+ *
+ *   if (error) return fallbackRender({ error, resetErrorBoundary })
+ *
+ *   return children
+ * }
  * ```
  */
 export function useSuspenseInfiniteQuery<