refactor: rename useErrorBoundar option to throwError (#4697)

* ♻️ refactor(query-core): rename useErrorBoundary query option to throwError

* ♻️ refactor(react-query): rename useErrorBoundary query option to throwError

* ♻️ refactor(react-query): rename useErrorBoundary mutation option to throwError

* ♻️ refactor(solid-query): rename useErrorBoundary mutation option to throwError

* ♻️ refactor(solid-query): rename useErrorBoundary query option to throwError

* ✅ test(react-query): rename useErrorBoundary query option to throwError

* ✅ test(react-query): rename useErrorBoundary mutation option to throwError

* ✅ test(react-query-devtools): rename useErrorBoundary query option to throwError

* ✅ test(solid-query): rename useErrorBoundary query option to throwError

* ✅ test(solid-query): rename useErrorBoundary mutation option to throwError

* 📝 docs(react-query): rename useErrorBoundary query option to throwError

* 📝 docs(react-query): rename useErrorBoundary mutation option to throwError

* ♻️ refactor(solid-query): rename useErrorBoundary util option to throwError

* ♻️ refactor(react-query): rename useErrorBoundary util option to throwError

* 📝 docs(react-query): add throwError to migration guide

* 🎨 style: format ThrowError type

* ♻️ refactor(query-core): rename throwError query option to throwErrors

* ♻️ refactor(react-query): rename throwError query option to throwErrors

* ♻️ refactor(react-query): rename throwError mutation option to throwErrors

* ✅ test(react-query): rename throwError mutation option to throwErrors

* ✅ test(react-query): rename throwError query option to throwErrors

* ✅ test(react-query-devtools): rename throwError query option to throwErrors

* 📝 docs(react-query): rename throwError mutation option to throwErrors

* ✅ test(react-query-devtools): rename throwError query option to throwErrors

* ✅ test(solid-query): rename throwError mutation option to throwErrors

* ✅ test(solid-query): rename throwError query option to throwErrors

* 📝 docs(react-query): rename throwError to throwErrors in migration guide

* 📝 docs(react-query): rename throwError to throwErrors in reference

* ✅ test(react-query): update suspense test desc

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: moshyfawn

docs/react/guides/migrating-to-react-query-5.md

@@ -26,3 +26,7 @@ if you still need to remove a query, you can use `queryClient.removeQueries({que
 ### The minimum required TypeScript version is now 4.7
 
 Mainly because an important fix was shipped around type inference. Please see this [TypeScript issue](https://github.com/microsoft/TypeScript/issues/43371) for more information.
+
+### The `useErrorBoundary` prop has been renamed to `throwErrors`
+
+To make the `useErrorBoundary` prop more framework-agnostic and avoid confusion with the established React function prefix "`use`" for hooks and the "ErrorBoundary" component name, it has been renamed to `throwErrors` to more accurately reflect its functionality.

docs/react/guides/suspense.md

@@ -41,11 +41,11 @@ useQuery({ queryKey, queryFn, 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.
 
-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 `useErrorBoundary` option to `false`. If you wish that errors are not thrown at all, you can set the `throwOnError` option to `false` as well!
+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 `throwErrors` option to `false`. If you wish that errors are not thrown at all, you can set the `throwOnError` option to `false` as well!
 
 ## Resetting Error Boundaries
 
-Whether you are using **suspense** or **useErrorBoundaries** in your queries, you will need a way to let queries know that you want to try again when re-rendering after some error occurred.
+Whether you are using **suspense** or **throwErrors** in your queries, you will need a way to let queries know that you want to try again when re-rendering after some error occurred.
 
 Query errors can be reset with the `QueryErrorResetBoundary` component or with the `useQueryErrorResetBoundary` hook.
 

docs/react/reference/QueryClient.md

@@ -95,7 +95,7 @@ try {
 
 **Options**
 
-The options for `fetchQuery` are exactly the same as those of [`useQuery`](../reference/useQuery), except the following: `enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, notifyOnChangeProps, onSuccess, onError, onSettled, useErrorBoundary, select, suspense, keepPreviousData, placeholderData`; which are strictly for useQuery and useInfiniteQuery. You can check the [source code](https://github.com/tannerlinsley/react-query/blob/361935a12cec6f36d0bd6ba12e84136c405047c5/src/core/types.ts#L83) for more clarity.
+The options for `fetchQuery` are exactly the same as those of [`useQuery`](../reference/useQuery), except the following: `enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, notifyOnChangeProps, onSuccess, onError, onSettled, throwErrors, select, suspense, keepPreviousData, placeholderData`; which are strictly for useQuery and useInfiniteQuery. You can check the [source code](https://github.com/tannerlinsley/react-query/blob/361935a12cec6f36d0bd6ba12e84136c405047c5/src/core/types.ts#L83) for more clarity.
 
 **Returns**
 

docs/react/reference/QueryErrorResetBoundary.md

@@ -3,7 +3,7 @@ id: QueryErrorResetBoundary
 title: QueryErrorResetBoundary
 ---
 
-When using **suspense** or **useErrorBoundaries** in your queries, you need a way to let queries know that you want to try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can reset any query errors within the boundaries of the component.
+When using **suspense** or **throwErrors** in your queries, you need a way to let queries know that you want to try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can reset any query errors within the boundaries of the component.
 
 ```tsx
 import { QueryErrorResetBoundary } from '@tanstack/react-query'

docs/react/reference/useMutation.md

@@ -29,7 +29,7 @@ const {
   onSuccess,
   retry,
   retryDelay,
-  useErrorBoundary,
+  throwErrors,
   meta
 })
 
