fix(experimental): persistQueryClient and persistors (TanStack#1789)

* fix(experimental): refactor to persistQueryClient and persistor interfaces

* clean up basic example

Author: tannerlinsley

createLocalStoragePersistor-experimental/package.json

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

docs/src/manifests/manifest.json

@@ -303,9 +303,14 @@
       "heading": true,
       "routes": [
         {
-          "title": "Persist - LocalStorage (Experimental)",
-          "path": "/plugins/persist-localstorage",
-          "editUrl": "/plugins/persist-localstorage.md"
+          "title": "persistQueryClient (Experimental)",
+          "path": "/plugins/persistQueryClient",
+          "editUrl": "/plugins/persistQueryClient.md"
+        },
+        {
+          "title": "createLocalStoragePersistor (Experimental)",
+          "path": "/plugins/createLocalStoragePersistor",
+          "editUrl": "/plugins/createLocalStoragePersistor.md"
         }
       ]
     },

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

@@ -20,7 +20,7 @@ Previous versions of React Query were awesome and brought some amazing new featu
 - Observe queries/mutations outside of React
 - Use the React Query core logic anywhere you want!
 - Bundled/Colocated Devtools via `react-query/devtools`
-- Cache Persistence to localstorage (experimental via `react-query/persist-localstorage-experimental`)
+- Cache Persistence to localstorage (experimental via `react-query/persistQueryClient-experimental` and `react-query/createLocalStoragePersistor-experimental`)
 
 ## Breaking Changes
 

docs/src/pages/plugins/createLocalStoragePersistor.md

