feat(persistQueryClient): PersistQueryClientProvider (#3248)

* feat(persistQueryClient): PersistQueryClientProvider

* feat(persistQueryClient): PersistQueryClientProvider

defer subscription if we are hydrating

* feat(persistQueryClient): PersistQueryClientProvider

make sure we do not subscribe if the component unmounts before restoring has finished

* feat(persistQueryClient): PersistQueryClientProvider

make unsubscribe a const so that we don't mutate what we've exposed

* feat(persistQueryClient): PersistQueryClientProvider

make hydrating queries go in fetchStatus: 'idle' instead of paused

because paused means we have started fetching and are pausing, and we will also continue, while with hydration, we haven't started fetching, and we also might not start if we get "fresh" data from hydration

* feat(persistQueryClient): PersistQueryClientProvider

don't export IsHydratingProvider, as it shouldn't be needed by consumers

* feat(persistQueryClient): PersistQueryClientProvider

provide onSuccess and onError callbacks to PersistQueryClientProvider so that you can react to the persisting having finished, to e.g. have a point where you can resumePausedMutations

* feat(persistQueryClient): PersistQueryClientProvider

tests for onSuccess callback, and remove onError callback, because the persister itself catches errors and removes the store

* feat(persistQueryClient): PersistQueryClientProvider

test for useQueries

* feat(persistQueryClient): PersistQueryClientProvider

docs

* make restore in mockPersister a bit slower to stabilize tests

* better persistQueryClient docs

* feat(PersistQueryClientProvider): make sure we can hydrate into multiple clients

and error handling

* offline example

* extract to custom hook

* remove onError callback

because errors are caught internally by persistQueryClient and the persisted client is then removed

* just ignore stale hydrations if the client changes

* Revert "just ignore stale hydrations if the client changes"

This reverts commit 91e2afb.

* just ignore stale hydrations if the client changes

this makes sure we only call onSuccess once, for the "latest" client

* since QueryClientProviderProps is now a union type, we can't extend it from an interface

Author: TkDodo

docs/src/manifests/manifest.json

@@ -326,6 +326,11 @@
           "title": "React Native",
           "path": "/examples/react-native",
           "editUrl": "/examples/react-native.mdx"
+        },
+        {
+          "title": "Offline Queries and Mutations",
+          "path": "/examples/offline",
+          "editUrl": "/examples/offline.mdx"
         }
       ]
     },

docs/src/pages/examples/offline.mdx

