Merge branch 'master' into feature/useIsMutating-overloads

Author: TkDodo

docs/src/pages/guides/caching.md

@@ -21,11 +21,11 @@ Let's assume we are using the default `cacheTime` of **5 minutes** and the defau
   - It will then cache the data using `'todos'` and `fetchTodos` as the unique identifiers for that cache.
   - The hook will mark itself as stale after the configured `staleTime` (defaults to `0`, or immediately).
 - A second instance of `useQuery('todos', fetchTodos)` mounts elsewhere.
-  - Because this exact data exist in the cache from the first instance of this query, that data is immediately returned from the cache.
+  - Because this exact data exists in the cache from the first instance of this query, that data is immediately returned from the cache.
 - A background refetch is triggered for both queries (but only one request), since a new instance appeared on screen.
   - Both instances are updated with the new data if the fetch is successful
 - Both instances of the `useQuery('todos', fetchTodos)` query are unmounted and no longer in use.
-  - Since there are no more active instances to this query, a cache timeout is set using `cacheTime` to delete and garbage collect the query (defaults to **5 minutes**).
+  - Since there are no more active instances of this query, a cache timeout is set using `cacheTime` to delete and garbage collect the query (defaults to **5 minutes**).
 - Before the cache timeout has completed another instance of `useQuery('todos', fetchTodos)` mounts. The query immediately returns the available cached value while the `fetchTodos` function is being run in the background to populate the query with a fresh value.
 - The final instance of `useQuery('todos', fetchTodos)` unmounts.
 - No more instances of `useQuery('todos', fetchTodos)` appear within **5 minutes**.

docs/src/pages/guides/initial-query-data.md

@@ -64,7 +64,7 @@ By default, `initialData` is treated as totally fresh, as if it were just fetche
     })
   }
   ```
-  This option allows the staleTime to be used for it's original purpose, determining how fresh the data needs to be, while also allowing the data to be refetched on mount if the `initialData` is older than the `staleTime`. In the example above, our data needs to be fresh within 1 minute, and we can hint to the query when the initialData was last updated so the query can decide for itself whether the data needs to be refetched again or not.
+  This option allows the staleTime to be used for its original purpose, determining how fresh the data needs to be, while also allowing the data to be refetched on mount if the `initialData` is older than the `staleTime`. In the example above, our data needs to be fresh within 1 minute, and we can hint to the query when the initialData was last updated so the query can decide for itself whether the data needs to be refetched again or not.
 
 > If you would rather treat your data as **prefetched data**, we recommend that you use the `prefetchQuery` or `fetchQuery` APIs to populate the cache beforehand, thus letting you configure your `staleTime` independently from your initialData
 

docs/src/pages/guides/mutations.md

@@ -46,7 +46,7 @@ A mutation can only be in one of the following states at any given moment:
 
 Beyond those primary states, more information is available depending on the state of the mutation:
 
-- `error` - If the mutation is in an `isError` state, the error is available via the `error` property.
+- `error` - If the mutation is in an `error` state, the error is available via the `error` property.
 - `data` - If the mutation is in a `success` state, the data is available via the `data` property.
 
 In the example above, you also saw that you can pass variables to your mutations function by calling the `mutate` function with a **single variable or object**.

docs/src/pages/guides/testing.md

@@ -46,6 +46,28 @@ Note that we provide a custom wrapper that builds the `QueryClient` and `QueryCl
 
 It is possible to write this wrapper only once, but if so we need to ensure that the `QueryClient` gets cleared before every test, and that tests don't run in parallel otherwise one test will influence the results of others.
 
+## Turn off retries
+
+The library defaults to three retries with exponential backoff, which means that your tests are likely to timeout if you want to test an erroneous query. The easiest way to turn retries off is via the QueryClientProvider. Let's extend the above example:
+
+```
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      // ✅ turns retries off
+      retry: false,
+    },
+  },
+})
+const wrapper = ({ children }) => (
+  <QueryClientProvider client={queryClient}>
+    {children}
+  </QueryClientProvider>
+);
+```
+
+This will set the defaults for all queries in the component tree to "no retries". It is important to know that this will only work if your actual useQuery has no explicit retries set. If you have a query that wants 5 retries, this will still take precedence, because defaults are only taken as a fallback.
+
 ## Testing Network Calls
 
 The primary use for React Query is to cache network requests, so it's important that we can test our code is making the correct network requests in the first place.

docs/src/pages/plugins/createAsyncStoragePersistor.md

@@ -17,7 +17,7 @@ This utility comes packaged with `react-query` and is available under the `react
 - Pass it to the [`persistQueryClient`](../persistQueryClient) function
 
 ```ts
-import AsyncStorage from '@react-native-community/async-storage'
+import AsyncStorage from '@react-native-async-storage/async-storage'
 import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
 import { createAsyncStoragePersistor } from 'react-query/createAsyncStoragePersistor-experimental'
 