@@ -82,8 +82,8 @@ mutate(variables, {
   - This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds.
   - A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff.
   - A function like `attempt => attempt * 1000` applies linear backoff.
-- `useErrorBoundary: undefined | boolean | (error: TError) => boolean`
-  - Defaults to the global query config's `useErrorBoundary` value, which is `undefined`
+- `throwErrors: undefined | boolean | (error: TError) => boolean`
+  - Defaults to the global query config's `throwErrors` value, which is `undefined`
   - Set this to `true` if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary
   - Set this to `false` to disable the behavior of throwing errors to the error boundary.
   - If set to a function, it will be passed the error and should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`)

docs/react/reference/useQuery.md

@@ -55,7 +55,7 @@ const {
   staleTime,
   structuralSharing,
   suspense,
-  useErrorBoundary,
+  throwErrors,
 })
 ```
 
@@ -178,8 +178,8 @@ const {
   - Defaults to `true`
   - If set to `false`, structural sharing between query results will be disabled.
   - If set to a function, the old and new data values will be passed through this function, which should combine them into resolved data for the query. This way, you can retain references from the old data to improve performance even when that data contains non-serializable values.
-- `useErrorBoundary: undefined | boolean | (error: TError, query: Query) => boolean`
-  - Defaults to the global query config's `useErrorBoundary` value, which is `undefined`
+- `throwErrors: undefined | boolean | (error: TError, query: Query) => boolean`
+  - Defaults to the global query config's `throwErrors` value, which is `undefined`
   - Set this to `true` if you want errors to be thrown in the render phase and propagate to the nearest error boundary
   - Set this to `false` to disable `suspense`'s default behavior of throwing errors to the error boundary.
   - If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`)

packages/query-core/src/queryClient.ts

@@ -749,8 +749,8 @@ export class QueryClient {
       defaultedOptions.refetchOnReconnect =
         defaultedOptions.networkMode !== 'always'
     }
-    if (typeof defaultedOptions.useErrorBoundary === 'undefined') {
-      defaultedOptions.useErrorBoundary = !!defaultedOptions.suspense
+    if (typeof defaultedOptions.throwErrors === 'undefined') {
+      defaultedOptions.throwErrors = !!defaultedOptions.suspense
     }
 
     return defaultedOptions as DefaultedQueryObserverOptions<

packages/query-core/src/queryObserver.ts

@@ -618,7 +618,7 @@ export class QueryObserver<
 
       const includedProps = new Set(notifyOnChangeProps ?? this.trackedProps)
 
-      if (this.options.useErrorBoundary) {
+      if (this.options.throwErrors) {
         includedProps.add('error')
       }
 

packages/query-core/src/types.ts

@@ -104,7 +104,7 @@ export interface QueryOptions<
   meta?: QueryMeta
 }
 
-export type UseErrorBoundary<
+export type ThrowErrors<
   TQueryFnData,
   TError,
   TQueryData,
@@ -221,12 +221,7 @@ export interface QueryObserverOptions<
    * If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`).
    * Defaults to `false`.
    */
-  useErrorBoundary?: UseErrorBoundary<
-    TQueryFnData,
-    TError,
-    TQueryData,
-    TQueryKey
-  >
+  throwErrors?: ThrowErrors<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
    * This option can be used to transform or select a part of the data returned by the query function.
    */
@@ -260,7 +255,7 @@ export type DefaultedQueryObserverOptions<
   TQueryKey extends QueryKey = QueryKey,
 > = WithRequired<
   QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
-  'useErrorBoundary' | 'refetchOnReconnect'
+  'throwErrors' | 'refetchOnReconnect'
 >
 
 export interface InfiniteQueryObserverOptions<
@@ -291,7 +286,7 @@ export type DefaultedInfiniteQueryObserverOptions<
     TQueryData,
     TQueryKey
   >,
-  'useErrorBoundary' | 'refetchOnReconnect'
+  'throwErrors' | 'refetchOnReconnect'
 >
 
 export interface FetchQueryOptions<
@@ -587,7 +582,7 @@ export interface MutationObserverOptions<
   TVariables = void,
   TContext = unknown,
 > extends MutationOptions<TData, TError, TVariables, TContext> {
-  useErrorBoundary?: boolean | ((error: TError) => boolean)
+  throwErrors?: boolean | ((error: TError) => boolean)
 }
 
 export interface MutateOptions<

packages/react-query-devtools/src/__tests__/devtools.test.tsx

@@ -704,7 +704,7 @@ describe('ReactQueryDevtools', () => {
 
       function Page() {
         const { data = 'default' } = useQuery(['check'], async () => 'test', {
-          useErrorBoundary: true,
+          throwErrors: true,
         })
 
         return (
@@ -739,7 +739,7 @@ describe('ReactQueryDevtools', () => {
 
       function Page() {
         const { data = 'default' } = useQuery(['check'], async () => 'test', {
-          useErrorBoundary: true,
+          throwErrors: true,
           context,
         })