@tanstack/preact-query 5.102.4 → 5.102.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-query",
-  "version": "5.102.4",
+  "version": "5.102.5",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in preact",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "!build/codemods/**/__tests__"
   ],
   "dependencies": {
-    "@tanstack/query-core": "5.102.4"
+    "@tanstack/query-core": "5.102.5"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.2",
@@ -55,7 +55,7 @@
     "preact-render-to-string": "^6.6.4",
     "typescript": "6.0.3",
     "typescript-eslint": "^8.54.0",
-    "@tanstack/query-persist-client-core": "5.102.4",
+    "@tanstack/query-persist-client-core": "5.102.5",
     "@tanstack/query-test-utils": "0.0.0"
   },
   "peerDependencies": {

package/src/QueryErrorResetBoundary.tsx

@@ -143,15 +143,17 @@ export interface QueryErrorResetBoundaryProps {
  *   return children
  * }
  *
- * const App = () => (
- *   <QueryErrorResetBoundary>
- *     {({ reset }) => (
- *       <ErrorBoundary reset={reset}>
- *         <Page />
- *       </ErrorBoundary>
- *     )}
- *   </QueryErrorResetBoundary>
- * )
+ * function App() {
+ *   return (
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary reset={reset}>
+ *           <Page />
+ *         </ErrorBoundary>
+ *       )}
+ *     </QueryErrorResetBoundary>
+ *   )
+ * }
  * ```
  */
 export const QueryErrorResetBoundary = ({

package/src/useInfiniteQuery.ts

@@ -86,25 +86,27 @@ export function useInfiniteQuery<
  *
  * @example
  * ```tsx
- * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
- *
- * const projectsOptions = infiniteQueryOptions({
- *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextId,
- * })
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
- *     useInfiniteQuery(projectsOptions)
+ *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
  *
  *   return (
  *     <button
  *       onClick={() => fetchNextPage()}
- *       disabled={!hasNextPage || isFetchingNextPage}
+ *       disabled={!hasNextPage || isFetching}
  *     >
- *       Load More
+ *       {isFetchingNextPage
+ *         ? 'Loading more...'
+ *         : hasNextPage
+ *           ? 'Load More'
+ *           : 'Nothing more to load'}
  *     </button>
  *   )
  * }
@@ -144,25 +146,27 @@ export function useInfiniteQuery<
  *
  * @example
  * ```tsx
- * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
- *
- * const projectsOptions = infiniteQueryOptions({
- *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextId,
- * })
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
- *     useInfiniteQuery(projectsOptions)
+ *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
  *
  *   return (
  *     <button
  *       onClick={() => fetchNextPage()}
- *       disabled={!hasNextPage || isFetchingNextPage}
+ *       disabled={!hasNextPage || isFetching}
  *     >
- *       Load More
+ *       {isFetchingNextPage
+ *         ? 'Loading more...'
+ *         : hasNextPage
+ *           ? 'Load More'
+ *           : 'Nothing more to load'}
  *     </button>
  *   )
  * }

package/src/useIsFetching.ts

@@ -24,6 +24,20 @@ import { useSyncExternalStore } from './utils'
  * // How many queries matching the posts prefix are fetching?
  * const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
  * ```
