feat(react-query): useSuspenseQueries (#5836)

* docs: suspense

* feat: remove suspense boolean from useQuery and useInfiniteQuery

* feat: useSuspenseQueries

* docs: useSuspenseQueries

* test: fix suspense in tests

* docs: offline caching is not experimental

* tests: there is no throwOnError on useSuspenseQueries

* chore: exports

* chore: try to stabilize a flaky test

Author: TkDodo

docs/react/comparison.md

@@ -400,7 +400,7 @@ The `loading` status has been renamed to `pending`, and similarly the derived `i
 
 For mutations as well the `status` has been changed from `loading` to `pending` and the `isLoading` flag has been changed to `isPending`.
 
-Lastly the a new derived `isLoading` flag has been added to the queries that is implemented as `isPending && isFetching`. This means that `isLoading` and `isInitialLoading` have the same thing, but `isInitialLoading` is deprecated now and will be removed in the next major version.
+Lastly, a new derived `isLoading` flag has been added to the queries that is implemented as `isPending && isFetching`. This means that `isLoading` and `isInitialLoading` have the same thing, but `isInitialLoading` is deprecated now and will be removed in the next major version.
 
 To understand the reasoning behing this change checkout the [v5 roadmap discussion](https://github.com/TanStack/query/discussions/4252).
 
@@ -462,4 +462,20 @@ See the [TypeScript docs](../typescript#typing-query-options) for more details.
 
 See the [useQueries docs](../reference/useQueries#combine) for more details.
 
+### new hooks for suspense
+
+With v5, suspense for data fetching finally becomes "stable". We've added dedicated `useSuspenseQuery`, `useSuspenseInfiniteQuery` and `useSuspenseQueries` hooks. With these hooks, `data` will never be potentially `undefined` on type level:
+
+```js
+const [post] = useSuspenseQuery({
+    // ^? const post: Post
+  queryKey: ['post', postId],
+  queryFn: () => fetchPost(postId),
+})
+```
+
+The experimental `suspense: boolean` flag on the query hooks has been removed.
+
+You can read more about them in the [suspense docs](../guides/suspense).
+
 [//]: # 'NewFeatures'

docs/react/guides/migrating-to-v5.md

@@ -24,7 +24,7 @@ function App () {
 [//]: # 'Example'
 [//]: # 'Info'
 
-> When using React Query in suspense mode, this pattern of parallelism does not work, since the first query would throw a promise internally and would suspend the component before the other queries run. To get around this, you'll either need to use the `useQueries` hook (which is suggested) or orchestrate your own parallelism with separate components for each `useQuery` instance (which is lame).
+> When using React Query in suspense mode, this pattern of parallelism does not work, since the first query would throw a promise internally and would suspend the component before the other queries run. To get around this, you'll either need to use the `useSuspenseQueries` hook (which is suggested) or orchestrate your own parallelism with separate components for each `useSuspenseQuery` instance.
 
 [//]: # 'Info'
 

docs/react/guides/parallel-queries.md

@@ -3,43 +3,27 @@ id: suspense
 title: Suspense
 ---
 
-React Query can also be used with React's Suspense for Data Fetching API's. To enable this mode, you can set either the global or query level config's `suspense` option to `true`.
+React Query can also be used with React's Suspense for Data Fetching API's. For this, we have dedicated hooks:
 
-Global configuration:
+- [useSuspenseQuery](../reference/useSuspenseQuery)
+- [useSuspenseInfiniteQuery](../reference/useSuspenseInfiniteQuery)
+- [useSuspenseQueries](../reference/useSuspenseQueries)
 
-```tsx
-// Configure for all queries
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      suspense: true,
-    },
-  },
-})
+When using suspense mode, `status` states and `error` objects are not needed and are then replaced by usage of the `React.Suspense` component (including the use of the `fallback` prop and React error boundaries for catching errors). Please read the [Resetting Error Boundaries](#resetting-error-boundaries) and look at the [Suspense Example](https://codesandbox.io/s/github/tannerlinsley/react-query/tree/main/examples/react/suspense) for more information on how to set up suspense mode.
 
-function Root() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <App />
-    </QueryClientProvider>
-  )
-}
-```
+In addition to queries behaving differently in suspense mode, mutations also behave a bit differently. By default, instead of supplying the `error` variable when a mutation fails, it will be thrown during the next render of the component it's used in and propagate to the nearest error boundary, similar to query errors. If you wish to disable this, you can set the `throwOnError` option to `false`. If you wish that errors are not thrown at all, you can set the `throwOnError` option to `false` as well!
 
-Query configuration:
+Enabling suspense mode for a query:
 
 ```tsx
-import { useQuery } from '@tanstack/react-query'
+import { useSuspenseQuery } from '@tanstack/react-query'
 
