Merge remote-tracking branch 'react-query/master' into alpha

# Conflicts:
#	src/react/utils.ts
#	src/reactjs/useBaseQuery.ts
#	src/reactjs/useMutation.ts

Author: TkDodo

.all-contributorsrc

@@ -203,6 +203,15 @@
         "code",
         "doc"
       ]
+    },
+    {
+      "login": "zrwsk",
+      "name": "Jakub Żurawski",
+      "avatar_url": "https://avatars.githubusercontent.com/u/9089600?v=4",
+      "profile": "https://github.com/zrwsk",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

CONTRIBUTING.md

@@ -2,11 +2,11 @@
 
 ## Questions
 
-If you have questions about implementation details, help or support, then please use our dedicated community forum at [Github Discussions](https://github.com/tannerlinsley/react-query/discussions) **PLEASE NOTE:** If you choose to instead open an issue for your question, your issue will be immediately closed and redirected to the forum.
+If you have questions about implementation details, help or support, then please use our dedicated community forum at [GitHub Discussions](https://github.com/tannerlinsley/react-query/discussions) **PLEASE NOTE:** If you choose to instead open an issue for your question, your issue will be immediately closed and redirected to the forum.
 
 ## Reporting Issues
 
-If you have found what you think is a bug, please [file an issue](https://github.com/tannerlinsley/react-query/issues/new). **PLEASE NOTE:** Issues that are identified as implementation questions or non-issues will be immediately closed and redirected to [Github Discussions](https://github.com/tannerlinsley/react-query/discussions)
+If you have found what you think is a bug, please [file an issue](https://github.com/tannerlinsley/react-query/issues/new). **PLEASE NOTE:** Issues that are identified as implementation questions or non-issues will be immediately closed and redirected to [GitHub Discussions](https://github.com/tannerlinsley/react-query/discussions)
 
 ## Suggesting new features
 
@@ -122,4 +122,4 @@ Use an appropriate commit type. Be especially careful with breaking changes.
 
 ## Releases
 
-For each new commit added to `master` with `git push` or by merging a pull request or merging from another branch, a github action is triggered and runs the `semantic-release` command to make a release if there are codebase changes since the last release that affect the package functionalities.
+For each new commit added to `master` with `git push` or by merging a pull request or merging from another branch, a GitHub action is triggered and runs the `semantic-release` command to make a release if there are codebase changes since the last release that affect the package functionalities.

README.md

@@ -82,6 +82,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="https://github.com/babycourageous"><img src="https://avatars.githubusercontent.com/u/14936212?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rene Dellefont</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=babycourageous" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/commits?author=babycourageous" title="Documentation">📖</a></td>
     <td align="center"><a href="https://github.com/jvuoti"><img src="https://avatars.githubusercontent.com/u/3702781?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Janne Vuoti</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=jvuoti" title="Code">💻</a></td>
     <td align="center"><a href="http://seaviewlab.com"><img src="https://avatars.githubusercontent.com/u/20332397?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Arnaud</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=arnaudbzn" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/commits?author=arnaudbzn" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/zrwsk"><img src="https://avatars.githubusercontent.com/u/9089600?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jakub Żurawski</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=zrwsk" title="Documentation">📖</a></td>
   </tr>
 </table>
 

docs/src/pages/guides/mutations.md

@@ -179,6 +179,28 @@ mutate(todo, {
 })
 ```
 
+### Consecutive mutations
+There is a slight difference in handling `onSuccess`, `onError` and `onSettled` callbacks when it comes to consecutive mutations. When passed to the `mutate` function, they will be fired up only _once_ and only if the component is still mounted.  This is due to the fact that mutation observer is removed and resubscribed every time when the `mutate` function is called. On the contrary, `useMutation` handlers execute for each `mutate` call.
+
+> Be aware that most likely, `mutationFn` passed to `useMutation` is ansynchronous. In that case, the order in which mutations are fulfilled may differ from the order of `mutate` function calls.
+
+```js
+useMutation(addTodo, {
+  onSuccess: (data, error, variables, context) => {
+    // Will be called 3 times
+  },
+})
+
+['Todo 1', 'Todo 2', 'Todo 3'].forEach((todo) => {
+  mutate(todo, {
+    onSuccess: (data, error, variables, context) => {
+      // Will execute only once, for the last mutation (Todo 3),
+      // regardles which mutation resolves first 
+    },
+  })
+})
+
+```
 ## Promises
 
 Use `mutateAsync` instead of `mutate` to get a promise which will resolve on success or throw on an error. This can for example be used to compose side effects.

docs/src/pages/guides/ssr.md

@@ -126,6 +126,7 @@ This guide is at-best, a high level overview of how SSR with React Query should
 - Dehydrate the client
 - Render your app with the client provider and also **using the dehydrated state. This is extremely important! You must render both server and client using the same dehydrated state to ensure hydration on the client produces the exact same markup as the server.**
 - Serialize and embed the dehydrated cache to be sent to the client with the HTML
+- Clear the React Query caches after the dehydrated state has been sent by calling [`queryClient.clear()`](../reference/QueryClient#queryclientclear)
 
 > SECURITY NOTE: Serializing data with `JSON.stringify` can put you at risk for XSS-vulnerabilities, [this blog post explains why and how to solve it](https://medium.com/node-security/the-most-common-xss-vulnerability-in-react-js-applications-2bdffbcc1fa0)
 
@@ -155,6 +156,8 @@ async function handleRequest (req, res) {
       </body>
     </html>
   `)
+
+  queryClient.clear()
 }
 ```
 
@@ -196,3 +199,11 @@ A query is considered stale depending on when it was `dataUpdatedAt`. A caveat h
 Because `staleTime` defaults to `0`, queries will be refetched in the background on page load by default. You might want to use a higher `staleTime` to avoid this double fetching, especially if you don't cache your markup.
 
 This refetching of stale queries is a perfect match when caching markup in a CDN! You can set the cache time of the page itself decently high to avoid having to re-render pages on the server, but configure the `staleTime` of the queries lower to make sure data is refetched in the background as soon as a user visits the page. Maybe you want to cache the pages for a week, but refetch the data automatically on page load if it's older than a day?
+
+### High memory consumption on server
+
+In case you are creating the `QueryClient` for every request, React Query creates the isolated cache for this client, which is preserved in memory for the `cacheTime` period (which defaults to 5 minutes). That may lead to high memory consumption on server in case of high number of requests during that period.
+
+To clear the cache after it is not needed and to lower memory consumption, you can add a call to [`queryClient.clear()`](../reference/QueryClient#queryclientclear) after the request is handled and dehydrated state has been sent to the client.
+
+Alternatively, you can set a smaller `cacheTime`.

docs/src/pages/reference/useQuery.md

@@ -177,11 +177,11 @@ const result = useQuery({
   - Optional
   - Defaults to `true`
   - If set to `false`, structural sharing between query results will be disabled.
-- `useErrorBoundary: undefined | boolean | (error: TError) => boolean`
+- `useErrorBoundary: undefined | boolean | (error: TError, query: Query) => 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 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`)
+  - 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`)
 - `meta: Record<string, unknown>`
   - Optional
   - If set, stores additional information on the query cache entry that can be used as needed. It will be accessible wherever the `query` is available, and is also part of the `QueryFunctionContext` provided to the `queryFn`.

src/core/types.ts

@@ -183,10 +183,15 @@ export interface QueryObserverOptions<
    * 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`).
+   * 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?: boolean | ((error: TError) => boolean)
+  useErrorBoundary?:
+    | boolean
+    | ((
+        error: TError,
+        query: Query<TQueryFnData, TError, TQueryData, TQueryKey>
+      ) => boolean)
   /**
    * This option can be used to transform or select a part of the data returned by the query function.
    */

src/reactjs/useBaseQuery.ts

@@ -127,7 +127,10 @@ export function useBaseQuery<
     result.isError &&
     !errorResetBoundary.isReset() &&
     !result.isFetching &&
-    shouldThrowError(defaultedOptions.useErrorBoundary, result.error)
+    shouldThrowError(defaultedOptions.useErrorBoundary, [
+      result.error,
+      observer.getCurrentQuery(),
+    ])
   ) {
     throw result.error
   }

src/reactjs/useMutation.ts

@@ -80,7 +80,9 @@ export function useMutation<
   const options = parseMutationArgs(arg1, arg2, arg3)
   const queryClient = useQueryClient()
 
-  const obsRef = React.useRef<MutationObserver<any, any, any, any>>()
+  const obsRef = React.useRef<
+    MutationObserver<TData, TError, TVariables, TContext>
+  >()
 
   if (!obsRef.current) {
     obsRef.current = new MutationObserver(queryClient, options)
@@ -114,10 +116,9 @@ export function useMutation<
 
   if (
     currentResult.error &&
-    shouldThrowError(
-      !!obsRef.current.options.useErrorBoundary,
-      currentResult.error
-    )
+    shouldThrowError(!!obsRef.current.options.useErrorBoundary, [
+      currentResult.error,
+    ])
   ) {
     throw currentResult.error
   }

src/reactjs/utils.ts

@@ -1,10 +1,10 @@
-export function shouldThrowError<TError>(
-  _useErrorBoundary: boolean | ((err: TError) => boolean),
-  error: TError
+export function shouldThrowError<T extends (...args: any[]) => boolean>(
+  _useErrorBoundary: boolean | T,
+  params: Parameters<T>
 ): boolean {
   // Allow useErrorBoundary function to override throwing behavior on a per-error basis
   if (typeof _useErrorBoundary === 'function') {
-    return _useErrorBoundary(error)
+    return _useErrorBoundary(...params)
   }
 
   return _useErrorBoundary