+ *
+ * @example
+ * A global loading indicator for any query fetching in the background, not just the ones on screen:
+ * ```tsx
+ * import { useIsFetching } from '@tanstack/preact-query'
+ *
+ * function GlobalLoadingIndicator() {
+ *   const isFetching = useIsFetching()
+ *
+ *   return isFetching ? (
+ *     <div>Queries are fetching in the background...</div>
+ *   ) : null
+ * }
+ * ```
  */
 export function useIsFetching(
   filters?: QueryFilters,

package/src/useMutation.ts

@@ -43,7 +43,45 @@ import { useSyncExternalStore } from './utils'
  *   })
  *
  *   return (
- *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *     <button
+ *       onClick={() =>
+ *         addMutation.mutate('Item', {
+ *           onError: (error) => console.error('Failed to add item:', error),
+ *         })
+ *       }
+ *     >
+ *       Add
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Rendering the mutation's own state, rather than just firing it off:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {addMutation.isPending ? (
+ *         'Adding todo...'
+ *       ) : (
+ *         <>
+ *           {addMutation.isError ? (
+ *             <div>An error occurred: {addMutation.error.message}</div>
+ *           ) : null}
+ *           <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *         </>
+ *       )}
+ *     </div>
  *   )
  * }
  * ```
@@ -83,6 +121,71 @@ 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:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodos() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   async function handleAddAll(todos: Array<string>) {
+ *     try {
+ *       await Promise.all(todos.map((todo) => addMutation.mutateAsync(todo)))
+ *     } catch (error) {
+ *       console.error('Failed to add todos:', error)
+ *     }
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleAddAll(['Todo 1', 'Todo 2', 'Todo 3'])}>
+ *       Add all
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * If some of the mutations above can fail independently of the others, and you want to know which ones
+ * did — rather than losing that information the moment the first one rejects — swap `Promise.all` for
+ * `Promise.allSettled`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodos() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   async function handleAddAll(todos: Array<string>) {
+ *     const results = 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)
+ *       }
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleAddAll(['Todo 1', 'Todo 2', 'Todo 3'])}>
+ *       Add all
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export function useMutation<
   TData = unknown,

package/src/useQuery.ts

@@ -83,6 +83,24 @@ export function useQuery<
  *   )
  * }
  * ```