@@ -56,7 +56,7 @@ interface CreateAsyncStoragePersistorOptions {
   /** The storage client used for setting an retrieving items from cache */
   storage: AsyncStorage
   /** The key to use when storing the cache to localstorage */
-  asyncStorageKey?: string
+  key?: string
   /** To avoid localstorage spamming,
    * pass a time in ms to throttle saving the cache to disk */
   throttleTime?: number
@@ -73,7 +73,7 @@ The default options are:
 
 ```js
 {
-  asyncStorageKey = `REACT_QUERY_OFFLINE_CACHE`,
+  key = `REACT_QUERY_OFFLINE_CACHE`,
   throttleTime = 1000,
 }
 ```

docs/src/pages/reference/MutationCache.md

@@ -14,6 +14,9 @@ const mutationCache = new MutationCache({
   onError: error => {
     console.log(error)
   },
+  onSuccess: data => {
+    console.log(data)
+  }
 })
 ```
 
@@ -28,6 +31,14 @@ Its available methods are:
 - `onError?: (error: unknown, variables: unknown, context: unknown, mutation: Mutation) => void`
   - Optional
   - This function will be called if some mutation encounters an error.
+- `onSuccess?: (data: unknown, variables: unknown, context: unknown, mutation: Mutation) => void`
+  - Optional
+  - This function will be called if some mutation is successful.
+
+## Global callbacks
+
+The `onError` and `onSuccess` callbacks on the MutationCache can be used to handle these events on a global level. They are different to `defaultOptions` provided to the QueryClient because:
+- `defaultOptions` can be overridden by each Mutation - the global callbacks will **always** be called.
 
 ## `mutationCache.getAll`
 

docs/src/pages/reference/QueryCache.md

@@ -3,7 +3,7 @@ id: QueryCache
 title: QueryCache
 ---
 
-The `QueryCache` is the storage mechanism for React Query. It stores all of the data, meta information and state of queries it contains.
+The `QueryCache` is the storage mechanism for React Query. It stores all the data, meta information and state of queries it contains.
 
 **Normally, you will not interact with the QueryCache directly and instead use the `QueryClient` for a specific cache.**
 
@@ -14,6 +14,9 @@ const queryCache = new QueryCache({
   onError: error => {
     console.log(error)
   },
+  onSuccess: data => {
+    console.log(data)
+  }
 })
 
 const query = queryCache.find('posts')
@@ -31,6 +34,15 @@ Its available methods are:
 - `onError?: (error: unknown, query: Query) => void`
   - Optional
   - This function will be called if some query encounters an error.
+- `onSuccess?: (data: unknown, query: Query) => void`
+  - Optional
+  - This function will be called if some query is successful.
+
+## Global callbacks
+
+The `onError` and `onSuccess` callbacks on the QueryCache can be used to handle these events on a global level. They are different to `defaultOptions` provided to the QueryClient because:
+- `defaultOptions` can be overridden by each Query - the global callbacks will **always** be called.
+- `defaultOptions` callbacks will be called once for each Observer, while the global callbacks will only be called once per Query.
 
 ## `queryCache.find`
 

docs/src/pages/reference/hydration/dehydrate.md

@@ -3,7 +3,7 @@ id: hydration/dehydrate
 title: hydration/dehydrate
 ---
 
-`dehydrate` creates a frozen representation of a `cache` that can later be hydrated with `Hydrate`, `useHydrate`, or `hydrate`. This is useful for passing prefetched queries from server to client or persisting queries to localstorage or other persisten locations. It only includes currently successful queries by default.
+`dehydrate` creates a frozen representation of a `cache` that can later be hydrated with `Hydrate`, `useHydrate`, or `hydrate`. This is useful for passing prefetched queries from server to client or persisting queries to localstorage or other persistent locations. It only includes currently successful queries by default.
 
 ```js
 import { dehydrate } from 'react-query/hydration'

media/logo.sketch

@@ -156,6 +156,13 @@ export class Mutation<
       .then(() => this.executeMutation())
       .then(result => {
         data = result
+        // Notify cache callback
+        this.mutationCache.config.onSuccess?.(
+          data,
+          this.state.variables,
+          this.state.context,
+          this as Mutation<unknown, unknown, unknown, unknown>
+        )
       })
       .then(() =>
         this.options.onSuccess?.(
@@ -178,14 +185,12 @@ export class Mutation<
       })
       .catch(error => {
         // Notify cache callback
-        if (this.mutationCache.config.onError) {
-          this.mutationCache.config.onError(
-            error,
-            this.state.variables,
-            this.state.context,
-            this as Mutation<unknown, unknown, unknown, unknown>
-          )
-        }
+        this.mutationCache.config.onError?.(
+          error,
+          this.state.variables,
+          this.state.context,
+          this as Mutation<unknown, unknown, unknown, unknown>
+        )
 
         // Log error
         getLogger().error(error)