Added useErrorBoundary and throwOnError options

Author: tannerlinsley

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.28
+
+- Added the `useMutation.throwOnError` and corresponding `queryConfig.throwOnError` option to configure whether the `mutate` function rethrows errors encountered in the mutation function
+- Added the `useMutation.useErrorBoundary` and corresponding `queryConfig.useErrorBoundary` option to configure whether mutation errors should be thrown during the render function and propagated to the nearest error boundary. This option will default to the same value as `queryConfig.suspense` if not defined otherwise
+
 ## 0.3.27
 
 - Switched from the fast-async babel plugin to the babel-plugin-transform-async-to-promises. This should offer better compiler/browser support at the expense of 0.1kb

README.md

@@ -697,6 +697,8 @@ useQuery(queryKey, queryFn, { suspense: true })
 
 When using suspense mode, `isLoading` and `error` states will be replaced by usage of the `React.Suspense` component (including the use of the `fallback` prop and React error boundaries for catching errors). Please see the [Suspense Example](https://codesandbox.io/s/github/tannerlinsley/react-query/tree/master/examples/sandbox) 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!
+
 ### Fetch-on-render vs Fetch-as-you-render
 
 Out of the box, React Query in `suspense` mode works really well as a **Fetch-on-render** solution with no additional configuration. However, if you want to take it to the next level and implement a `Fetch-as-you-render` model, we recommend implementing [Prefetching](#prefetching) on routing and/or user interactions events to initialize queries before they are needed.
@@ -1371,6 +1373,8 @@ const {
 const [mutate, { data, isLoading, error }] = useMutation(mutationFn, {
   refetchQueries,
   refetchQueriesOnFailure,
+  useErrorBoundary,
+  throwOnError,
 })
 
 const promise = mutate(variables, { updateQuery, waitForRefetchQueries })
@@ -1388,6 +1392,12 @@ const promise = mutate(variables, { updateQuery, waitForRefetchQueries })
 - `refetchQueriesOnFailure: Boolean`
   - Defaults to `false`
   - Set this to `true` if you want `refetchQueries` to be refetched regardless of the mutation succeeding.
+- `useErrorBoundary`
+  - Defaults to the global query config's `useErrorBoundary` value, which is `false`
+  - Set this to true if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary
+- `throwOnError`
+  - Defaults to `true` (but will be `false` in the next major release)
+  - Set this to `true` if failed mutations should re-throw errors from the mutation function to the `mutate` function.
 - `variables: any`
   - Optional
   - The variables object to pass to the `mutationFn`.
@@ -1564,6 +1574,8 @@ const queryConfig = {
   refetchAllOnWindowFocus: true,
   refetchInterval: false,
   suspense: false,
+  useErrorBoundary: undefined, // Defaults to the value of `suspense` if not defined otherwise
+  throwOnError: true,
 }
 
 function App() {
@@ -1579,4 +1591,4 @@ function App() {
 
 - `config: Object`
   - Must be **stable** or **memoized**. Do not create an inline object!
-  - For a description of all config options, please see the [`useQuery` hook](#usequery).
+  - For a description of all config options, please see their usage in both the [`useQuery` hook](#usequery) and the [`useMutation` hook](#usemutation).

src/index.js

@@ -16,6 +16,8 @@ let defaultConfig = {
   refetchInterval: false,
   suspense: false,
   queryKeySerializerFn: defaultQueryKeySerializerFn,
+  throwOnError: true,
+  useErrorBoundary: undefined, // this will default to the suspense value
 }
 
 const onWindowFocus = () => {
@@ -64,13 +66,19 @@ setFocusHandler(handleFocus => {
 export function ReactQueryConfigProvider({ config, children }) {
   let configContextValue = React.useContext(configContext)
 
-  const newConfig = React.useMemo(
-    () => ({
+  const newConfig = React.useMemo(() => {
+    const newConfig = {
       ...(configContextValue || defaultConfig),
       ...config,
-    }),
-    [config, configContextValue]
-  )
+    }
+
+    // Default useErrorBoundary to the suspense value
+    if (typeof newConfig.useErrorBoundary === 'undefined') {
+      newConfig.useErrorBoundary = newConfig.suspense
+    }
+
+    return newConfig
+  }, [config, configContextValue])
 
   if (!configContextValue) {
     defaultConfig = newConfig
@@ -612,14 +620,19 @@ export async function refetchQuery(queryKey, config = {}) {
 
 export function useMutation(
   mutationFn,
-  { refetchQueries, refetchQueriesOnFailure } = {}
+  { refetchQueries, refetchQueriesOnFailure, ...config } = {}
 ) {
   const [data, setData] = React.useState(null)
   const [error, setError] = React.useState(null)
   const [isLoading, setIsLoading] = React.useState(false)
   const mutationFnRef = React.useRef()
   mutationFnRef.current = mutationFn
 
+  const { throwOnError, useErrorBoundary } = {
+    ...useConfigContext(),
+    ...config,
+  }
+
   const mutate = React.useCallback(
     async (variables, { updateQuery, waitForRefetchQueries = false } = {}) => {
       setIsLoading(true)
@@ -662,14 +675,22 @@ export function useMutation(
         }
 
         setIsLoading(false)
-        throw error
+        if (throwOnError) {
+          throw error
+        }
       }
     },
-    [refetchQueriesOnFailure, refetchQueries]
+    [refetchQueries, refetchQueriesOnFailure, throwOnError]
   )
 
   const reset = React.useCallback(() => setData(null), [])
 
+  React.useEffect(() => {
+    if (useErrorBoundary && error) {
+      throw error
+    }
+  }, [error, useErrorBoundary])
+
   return [mutate, { data, isLoading, error, reset }]
 }