@tanstack/preact-query 5.102.8 → 5.103.0

package/src/useSuspenseQueries.ts

@@ -181,8 +181,8 @@ export type SuspenseQueriesResults<
         : { [K in keyof T]: GetUseSuspenseQueryResult<T[K]> }
 
 /**
- * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
- * `throwOnError`, `enabled`, or `placeholderData`.
+ * The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed`
+ * option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`.
  *
  * @param options - The `queries` array to run in Suspense, and an optional `combine` function.
  * @param queryClient - Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context
@@ -196,9 +196,17 @@ export type SuspenseQueriesResults<
  * this, make sure to set a high enough `staleTime`. Cancellation does not work.
  *
  * @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 { useSuspenseQueries } from '@tanstack/preact-query'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import {
+ *   QueryErrorResetBoundary,
+ *   useSuspenseQueries,
+ * } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
  *
  * function Posts({ ids }: { ids: Array<number> }) {
  *   // Every result is guaranteed to be defined — no per-query `isPending` check needed.
@@ -220,11 +228,44 @@ export type SuspenseQueriesResults<
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading posts...</h1>}>
- *       <Posts ids={[1, 2, 3]} />
- *     </Suspense>
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading posts...</h1>}>
+ *             <Posts ids={[1, 2, 3]} />
+ *           </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
+ * }
  * ```
  *
  * @example
@@ -232,7 +273,12 @@ export type SuspenseQueriesResults<
  * they fetch in parallel rather than suspending one after another:
  * ```tsx
  * import { Suspense } from 'preact/compat'
- * import { useSuspenseQueries } from '@tanstack/preact-query'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import {
+ *   QueryErrorResetBoundary,
+ *   useSuspenseQueries,
+ * } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
  *
  * function Dashboard() {
  *   const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
@@ -254,11 +300,110 @@ export type SuspenseQueriesResults<
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading dashboard...</h1>}>
- *       <Dashboard />
- *     </Suspense>
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *             <Dashboard />
+ *           </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
+ * }
+ * ```
+ *
+ * @example
+ * `combine`s the results into a single boolean, so `Refresh` only re-renders when that boolean changes,
+ * not on every individual query update. This overload is the only one that accepts `combine`:
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import {
+ *   QueryErrorResetBoundary,
+ *   useSuspenseQueries,
+ * } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
+ *
+ * function Refresh() {
+ *   const anyFetching = useSuspenseQueries({
+ *     queries: [
+ *       { queryKey: ['users'], queryFn: fetchUsers },
+ *       { queryKey: ['teams'], queryFn: fetchTeams },
+ *     ],
+ *     combine: (results) => results.some((result) => result.isFetching),
+ *   })
+ *
+ *   return anyFetching ? <span>Refreshing…</span> : null
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *             <Refresh />
+ *           </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 useSuspenseQueries<
@@ -282,8 +427,8 @@ export function useSuspenseQueries<
 ): TCombinedResult
 
 /**
- * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
- * `throwOnError`, `enabled`, or `placeholderData`.
+ * The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed`
+ * option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`.
  *
  * @param options - The `queries` array to run in Suspense, and an optional `combine` function.
  * @param queryClient - Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context
@@ -297,9 +442,17 @@ export function useSuspenseQueries<
  * this, make sure to set a high enough `staleTime`. Cancellation does not work.
  *
  * @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 { useSuspenseQueries } from '@tanstack/preact-query'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import {
+ *   QueryErrorResetBoundary,
+ *   useSuspenseQueries,
+ * } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
  *
  * function Posts({ ids }: { ids: Array<number> }) {
  *   // Every result is guaranteed to be defined — no per-query `isPending` check needed.
@@ -321,11 +474,44 @@ export function useSuspenseQueries<
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading posts...</h1>}>
- *       <Posts ids={[1, 2, 3]} />
- *     </Suspense>
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading posts...</h1>}>
+ *             <Posts ids={[1, 2, 3]} />
+ *           </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
+ * }
  * ```
  *
  * @example
@@ -333,7 +519,12 @@ export function useSuspenseQueries<
  * they fetch in parallel rather than suspending one after another:
  * ```tsx
  * import { Suspense } from 'preact/compat'
- * import { useSuspenseQueries } from '@tanstack/preact-query'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import {
+ *   QueryErrorResetBoundary,
+ *   useSuspenseQueries,
+ * } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
  *
  * function Dashboard() {
  *   const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
@@ -355,11 +546,44 @@ export function useSuspenseQueries<
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading dashboard...</h1>}>
- *       <Dashboard />
- *     </Suspense>
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *             <Dashboard />
+ *           </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 useSuspenseQueries<

package/src/useSuspenseQuery.ts

@@ -22,9 +22,14 @@ import { useBaseQuery } from './useBaseQuery'
  * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
  *
  * @example
+ * The query error is thrown if the 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 { useSuspenseQuery } from '@tanstack/preact-query'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
  *
  * function Posts() {
  *   // `data` is guaranteed to be defined here — no `isPending` check needed.
@@ -35,21 +40,56 @@ import { useBaseQuery } from './useBaseQuery'
  *
  *   return (
  *     <div>
- *       <h1>Posts {isFetching ? <Spinner /> : null}</h1>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
+ *       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
  *     </div>
  *   )
  * }
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading posts...</h1>}>
- *       <Posts />
- *     </Suspense>
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading posts...</h1>}>
+ *             <Posts />
+ *           </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 useSuspenseQuery<