@@ -0,0 +1,23 @@
+---
+id: offline
+title: Offline Queries and Mutations
+toc: false
+---
+
+- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-query/tree/alpha/examples/offline)
+- [View Source](https://github.com/tannerlinsley/react-query/tree/alpha/examples/offline)
+
+<iframe
+  src="https://codesandbox.io/embed/github/tannerlinsley/react-query/tree/alpha/examples/offline?autoresize=1&fontsize=14&theme=dark"
+  title="tannerlinsley/react-query: offline"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  style={{
+    width: '100%',
+    height: '80vh',
+    border: '0',
+    borderRadius: 8,
+    overflow: 'hidden',
+    position: 'static',
+    zIndex: 0,
+  }}
+></iframe>

docs/src/pages/plugins/persistQueryClient.md

@@ -159,6 +159,68 @@ There are actually three interfaces available:
 - `PersistedQueryClientRestoreOptions` is used for `persistQueryClientRestore` (doesn't use `dehydrateOptions`).
 - `PersistQueryClientOptions` is used for `persistQueryClient`
 
+## Usage with React
+
+[persistQueryClient](#persistQueryClient) will try to restore the cache and automatically subscribes to further changes, thus syncing your client to the provided storage.
+
+However, restoring is asynchronous, because all persisters are async by nature, which means that if you render your App while you are restoring, you might get into race conditions if a query mounts and fetches at the same time.
+
+Further, if you subscribe to changes outside of the React component lifecycle, you have no way of unsubscribing:
+
+```js
+// 🚨 never unsubscribes from syncing
+persistQueryClient({
+  queryClient,
+  persister: localStoragePersister,
+})
+
+// 🚨 happens at the same time as restoring
+ReactDOM.render(<App />, rootElement)
+```
+
+### PeristQueryClientProvider
+
+For this use-case, you can use the `PersistQueryClientProvider`. It will make sure to subscribe / unsubscribe correctly according to the React component lifecycle, and it will also make sure that queries will not start fetching while we are still restoring. Queries will still render though, they will just be put into `fetchingState: 'idle'` until data has been restored. Then, they will refetch unless the restored data is _fresh_ enough, and _initialData_ will also be respected. It can be used _instead of_ the normal [QueryClientProvider](../reference/QueryClientProvider):
+
+```jsx
+
+import { PersistQueryClientProvider } from 'react-query/persistQueryClient'
+import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
+    },
+  },
+})
+
+const persister = createWebStoragePersister({
+  storage: window.localStorage,
+})
+
+ReactDOM.render(
+  <PersistQueryClientProvider
+    client={queryClient}
+    persistOptions={{ persister }}
+  >
+    <App />
+  </PersistQueryClientProvider>,
+  rootElement
+)
+```
+
+#### Props
+
+`PersistQueryClientProvider` takes the same props as [QueryClientProvider](../reference/QueryClientProvider), and additionally:
+
+- `persistOptions: PersistQueryClientOptions`
+  - all [options](#options) you cann pass to [persistQueryClient](#persistqueryclient) minus the QueryClient itself
+- `onSuccess?: () => void`
+  - optional
+  - will be called when the initial restore is finished
+  - can be used to [resumePausedMutations](../reference/QueryClient#queryclientresumepausedmutations)
+
 ## Persisters
 
 ### Persisters Interface

docs/src/pages/reference/QueryClient.md

@@ -49,6 +49,7 @@ Its available methods are:
 - [`queryClient.getQueryCache`](#queryclientgetquerycache)
 - [`queryClient.getMutationCache`](#queryclientgetmutationcache)
 - [`queryClient.clear`](#queryclientclear)
+- - [`queryClient.resumePausedMutations`](#queryclientresumepausedmutations)
 
 **Options**
 
@@ -563,3 +564,11 @@ The `clear` method clears all connected caches.
 ```js
 queryClient.clear()
 ```
+
+## `queryClient.resumePausedMutations`
+
+Can be used to resume mutations that have been paused because there was no network connection.
+
+```js
+queryClient.resumePausedMutations()
+```

examples/offline/.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["react-app"]
+}

examples/offline/.eslintrc

@@ -0,0 +1,7 @@
+{
+  "extends": ["react-app", "prettier"],
+  "rules": {
+    // "eqeqeq": 0,
+    // "jsx-a11y/anchor-is-valid": 0
+  }
+}

examples/offline/.gitignore

@@ -0,0 +1,26 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

examples/offline/.prettierrc

@@ -0,0 +1 @@
+{}

examples/offline/.rescriptsrc.js

@@ -0,0 +1,37 @@
+const path = require("path");
+const resolveFrom = require("resolve-from");
+
+const fixLinkedDependencies = (config) => {
+  config.resolve = {
+    ...config.resolve,
+    alias: {
+      ...config.resolve.alias,
+      react$: resolveFrom(path.resolve("node_modules"), "react"),
+      "react-dom$": resolveFrom(path.resolve("node_modules"), "react-dom"),
+    },
+  };
+  return config;
+};
+
+const includeSrcDirectory = (config) => {
+  config.resolve = {
+    ...config.resolve,
+    modules: [path.resolve("src"), ...config.resolve.modules],
+  };
+  return config;
+};
+
+const allowOutsideSrc = (config) => {
+  config.resolve.plugins = config.resolve.plugins.filter(
+    (p) => p.constructor.name !== "ModuleScopePlugin"
+  );
+  return config;
+};
+
+module.exports = [
+  ["use-babel-config", ".babelrc"],
+  ["use-eslint-config", ".eslintrc"],
+  fixLinkedDependencies,
+  allowOutsideSrc,
+  // includeSrcDirectory,
+];

examples/offline/README.md

@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install` or `yarn`
+- `npm run start` or `yarn start`