Merge branch 'tannerlinsley:master' into master

Author: Andrey-Bazhanov

docs/src/components/markdown.module.css

@@ -61,19 +61,19 @@
   @apply text-base;
 }
 
-.markdown > p > a,
-.markdown > ul > li > a,
-.markdown > ol > li > a,
-.markdown > blockquote > p > a,
-.markdown > table > tbody > tr > td > a {
+.markdown p > a,
+.markdown ul > li > a,
+.markdown ol > li > a,
+.markdown blockquote > p > a,
+.markdown table > tbody > tr > td > a {
   @apply text-blue-600 font-semibold transition-colors duration-150 ease-out;
 }
 
-.markdown > p > a:hover,
-.markdown > ul > li > a:hover,
-.markdown > ol > li > a:hover,
-.markdown > blockquote > p > a:hover,
-.markdown > table > tbody > tr > td > a:hover {
+.markdown p > a:hover,
+.markdown ul > li > a:hover,
+.markdown ol > li > a:hover,
+.markdown blockquote > p > a:hover,
+.markdown table > tbody > tr > td > a:hover {
   @apply text-blue-800 transition-colors duration-150 ease-out;
 }
 

docs/src/images/emblem-light.svg

@@ -45,3 +45,7 @@ React Query maintainer [TkDodo](https://twitter.com/tkdodo) has a series of blog
 ## [#10: React Query as a State Manager](https://tkdodo.eu/blog/react-query-as-a-state-manager)
 
 > React Query doesn't fetch any data for you - it's a data synchronization tool that excels when used for server state. This article has everything you need to know to make React Query your single source of truth state manager for your async state. You'll learn how to let React Query do it's magic and why customizing `staleTime` might be all you need. [Read more...](https://tkdodo.eu/blog/react-query-as-a-state-manager)
+
+## [#11: React Query Error Handling](https://tkdodo.eu/blog/react-query-error-handling)
+
+> Handling errors is an integral part of working with asynchronous data, especially data fetching. We have to face it: Not all requests will be successful, and not all Promises will be fulfilled. This blog post describes various ways of coping with errors in React Query, such as the error property, using Error Boundaries or onError callbacks, so that you can prepare your application for the cases when "Something went wrong". [Read more...](https://tkdodo.eu/blog/react-query-error-handling)

docs/src/images/logo.svg

@@ -121,7 +121,7 @@ await waitFor(() => {
   return result.current.isSuccess;
 });
 
-expect(result.current).toEqual({answer: 42});
+expect(result.current.data).toEqual({answer: 42});
 ```
 
 Here we are making use of `waitFor` and waiting until our the query status indicates that the request has succeeded. This way we know that our hook has finished and should have the correct data.

docs/src/images/logos/walmart.svg

@@ -66,9 +66,11 @@ 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`
-  - 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
+- `useErrorBoundary: undefined | boolean | (error: TError) => boolean`
+  - Defaults to the global query config's `useErrorBoundary` 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 behaviour 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`)
 
 **Returns**
 

docs/src/pages/community/tkdodos-blog.md

@@ -170,9 +170,11 @@ const result = useQuery({
   - Optional
   - Defaults to `true`
   - If set to `false`, structural sharing between query results will be disabled.
-- `useErrorBoundary: boolean`
-  - Defaults to the global query config's `useErrorBoundary` value, which is false
-  - Set this to true if you want errors to be thrown in the render phase and propagated to the nearest error boundary
+- `useErrorBoundary: undefined | boolean | (error: TError) => boolean`
+  - Defaults to the global query config's `useErrorBoundary` 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 behaviour 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`)
 
 **Returns**
 

docs/src/pages/guides/testing.md

@@ -4,6 +4,7 @@ import type { QueryClient } from './queryClient'
 import { Subscribable } from './subscribable'
 import type {
   MutateOptions,
+  MutationObserverBaseResult,
   MutationObserverResult,
   MutationObserverOptions,
 } from './types'
@@ -129,7 +130,12 @@ export class MutationObserver<
       ? this.currentMutation.state
       : getDefaultState<TData, TError, TVariables, TContext>()
 
-    this.currentResult = {
+    const result: MutationObserverBaseResult<
+      TData,
+      TError,
+      TVariables,
+      TContext
+    > = {
       ...state,
       isLoading: state.status === 'loading',
       isSuccess: state.status === 'success',
@@ -138,6 +144,13 @@ export class MutationObserver<
       mutate: this.mutate,
       reset: this.reset,
     }
+
+    this.currentResult = result as MutationObserverResult<
+      TData,
+      TError,
+      TVariables,
+      TContext
+    >
   }
 
   private notify(options: NotifyOptions) {

docs/src/pages/reference/useMutation.md

@@ -163,9 +163,12 @@ export interface QueryObserverOptions<
   onSettled?: (data: TData | undefined, error: TError | null) => void
   /**
    * Whether errors should be thrown instead of setting the `error` property.
+   * If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary.
+   * If set to `false` and `suspense` is `false`, errors are returned as state.
+   * 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`).
    * Defaults to `false`.
    */
-  useErrorBoundary?: boolean
+  useErrorBoundary?: boolean | ((error: TError) => boolean)
   /**
    * This option can be used to transform or select a part of the data returned by the query function.
    */
@@ -527,7 +530,7 @@ export interface MutationObserverOptions<
   TVariables = void,
   TContext = unknown
 > extends MutationOptions<TData, TError, TVariables, TContext> {
-  useErrorBoundary?: boolean
+  useErrorBoundary?: boolean | ((error: TError) => boolean)
 }
 
 export interface MutateOptions<
@@ -564,7 +567,7 @@ export type MutateFunction<
   options?: MutateOptions<TData, TError, TVariables, TContext>
 ) => Promise<TData>
 
-export interface MutationObserverResult<
+export interface MutationObserverBaseResult<
   TData = unknown,
   TError = unknown,
   TVariables = void,
@@ -578,6 +581,77 @@ export interface MutationObserverResult<
   reset: () => void
 }
 
+export interface MutationObserverIdleResult<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown
+> extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
+  data: undefined
+  error: null
+  isError: false
+  isIdle: true
+  isLoading: false
+  isSuccess: false
+  status: 'idle'
+}
+
+export interface MutationObserverLoadingResult<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown
+> extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
+  data: undefined
+  error: null
+  isError: false
+  isIdle: false
+  isLoading: true
+  isSuccess: false
+  status: 'loading'
+}
+
+export interface MutationObserverErrorResult<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown
+> extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
+  data: undefined
+  error: TError
+  isError: true
+  isIdle: false
+  isLoading: false
+  isSuccess: false
+  status: 'error'
+}
+
+export interface MutationObserverSuccessResult<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown
+> extends MutationObserverBaseResult<TData, TError, TVariables, TContext> {
+  data: TData
+  error: null
+  isError: false
+  isIdle: false
+  isLoading: false
+  isSuccess: true
+  status: 'success'
+}
+
+export type MutationObserverResult<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown
+> =
+  | MutationObserverIdleResult<TData, TError, TVariables, TContext>
+  | MutationObserverLoadingResult<TData, TError, TVariables, TContext>
+  | MutationObserverErrorResult<TData, TError, TVariables, TContext>
+  | MutationObserverSuccessResult<TData, TError, TVariables, TContext>
+
 export interface DefaultOptions<TError = unknown> {
   queries?: QueryObserverOptions<unknown, TError>
   mutations?: MutationObserverOptions<unknown, TError, unknown, unknown>