Merge branch 'master' into feature/2682-error-query-doesn't-fire-again-when-keys-change

Author: TkDodo

docs/src/manifests/manifest.json

@@ -435,26 +435,11 @@
           "editUrl": "/reference/setLogger.md"
         },
         {
-          "title": "hydration/Hydrate",
-          "path": "/reference/hydration/HydrateComp",
-          "editUrl": "/reference/hydration/HydrateComp.md"
-        },
-        {
-          "title": "hydration/useHydrate",
-          "path": "/reference/hydration/useHydrate",
-          "editUrl": "/reference/hydration/useHydrate.md"
-        },
-        {
-          "title": "hydration/hydrate",
-          "path": "/reference/hydration/hydrate",
-          "editUrl": "/reference/hydration/hydrate.md"
-        },
-        {
-          "title": "hydration/dehydrate",
-          "path": "/reference/hydration/dehydrate",
-          "editUrl": "/reference/hydration/dehydrate.md"
+          "title": "hydration",
+          "path": "/reference/hydration",
+          "editUrl": "/reference/hydration.md"
         }
       ]
     }
   ]
-}
+}

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

@@ -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/pages/guides/ssr.md

@@ -55,8 +55,7 @@ To support caching queries on the server and set up hydration:
 
 ```js
 // _app.jsx
-import { QueryClient, QueryClientProvider } from 'react-query'
-import { Hydrate } from 'react-query/hydration'
+import { Hydrate, QueryClient, QueryClientProvider } from 'react-query'
 
 export default function MyApp({ Component, pageProps }) {
   const [queryClient] = React.useState(() => new QueryClient())
@@ -79,8 +78,7 @@ Now you are ready to prefetch some data in your pages with either [`getStaticPro
 
 ```js
 // pages/posts.jsx
-import { QueryClient, useQuery } from 'react-query'
-import { dehydrate } from 'react-query/hydration'
+import { dehydrate, QueryClient, useQuery } from 'react-query';
 
 export async function getStaticProps() {
   const queryClient = new QueryClient()
@@ -126,8 +124,7 @@ This guide is at-best, a high level overview of how SSR with React Query should
 > 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)
 
 ```js
-import { QueryClient, QueryClientProvider } from 'react-query'
-import { dehydrate, Hydrate } from 'react-query/hydration'
+import { dehydrate, Hydrate, QueryClient, QueryClientProvider } from 'react-query';
 
 function handleRequest (req, res) {
   const queryClient = new QueryClient()
@@ -162,8 +159,7 @@ function handleRequest (req, res) {
 - 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.**
 
 ```js
-import { QueryClient, QueryClientProvider } from 'react-query'
-import { Hydrate } from 'react-query/hydration'
+import { Hydrate, QueryClient, QueryClientProvider } from 'react-query'
 
 const dehydratedState = window.__REACT_QUERY_STATE__
 

docs/src/pages/guides/testing.md

@@ -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/pages/reference/hydration.md

@@ -0,0 +1,121 @@
+---
+id: hydration
+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 persistent locations. It only includes currently successful queries by default.
+
+```js
+import { dehydrate } from 'react-query'
+
+const dehydratedState = dehydrate(queryClient, {
+  shouldDehydrateQuery,
+})
+```
+
+> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `dehydrate` from `react-query/hydration`
+
+**Options**
+
+- `client: QueryClient`
+  - **Required**
+  - The `queryClient` that should be dehydrated
+- `options: DehydrateOptions`
+  - Optional
+  - `dehydrateMutations: boolean`
+    - Optional
+    - Whether or not to dehydrate mutations.
+  - `dehydrateQueries: boolean`
+    - Optional
+    - Whether or not to dehydrate queries.
+  - `shouldDehydrateMutation: (mutation: Mutation) => boolean`
+    - Optional
+    - This function is called for each mutation in the cache
+    - Return `true` to include this mutation in dehydration, or `false` otherwise
+    - The default version only includes paused mutations
+  - `shouldDehydrateQuery: (query: Query) => boolean`
+    - Optional
+    - This function is called for each query in the cache
+    - Return `true` to include this query in dehydration, or `false` otherwise
+    - The default version only includes successful queries, do `shouldDehydrateQuery: () => true` to include all queries
+
+**Returns**
+
+- `dehydratedState: DehydratedState`
+  - This includes everything that is needed to hydrate the `queryClient` at a later point
+  - You **should not** rely on the exact format of this response, it is not part of the public API and can change at any time
+  - This result is not in serialized form, you need to do that yourself if desired
+
+## `hydrate`
+
+`hydrate` adds a previously dehydrated state into a `cache`. If the queries included in dehydration already exist in the queryCache, `hydrate` does not overwrite them.
+
+```js
+import { hydrate } from 'react-query'
+
+hydrate(queryClient, dehydratedState, options)
+```
+
+> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `hydrate` from `react-query/hydration`
+
+**Options**
+
+- `client: QueryClient`
+  - **Required**
+  - The `queryClient` to hydrate the state into
+- `dehydratedState: DehydratedState`
+  - **Required**
+  - The state to hydrate into the client
+- `options: HydrateOptions`
+  - Optional
+  - `defaultOptions: DefaultOptions`
+    - Optional
+    - `mutations: MutationOptions` The default mutation options to use for the hydrated mutations.
+    - `queries: QueryOptions` The default query options to use for the hydrated queries.
+
+## `useHydrate`
+
+`useHydrate` adds a previously dehydrated state into the `queryClient` that would be returned by `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on update timestamp.
+
+```jsx
+import { useHydrate } from 'react-query'
+
+useHydrate(dehydratedState, options)
+```
+
+> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `useHydrate` from `react-query/hydration`
+
+**Options**
+
+- `dehydratedState: DehydratedState`
+  - **Required**
+  - The state to hydrate
+- `options: HydrateOptions`
+  - Optional
+  - `defaultOptions: QueryOptions`
+    - The default query options to use for the hydrated queries.
+
+## `Hydrate`
+
+`Hydrate` wraps `useHydrate` into component. Can be useful when you need hydrate in class component or need hydrate on same level where `QueryClientProvider` rendered.
+
+```js
+import { Hydrate } from 'react-query'
+
+function App() {
+  return <Hydrate state={dehydratedState}>...</Hydrate>
+}
+```
+
+> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `Hydrate` from `react-query/hydration`
+
+**Options**
+
+- `state: DehydratedState`
+  - The state to hydrate
+- `options: HydrateOptions`
+  - Optional
+  - `defaultOptions: QueryOptions`
+    - The default query options to use for the hydrated queries.

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

@@ -20,6 +20,7 @@ const {
   isPlaceholderData,
   isPreviousData,
   isRefetchError,
+  isRefetching,
   isStale,
   isSuccess,
   refetch,
@@ -220,6 +221,9 @@ const result = useQuery({
 - `isFetching: boolean`
   - Is `true` whenever a request is in-flight, which includes initial `loading` as well as background refetches.
   - Will be `true` if the query is currently fetching, including background fetching.
+- `isRefetching: boolean`
+  - Is `true` whenever a background refetch is in-flight, which _does not_ include initial `loading`
+  - Is the same as `isFetching && !isLoading`
 - `failureCount: number`
   - The failure count for the query.
   - Incremented every time the query fails.