refactor(persistQueryClient): Make persistQueryClient stable (#2961)

* 🚚 Remove experimental from persist-query-client

* 🚚 Rename persistor -> persister

* ✏️  Fix Persistor -> Persister in imports

* 🚚 Update name in rollup config

* 🚚 Move createAsyncStoragePersister and createWebStoragePersister to stable version and rename persistor -> persister

* 📝  Update documentation

* 📝   Add migrating to v4 docs

* Apply suggestions from code review

Co-authored-by: Dominik Dorfmeister <office@dorfmeister.cc>

Author: prateek3255

createAsyncStoragePersister/package.json

@@ -0,0 +1,6 @@
+{
+  "internal": true,
+  "main": "../lib/createAsyncStoragePersister/index.js",
+  "module": "../es/createAsyncStoragePersister/index.js",
+  "types": "../types/createAsyncStoragePersister/index.d.ts"
+}

createAsyncStoragePersistor-experimental/package.json

@@ -0,0 +1,6 @@
+{
+  "internal": true,
+  "main": "../lib/createWebStoragePersister/index.js",
+  "module": "../es/createWebStoragePersister/index.js",
+  "types": "../types/createWebStoragePersister/index.d.ts"
+}

createWebStoragePersister/package.json

@@ -319,19 +319,19 @@
       "heading": true,
       "routes": [
         {
-          "title": "persistQueryClient (Experimental)",
+          "title": "persistQueryClient",
           "path": "/plugins/persistQueryClient",
           "editUrl": "/plugins/persistQueryClient.md"
         },
         {
-          "title": "createWebStoragePersistor (Experimental)",
-          "path": "/plugins/createWebStoragePersistor",
-          "editUrl": "/plugins/createWebStoragePersistor.md"
+          "title": "createWebStoragePersister",
+          "path": "/plugins/createWebStoragePersister",
+          "editUrl": "/plugins/createWebStoragePersister.md"
         },
         {
-          "title": "createAsyncStoragePersistor (Experimental)",
-          "path": "/plugins/createAsyncStoragePersistor",
-          "editUrl": "/plugins/createAsyncStoragePersistor.md"
+          "title": "createAsyncStoragePersister",
+          "path": "/plugins/createAsyncStoragePersister",
+          "editUrl": "/plugins/createAsyncStoragePersister.md"
         },
         {
           "title": "broadcastQueryClient (Experimental)",

createWebStoragePersistor-experimental/package.json

@@ -132,6 +132,22 @@ If you were importing anything from `'react-query/react'` directly in your proje
 + import { QueryClientProvider } from 'react-query/reactjs';
 ```
 
+### `persistQueryClient` and the corresponding persister plugins are no longer experimental and have been renamed
+
+The plugins `createWebStoragePersistor` and `createAsyncStoragePersistor` have been renamed to [`createWebStoragePersister`](/plugins/createWebStoragePersister) and [`createAsyncStoragePersister`](/plugins/createAsyncStoragePersister) respectively. The interface `Persistor` in `persistQueryClient` has also been renamed to `Persister`. Checkout [this stackexchange](https://english.stackexchange.com/questions/206893/persister-or-persistor) for the motivation of this change.
+
+Since these plugins are no longer experimental, their import paths have also been updated:
+
+```diff
+- import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
+- import { createWebStoragePersistor } from 'react-query/createWebStoragePersistor-experimental'
+- import { createAsyncStoragePersistor } from 'react-query/createAsyncStoragePersistor-experimental'
+
++ import { persistQueryClient } from 'react-query/persistQueryClient'
++ import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
++ import { createAsyncStoragePersister } from 'react-query/createAsyncStoragePersister'
+```
+
 ## New Features 🚀
 
 ### Mutation Cache Garbage Collection

docs/src/manifests/manifest.json

@@ -1,25 +1,23 @@
 ---
-id: createAsyncStoragePersistor
-title: createAsyncStoragePersistor (Experimental)
+id: createAsyncStoragePersister
+title: createAsyncStoragePersister
 ---
 
-> VERY IMPORTANT: This utility is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Use at your own risk. If you choose to rely on this in production in an experimental stage, please lock your version to a patch-level version to avoid unexpected breakages.
-
 ## Installation
 
-This utility comes packaged with `react-query` and is available under the `react-query/createAsyncStoragePersistor-experimental` import.
+This utility comes packaged with `react-query` and is available under the `react-query/createAsyncStoragePersister` import.
 
 ## Usage
 
-- Import the `createAsyncStoragePersistor` function
-- Create a new asyncStoragePersistor
+- Import the `createAsyncStoragePersister` function
+- Create a new asyncStoragePersister
   - you can pass any `storage` to it that adheres to the `AsyncStorage` interface - the example below uses the async-storage from React Native
 - Pass it to the [`persistQueryClient`](./persistQueryClient) function
 
 ```ts
 import AsyncStorage from '@react-native-async-storage/async-storage'
-import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
-import { createAsyncStoragePersistor } from 'react-query/createAsyncStoragePersistor-experimental'
+import { persistQueryClient } from 'react-query/persistQueryClient'
+import { createAsyncStoragePersister } from 'react-query/createAsyncStoragePersister'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -29,30 +27,30 @@ const queryClient = new QueryClient({
   },
 })
 
-const asyncStoragePersistor = createAsyncStoragePersistor({
+const asyncStoragePersister = createAsyncStoragePersister({
   storage: AsyncStorage
 })
 
 persistQueryClient({
   queryClient,
-  persistor: asyncStoragePersistor,
+  persister: asyncStoragePersister,
 })
 ```
 
 ## API
 
-### `createAsyncStoragePersistor`
+### `createAsyncStoragePersister`
 
-Call this function to create an asyncStoragePersistor that you can use later with `persistQueryClient`.
+Call this function to create an asyncStoragePersister that you can use later with `persistQueryClient`.
 
 ```js
-createAsyncStoragePersistor(options: CreateAsyncStoragePersistorOptions)
+createAsyncStoragePersister(options: CreateAsyncStoragePersisterOptions)
 ```
 
 ### `Options`
 
 ```ts
-interface CreateAsyncStoragePersistorOptions {
+interface CreateAsyncStoragePersisterOptions {
   /** The storage client used for setting an retrieving items from cache */
   storage: AsyncStorage
   /** The key to use when storing the cache to localStorage */

docs/src/pages/guides/migrating-to-react-query-4.md

@@ -1,23 +1,21 @@
 ---
-id: createWebStoragePersistor
-title: createWebStoragePersistor (Experimental)
+id: createWebStoragePersister
+title: createWebStoragePersister
 ---
 
-> VERY IMPORTANT: This utility is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Use at your own risk. If you choose to rely on this in production in an experimental stage, please lock your version to a patch-level version to avoid unexpected breakages.
-
 ## Installation
 
-This utility comes packaged with `react-query` and is available under the `react-query/createWebStoragePersistor-experimental` import.
+This utility comes packaged with `react-query` and is available under the `react-query/createWebStoragePersister` import.
 
 ## Usage
 
-- Import the `createWebStoragePersistor` function
-- Create a new webStoragePersistor
+- Import the `createWebStoragePersister` function
+- Create a new webStoragePersister
 - Pass it to the [`persistQueryClient`](./persistQueryClient) function
 
 ```ts
-import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
-import { createWebStoragePersistor } from 'react-query/createWebStoragePersistor-experimental'
+import { persistQueryClient } from 'react-query/persistQueryClient'
+import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -27,29 +25,29 @@ const queryClient = new QueryClient({
   },
 })
 
-const localStoragePersistor = createWebStoragePersistor({ storage: window.localStorage })
-// const sessionStoragePersistor = createWebStoragePersistor({ storage: window.sessionStorage })
+const localStoragePersister = createWebStoragePersister({ storage: window.localStorage })
+// const sessionStoragePersister = createWebStoragePersister({ storage: window.sessionStorage })
 
 persistQueryClient({
   queryClient,
-  persistor: localStoragePersistor,
+  persister: localStoragePersister,
 })
 ```
 
 ## API
 
-### `createWebStoragePersistor`
+### `createWebStoragePersister`
 
-Call this function to create a webStoragePersistor that you can use later with `persistQueryClient`.
+Call this function to create a webStoragePersister that you can use later with `persistQueryClient`.
 
 ```js
-createWebStoragePersistor(options: CreateWebStoragePersistorOptions)
+createWebStoragePersister(options: CreateWebStoragePersisterOptions)
 ```
 
 ### `Options`
 
 ```ts
-interface CreateWebStoragePersistorOptions {
+interface CreateWebStoragePersisterOptions {
   /** The storage client used for setting an retrieving items from cache (window.localStorage or window.sessionStorage) */
   storage: Storage
   /** The key to use when storing the cache */

…s/plugins/createAsyncStoragePersistor.md …s/plugins/createAsyncStoragePersister.mddocs/src/pages/plugins/createAsyncStoragePersistor.md renamed to docs/src/pages/plugins/createAsyncStoragePersister.md docs/src/pages/plugins/createAsyncStoragePersistor.md renamed to docs/src/pages/plugins/createAsyncStoragePersister.md

@@ -1,28 +1,26 @@
 ---
 id: persistQueryClient
-title: persistQueryClient (Experimental)
+title: persistQueryClient
 ---
 
-> VERY IMPORTANT: This utility is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Use at your own risk. If you choose to rely on this in production in an experimental stage, please lock your version to a patch-level version to avoid unexpected breakages.
+`persistQueryClient` is a utility for persisting the state of your queryClient and its caches for later use. Different **persisters** can be used to store your client and cache to many different storage layers.
 
-`persistQueryClient` is a utility for persisting the state of your queryClient and its caches for later use. Different **persistors** can be used to store your client and cache to many different storage layers.
+## Officially Supported Persisters
 
-## Officially Supported Persistors
-
-- [createWebStoragePersistor (Experimental)](/plugins/createWebStoragePersistor)
-- [createAsyncStoragePersistor (Experimental)](/plugins/createAsyncStoragePersistor)
+- [createWebStoragePersister](/plugins/createWebStoragePersister)
+- [createAsyncStoragePersister](/plugins/createAsyncStoragePersister)
 
 ## Installation
 
-This utility comes packaged with `react-query` and is available under the `react-query/persistQueryClient-experimental` import.
+This utility comes packaged with `react-query` and is available under the `react-query/persistQueryClient` import.
 
 ## Usage
 
-Import the `persistQueryClient` function, and pass it your `QueryClient` instance (with a `cacheTime` set), and a Persistor interface (there are multiple persistor types you can use):
+Import the `persistQueryClient` function, and pass it your `QueryClient` instance (with a `cacheTime` set), and a Persister interface (there are multiple persister types you can use):
 
 ```ts
-import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
-import { createWebStoragePersistor } from 'react-query/createWebStoragePersistor-experimental'
+import { persistQueryClient } from 'react-query/persistQueryClient'
+import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -32,11 +30,11 @@ const queryClient = new QueryClient({
   },
 })
 
-const localStoragePersistor = createWebStoragePersistor({storage: window.localStorage})
+const localStoragePersister = createWebStoragePersister({storage: window.localStorage})
 
 persistQueryClient({
   queryClient,
-  persistor: localStoragePersistor,
+  persister: localStoragePersister,
 })
 ```
 
@@ -52,29 +50,29 @@ You can also pass it `Infinity` to disable garbage collection behavior entirely.
 
 As you use your application:
 
-- When your query/mutation cache is updated, it will be dehydrated and stored by the persistor you provided. **By default**, this action is throttled to happen at most every 1 second to save on potentially expensive writes to a persistor, but can be customized as you see fit.
+- When your query/mutation cache is updated, it will be dehydrated and stored by the persister you provided. **By default**, this action is throttled to happen at most every 1 second to save on potentially expensive writes to a persister, but can be customized as you see fit.
 
 When you reload/bootstrap your app:
 
-- Attempts to load a previously persisted dehydrated query/mutation cache from the persistor
+- Attempts to load a previously persisted dehydrated query/mutation cache from the persister
 - If a cache is found that is older than the `maxAge` (which by default is 24 hours), it will be discarded. This can be customized as you see fit.
 
 ## Cache Busting
 
 Sometimes you may make changes to your application or data that immediately invalidate any and all cached data. If and when this happens, you can pass a `buster` string option to `persistQueryClient`, and if the cache that is found does not also have that buster string, it will be discarded.
 
 ```ts
-persistQueryClient({ queryClient, persistor, buster: buildHash })
+persistQueryClient({ queryClient, persister, buster: buildHash })
 ```
 
 ## API
 
 ### `persistQueryClient`
 
-Pass this function a `QueryClient` instance and a persistor that will persist your cache. Both are **required**
+Pass this function a `QueryClient` instance and a persister that will persist your cache. Both are **required**
 
 ```ts
-persistQueryClient({ queryClient, persistor })
+persistQueryClient({ queryClient, persister })
 ```
 
 ### `Options`
@@ -85,9 +83,9 @@ An object of options:
 interface PersistQueryClientOptions {
   /** The QueryClient to persist */
   queryClient: QueryClient
-  /** The Persistor interface for storing and restoring the cache
+  /** The Persister interface for storing and restoring the cache
    * to/from a persisted location */
-  persistor: Persistor
+  persister: Persister
   /** The max-allowed age of the cache.
    * If a persisted cache is found that is older than this
    * time, it will be discarded */
@@ -111,12 +109,12 @@ The default options are:
 }
 ```
 
-## Building a Persistor
+## Building a Persister
 
-Persistors have the following interface:
+Persisters have the following interface:
 
 ```ts
-export interface Persistor {
+export interface Persister {
   persistClient(persistClient: PersistedClient): Promisable<void>
   restoreClient(): Promisable<PersistedClient | undefined>
   removeClient(): Promisable<void>
@@ -133,4 +131,4 @@ export interface PersistedClient {
 }
 ```
 
-Satisfy all of these interfaces and you've got yourself a persistor!
+Satisfy all of these interfaces and you've got yourself a persister!

…ges/plugins/createWebStoragePersistor.md …ges/plugins/createWebStoragePersister.mddocs/src/pages/plugins/createWebStoragePersistor.md renamed to docs/src/pages/plugins/createWebStoragePersister.md docs/src/pages/plugins/createWebStoragePersistor.md renamed to docs/src/pages/plugins/createWebStoragePersister.md

@@ -9,8 +9,23 @@ import {
   QueryClientProvider,
 } from "react-query";
 import { ReactQueryDevtools } from "react-query/devtools";
+import { persistQueryClient } from 'react-query/persistQueryClient';
+import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
 
-const queryClient = new QueryClient();
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
+    },
+  },
+})
+
+const localStoragePersister = createWebStoragePersister({storage: window.localStorage})
+
+persistQueryClient({
+  queryClient,
+  persister: localStoragePersister,
+})
 
 function App() {
   const [postId, setPostId] = React.useState(-1);