feat(persistQueryClient): PersistQueryClientProvider

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`

examples/offline/package.json

@@ -0,0 +1,36 @@
+{
+  "private": true,
+  "scripts": {
+    "start": "rescripts start",
+    "build": "rescripts build",
+    "test": "rescripts test",
+    "eject": "rescripts eject"
+  },
+  "dependencies": {
+    "@tanstack/react-location": "^3.7.0",
+    "ky": "^0.30.0",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "react-hot-toast": "^2.2.0",
+    "react-query": "^4.0.0-alpha.19",
+    "react-scripts": "3.0.1"
+  },
+  "devDependencies": {
+    "@rescripts/cli": "^0.0.11",
+    "@rescripts/rescript-use-babel-config": "^0.0.8",
+    "@rescripts/rescript-use-eslint-config": "^0.0.9",
+    "babel-eslint": "10.0.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

examples/offline/public/favicon.ico

@@ -0,0 +1 @@
+https://rawcdn.githack.com/tannerlinsley/react-query/master/examples/simple/public/favicon.ico

examples/offline/public/index.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <!--
+      manifest.json provides metadata used when your web app is installed on a
+      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
+    -->
+    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
+    <!--
+      Notice the use of %PUBLIC_URL% in the tags above.
+      It will be replaced with the URL of the `public` folder during the build.
+      Only files inside the `public` folder can be referenced from the HTML.
+
+      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
+      work correctly both with client-side routing and a non-root public URL.
+      Learn how to configure a non-root public URL by running `npm run build`.
+    -->
+    <title>React App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <!--
+      This HTML file is a template.
+      If you open it directly in the browser, you will see an empty page.
+
+      You can add webfonts, meta tags, or analytics to this file.
+      The build step will place the bundled scripts into the <body> tag.
+
+      To begin the development, run `npm start` or `yarn start`.
+      To create a production bundle, use `npm run build` or `yarn build`.
+    -->
+  </body>
+</html>

examples/offline/public/manifest.json

@@ -0,0 +1,15 @@
+{
+  "short_name": "React App",
+  "name": "Create React App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}