-// Enable for an individual query
-useQuery({ queryKey, queryFn, suspense: true })
+const { data } = useSuspenseQuery({ queryKey, queryFn })
 ```
 
-When using suspense mode, `status` states and `error` objects are not needed and are then replaced by usage of the `React.Suspense` component (including the use of the `fallback` prop and React error boundaries for catching errors). Please read the [Resetting Error Boundaries](#resetting-error-boundaries) and look at the [Suspense Example](https://codesandbox.io/s/github/tannerlinsley/react-query/tree/main/examples/react/suspense) for more information on how to set up suspense mode.
+This works nicely in TypeScript, because `data` is guaranteed to be defined (as errors and loading states are handled by Suspense- and ErrorBoundaries).
 
-In addition to queries behaving differently in suspense mode, mutations also behave a bit differently. By default, instead of supplying the `error` variable when a mutation fails, it will be thrown during the next render of the component it's used in and propagate to the nearest error boundary, similar to query errors. If you wish to disable this, you can set the `throwOnError` option to `false`. If you wish that errors are not thrown at all, you can set the `throwOnError` option to `false` as well!
+On the flip side, you therefore can't conditionally enable / disable the Query. `placeholderData` also doesn't exist for this Query. To prevent the UI from being replaced by a fallback during an update, wrap your updates that change the QueryKey into [startTransition](https://react.dev/reference/react/Suspense#preventing-unwanted-fallbacks).
 
 ## Resetting Error Boundaries
 
@@ -96,20 +80,6 @@ const App: React.FC = () => {
 }
 ```
 
-## useSuspenseQuery
-
-You can also use the dedicated `useSuspenseQuery` hook to enable suspense mode for a query:
-
-```tsx
-import { useSuspenseQuery } from '@tanstack/react-query'
-
-const { data } = useSuspenseQuery({ queryKey, queryFn })
-```
-
-This has the same effect as setting the `suspense` option to `true` in the query config, but it works better in TypeScript, because `data` is guaranteed to be defined (as errors and loading states are handled by Suspense- and ErrorBoundaries).
-
-On the flip side, you therefore can't conditionally enable / disable the Query. `placeholderData` also doesn't exist for this Query. To prevent the UI from being replaced by a fallback during an update, wrap your updates that change the QueryKey into [startTransition](https://react.dev/reference/react/Suspense#preventing-unwanted-fallbacks).
-
 ## Fetch-on-render vs Render-as-you-fetch
 
 Out of the box, React Query in `suspense` mode works really well as a **Fetch-on-render** solution with no additional configuration. This means that when your components attempt to mount, they will trigger query fetching and suspend, but only once you have imported them and mounted them. If you want to take it to the next level and implement a **Render-as-you-fetch** model, we recommend implementing [Prefetching](../guides/prefetching) on routing callbacks and/or user interactions events to start loading queries before they are mounted and hopefully even before you start importing or mounting their parent components.

docs/react/guides/suspense.md

@@ -17,7 +17,8 @@ The same as for [useInfiniteQuery](../reference/useInfiniteQuery), except for:
 
 **Returns**
 
-Same object as [useInfiniteQuery](../reference/useInfiniteQuery), except for:
+Same object as [useInfiniteQuery](../reference/useInfiniteQuery), except that:
+- `data` is guaranteed to be defined
 - `isPlaceholderData` is missing
 - `status` is always `success`
   - the derived flags are set accordingly.

docs/react/reference/useSuspenseInfiniteQuery.md

@@ -0,0 +1,24 @@
+---
+id: useSuspenseQueries
+title: useSuspenseQueries
+---
+
+```tsx
+const result = useSuspenseQueries(options)
+```
+
+**Options**
+
+The same as for [useQueries](../reference/useQueries), except that each `query` can't have:
+- `suspense`
+- `throwOnError`
+- `enabled`
+- `placeholderData`
+
+**Returns**
+
+Same structure as [useQueries](../reference/useQueries), except that for each `query`:
+- `data` is guaranteed to be defined
+- `isPlaceholderData` is missing
+- `status` is always `success`
+  - the derived flags are set accordingly.

docs/react/reference/useSuspenseQueries.md

@@ -17,7 +17,8 @@ The same as for [useQuery](../reference/useQuery), except for:
 
 **Returns**
 
-Same object as [useQuery](../reference/useQuery), except for:
+Same object as [useQuery](../reference/useQuery), except that:
+- `data` is guaranteed to be defined
 - `isPlaceholderData` is missing
 - `status` is always `success`
   - the derived flags are set accordingly.

docs/react/reference/useSuspenseQuery.md

@@ -3,7 +3,14 @@ import { ErrorBoundary } from 'react-error-boundary'
 import * as React from 'react'
 
 import { vi } from 'vitest'
-import { QueryCache, QueryErrorResetBoundary, useQueries, useQuery } from '..'
+import {
+  QueryCache,
+  QueryErrorResetBoundary,
+  useQueries,
+  useQuery,
+  useSuspenseQueries,
+  useSuspenseQuery,
+} from '..'
 import { createQueryClient, queryKey, renderWithClient, sleep } from './utils'
 
 // TODO: This should be removed with the types for react-error-boundary get updated.
@@ -522,7 +529,7 @@ describe('QueryErrorResetBoundary', () => {
       let renders = 0
 
       function Page() {
-        const { data } = useQuery({
+        const { data } = useSuspenseQuery({
           queryKey: key,
           queryFn: async () => {
             fetchCount++
@@ -534,7 +541,6 @@ describe('QueryErrorResetBoundary', () => {
             }
           },
           retry: false,
-          suspense: true,
         })
         renders++
         return <div>{data}</div>
@@ -735,7 +741,7 @@ describe('QueryErrorResetBoundary', () => {
       let succeed = false
 
       function Page() {
-        const [{ data }] = useQueries({
+        const [{ data }] = useSuspenseQueries({
           queries: [
             {
               queryKey: key,
@@ -748,9 +754,7 @@ describe('QueryErrorResetBoundary', () => {
                 }
               },
               retry: false,
-              throwOnError: true,
               retryOnMount: true,
-              suspense: true,
             },
           ],
         })