@@ -0,0 +1,69 @@
+---
+id: createLocalStoragePersistor
+title: createLocalStoragePersistor (Experimental)
+---
+
+> 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/createLocalStoragePersistor-experimental` import.
+
+## Usage
+
+- Import the `createLocalStoragePersistor` function
+- Create a new localStoragePersistor
+- Pass it to the [`persistQueryClient`](../persistQueryClient) function
+
+```ts
+import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
+import { createLocalStoragePersistor } from 'react-query/createLocalStoragePersistor-experimental'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
+    },
+  },
+})
+
+const localStoragePersistor = createLocalStoragePersistor()
+
+persistQueryClient({
+  queryClient
+  persistor: localStoragePersistor,
+})
+```
+
+## API
+
+### `createLocalStoragePersistor`
+
+Call this function (with an optional options object) to create a localStoragePersistor that you can use later with `persisteQueryClient`.
+
+```js
+createLocalStoragePersistor(options?: CreateLocalStoragePersistorOptions)
+```
+
+### `Options`
+
+An optional object of options:
+
+```js
+interface CreateLocalStoragePersistorOptions {
+  /** The key to use when storing the cache to localstorage */
+  localStorageKey?: string
+  /** To avoid localstorage spamming,
+   * pass a time in ms to throttle saving the cache to disk */
+  throttleTime?: number
+}
+```
+
+The default options are:
+
+```js
+{
+  localStorageKey = `REACT_QUERY_OFFLINE_CACHE`,
+  throttleTime = 1000,
+}
+```

docs/src/pages/plugins/persist-localstorage.md

@@ -0,0 +1,131 @@
+---
+id: persistQueryClient
+title: persistQueryClient (Experimental)
+---
+
+> 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 **persistors** can be used to store your client and cache to many different storage layers.
+
+## Officially Supported Persistors
+
+- [createLocalStoragePersistor (Experimental)](../createLocalStoragePersistor)
+
+## Installation
+
+This utility comes packaged with `react-query` and is available under the `react-query/persistQueryClient-experimental` 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):
+
+```ts
+import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
+import { createLocalStoragePersistor } from 'react-query/createLocalStoragePersistor-experimental'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
+    },
+  },
+})
+
+const localStoragePersistor = createLocalStoragePersistor()
+
+persistQueryClient({
+  queryClient
+  persistor: localStoragePersistor,
+})
+```
+
+**IMPORTANT** - for persist to work properly, you need to pass `QueryClient` a `cacheTime` value to override the default during hydration (as shown above).
+
+If it is not set when creating the `QueryClient` instance, it will default to `300000` (5 minutes) for hydration, and the stored cache will be discarded after 5 minutes of inactivity. This is the default garbage collection behavior.
+
+It should be set as the same value or higher than persistQueryClient's `maxAge` option. E.g. if `maxAge` is 24 hours (the default) then `cacheTime` should be 24 hours or higher. If lower than `maxAge`, garbage collection will kick in and discard the stored cache earlier than expected.
+
+You can also pass it `Infinity` to disable garbage collection behavior entirely.
+
+## How does it work?
+
+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 you reload/bootstrap your app:
+
+- Attempts to load a previously persisted dehydrated query/mutation cache from the persistor
+- 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 })
+```
+
+## API
+
+### `persistQueryClient`
+
+Pass this function a `QueryClient` instance and a persistor that will persist your cache. Both are **required**
+
+```ts
+persistQueryClient({ queryClient, persistor })
+```
+
+### `Options`
+
+An object of options:
+
+```ts
+interface PersistQueryClientOptions {
+  /** The QueryClient to persist */
+  queryClient: QueryClient
+  /** The Persistor interface for storing and restoring the cache
+   * to/from a persisted location */
+  persistor: Persistor
+  /** The max-allowed age of the cache.
+   * If a persisted cache is found that is older than this
+   * time, it will be discarded */
+  maxAge?: number
+  /** A unique string that can be used to forcefully
+   * invalidate existing caches if they do not share the same buster string */
+  buster?: string
+}
+```
+
+The default options are:
+
+```ts
+{
+  maxAge = 1000 * 60 * 60 * 24, // 24 hours
+  buster = '',
+}
+```
+
+## Building a Persistor
+
+Persistors have the following interface:
+
+```ts
+export interface Persistor {
+  persistClient(persistClient: PersistedClient): Promisable<void>
+  restoreClient(): Promisable<PersistedClient | undefined>
+  removeClient(): Promisable<void>
+}
+```
+
+Persisted Client entries have the following interface:
+
+```ts
+export interface PersistedClient {
+  timestamp: number
+  buster: string
+  cacheState: any
+}
+```
+
+Satisfy all of these interfaces and you've got yourself a persistor!

docs/src/pages/plugins/persistQueryClient.md

@@ -48,7 +48,8 @@
     "es",
     "hydration",
     "devtools",
-    "persist-localstorage-experimental",
+    "persistQueryClient-experimental",
+    "createLocalStoragePersistor-experimental",
     "lib",
     "react",
     "scripts",
@@ -121,6 +122,7 @@
     "rollup-plugin-size": "^0.2.2",
     "rollup-plugin-terser": "^6.1.0",
     "rollup-plugin-visualizer": "^4.0.4",
+    "type-fest": "^0.21.0",
     "typescript": "^4.1.2"
   }
 }

package.json

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

persist-localstorage-experimental/package.json

@@ -20,9 +20,14 @@ const inputSrcs = [
   ['src/devtools/index.ts', 'ReactQueryDevtools', 'react-query-devtools'],
   ['src/hydration/index.ts', 'ReactQueryHydration', 'react-query-hydration'],
   [
-    'src/persist-localstorage-experimental/index.ts',
-    'ReactQueryPersistLocalStorageExperimental',
-    'persist-localstorage-experimental',
+    'src/persistQueryClient-experimental/index.ts',
+    'ReactQueryPersistQueryClientExperimental',
+    'persistQueryClient-experimental',
+  ],
+  [
+    'src/createLocalStoragePersistor-experimental/index.ts',
+    'ReactQueryCreateLocalStoragePersistorExperimental',
+    'createLocalStoragePersistor-experimental',
   ],
 ]