+ *
+ * @example
+ * The same query, checking `isPending`/`isError` instead of `status` — pick whichever reads better to you:
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function Posts() {
+ *   const { isPending, isError, data, error } = useQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,
@@ -130,17 +148,22 @@ export function useQuery<
  * ```
  *
  * @example
- * A dependent query, only enabled once `postId` is set:
+ * 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
  * import { useQuery } from '@tanstack/preact-query'
  *
  * function Post({ postId }: { postId: number | undefined }) {
- *   const { data } = useQuery({
+ *   const { data, isLoading, isError, error } = useQuery({
  *     queryKey: ['post', postId],
  *     queryFn: () => fetchPost(postId!),
  *     enabled: postId != null,
  *   })
  *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return <h1>{data?.title}</h1>
  * }
  * ```
@@ -165,6 +188,35 @@ export function useQuery<
  *   return <h1>{data?.title}</h1>
  * }
  * ```
+ *
+ * @example
+ * Paginated data, keeping the previous page's data visible while the next page loads:
+ * ```tsx
+ * import { keepPreviousData, useQuery } from '@tanstack/preact-query'
+ * import { useState } from 'preact/hooks'
+ *
+ * function Posts() {
+ *   const [page, setPage] = useState(0)
+ *
+ *   const { data, isPlaceholderData } = useQuery({
+ *     queryKey: ['posts', page],
+ *     queryFn: () => fetchPosts(page),
+ *     placeholderData: keepPreviousData,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {data?.map((post) => <p key={post.id}>{post.title}</p>)}
+ *       <button
+ *         disabled={isPlaceholderData}
+ *         onClick={() => setPage((old) => old + 1)}
+ *       >
+ *         Next Page
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,

package/src/useSuspenseInfiniteQuery.ts

@@ -35,20 +35,28 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * function Projects() {
  *   // `data` is guaranteed to be defined here — no `isPending` check needed.
- *   const { data, fetchNextPage, hasNextPage } = useSuspenseInfiniteQuery({
- *     queryKey: ['projects'],
- *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *     initialPageParam: 0,
- *     getNextPageParam: (lastPage) => lastPage.nextId,
- *   })
+ *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useSuspenseInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
  *
  *   return (
  *     <div>
  *       {data.pages.map((page) =>
  *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
  *       )}
- *       <button onClick={() => fetchNextPage()} disabled={!hasNextPage}>
- *         Load More
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
  *       </button>
  *     </div>
  *   )

package/src/useSuspenseQueries.ts

@@ -202,7 +202,7 @@ export type SuspenseQueriesResults<
  *
  * function Posts({ ids }: { ids: Array<number> }) {
  *   // Every result is guaranteed to be defined — no per-query `isPending` check needed.
- *   const results = useSuspenseQueries({
+ *   const postQueries = useSuspenseQueries({
  *     queries: ids.map((id) => ({
  *       queryKey: ['post', id],
  *       queryFn: () => fetchPost(id),
@@ -211,8 +211,8 @@ export type SuspenseQueriesResults<
  *
  *   return (
  *     <ul>
- *       {results.map((result) => (
- *         <li key={result.data.id}>{result.data.title}</li>
+ *       {postQueries.map((query) => (
+ *         <li key={query.data.id}>{query.data.title}</li>
  *       ))}
  *     </ul>
  *   )
@@ -226,6 +226,40 @@ export type SuspenseQueriesResults<
  *   )
  * }
  * ```
+ *
+ * @example
+ * Several different queries — use `useSuspenseQueries` instead of multiple `useSuspenseQuery` calls, so
+ * they fetch in parallel rather than suspending one after another:
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Dashboard() {
+ *   const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
+ *     queries: [
+ *       { queryKey: ['users'], queryFn: fetchUsers },
+ *       { queryKey: ['teams'], queryFn: fetchTeams },
+ *       { queryKey: ['projects'], queryFn: fetchProjects },
+ *     ],
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <UserList users={usersQuery.data} />
+ *       <TeamList teams={teamsQuery.data} />
+ *       <ProjectList projects={projectsQuery.data} />
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *       <Dashboard />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function useSuspenseQueries<
   T extends Array<any>,
@@ -269,7 +303,7 @@ export function useSuspenseQueries<
  *
  * function Posts({ ids }: { ids: Array<number> }) {
  *   // Every result is guaranteed to be defined — no per-query `isPending` check needed.
- *   const results = useSuspenseQueries({
+ *   const postQueries = useSuspenseQueries({
  *     queries: ids.map((id) => ({
  *       queryKey: ['post', id],
  *       queryFn: () => fetchPost(id),
@@ -278,8 +312,8 @@ export function useSuspenseQueries<
  *
  *   return (
  *     <ul>
- *       {results.map((result) => (
- *         <li key={result.data.id}>{result.data.title}</li>
+ *       {postQueries.map((query) => (
+ *         <li key={query.data.id}>{query.data.title}</li>
  *       ))}
  *     </ul>
  *   )
@@ -293,6 +327,40 @@ export function useSuspenseQueries<
  *   )
  * }
  * ```
+ *
+ * @example
+ * Several different queries — use `useSuspenseQueries` instead of multiple `useSuspenseQuery` calls, so
+ * they fetch in parallel rather than suspending one after another:
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Dashboard() {
+ *   const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
+ *     queries: [
+ *       { queryKey: ['users'], queryFn: fetchUsers },
+ *       { queryKey: ['teams'], queryFn: fetchTeams },
+ *       { queryKey: ['projects'], queryFn: fetchProjects },
+ *     ],
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <UserList users={usersQuery.data} />
+ *       <TeamList teams={teamsQuery.data} />
+ *       <ProjectList projects={projectsQuery.data} />
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *       <Dashboard />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function useSuspenseQueries<
   T extends Array<any>,

package/src/useSuspenseQuery.ts

@@ -11,6 +11,10 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * Caveat: cancellation does not work.
  *
+ * @remarks Multiple `useSuspenseQuery` 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.
+ * Use {@link useSuspenseQueries} instead when you have more than one suspenseful query in a component, so they
+ * fetch in parallel.
  * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.