You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: update persistQueryClient.md with Persister docs (#3356)
* docs: add idb example
* docs: consolidate sections
storing ~> persistQueryClientSave
restoring ~> persistQueryClientRestore
* docs: create section for persisters
* docs: focus cacheTime docs
persistQueryClient and createWebStoragePersister are unrelated
* docs: add tip for indexed db
* docs: cleanup intro
* docs: note additional interfaces available
* docs: reorder api to be more intuitive
* docs: improve wording
Copy file name to clipboardExpand all lines: docs/src/pages/plugins/persistQueryClient.md
+92-65Lines changed: 92 additions & 65 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,128 +3,117 @@ id: persistQueryClient
3
3
title: persistQueryClient
4
4
---
5
5
6
-
`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.
6
+
This is set of utilities for interacting with "persisters" which save your queryClient for later use. Different **persisters** can be used to store your client and cache to many different storage layers.
This utility comes packaged with `react-query` and is available under the `react-query/persistQueryClient` import.
16
+
**IMPORTANT** - for persist to work properly, you probably want to pass `QueryClient` a `cacheTime` value to override the default during hydration (as shown above).
16
17
17
-
## Usage
18
+
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.
18
19
19
-
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):
20
+
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.
**IMPORTANT** - for persist to work properly, you need to pass `QueryClient` a `cacheTime` value to override the default during hydration (as shown above).
44
-
45
-
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.
46
-
47
-
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.
48
-
49
-
You can also pass it `Infinity` to disable garbage collection behavior entirely.
34
+
### Environment Checking
35
+
A check for window `undefined` is performed prior to saving/restoring/removing your data (avoids build errors).
50
36
51
-
##How does it work?
37
+
### Cache Busting
52
38
53
-
- A check for window `undefined` is performed prior to saving/restoring/removing your data (avoids build errors).
54
-
55
-
### Storing
56
-
57
-
As you use your application:
58
-
59
-
- When your query/mutation cache is updated, it will be [`dehydrated`](../reference/hydration#dehydrate) and stored by the persister you provided. The officially supported persisters throttle this action to happen at most every 1 second to save on potentially expensive writes, but can be customized as you see fit.
60
-
61
-
#### Cache Busting
62
-
63
-
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.
39
+
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. If the cache that is found does not also have that buster string, it will be discarded. The following several functions accept this option:
- Attempts to [`hydrate`](../reference/hydration#hydrate) a previously persisted dehydrated query/mutation cache from the persister back into the query cache of the passed query client.
74
-
- 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.
49
+
If data is found to be any of the following:
75
50
76
-
### Removal
51
+
1. expired (see `maxAge`)
52
+
2. busted (see `buster`)
53
+
3. error (ex: `throws ...`)
54
+
4. empty (ex: `undefined`)
77
55
78
-
- If data is found to be expired (see `maxAge`), busted (see `buster`), error (ex: `throws ...`), or empty (ex: `undefined`), the persister `removeClient()` is called and the cache is immediately discarded.
56
+
the persister `removeClient()` is called and the cache is immediately discarded.
79
57
80
58
## API
81
59
82
-
### `persistQueryClientRestore`
60
+
### `persistQueryClientSave`
61
+
62
+
- Your query/mutation are [`dehydrated`](../reference/hydration#dehydrate) and stored by the persister you provided.
63
+
-`createWebStoragePersister` and `createAsyncStoragePersister` throttle this action to happen at most every 1 second to save on potentially expensive writes. Review their documentation to see how to customize their throttle timing.
83
64
84
-
This will attempt to restore a persister's stored cached to the query cache of the passed queryClient.
65
+
You can use this to explicitly persist the cache at the moment(s) you choose.
85
66
86
67
```ts
87
-
persistQueryClientRestore({
68
+
persistQueryClientSave({
88
69
queryClient,
89
70
persister,
90
-
maxAge=1000*60*60*24, // 24 hours
91
71
buster='',
92
-
hydrateOptions=undefined,
72
+
dehydrateOptions=undefined,
93
73
})
94
74
```
95
75
96
-
### `persistQueryClientSave`
76
+
### `persistQueryClientSubscribe`
77
+
78
+
Runs `persistQueryClientSave` whenever the cache changes for your `queryClient`. For example: you might initiate the `subscribe` when a user logs-in and checks "Remember me".
97
79
98
-
This will attempt to save the current query cache with the persister. You can use this to explicitly persist the cache at the moments you choose.
80
+
- It returns an `unsubscribe` function which you can use to discontinue the monitor; ending the updates to the persisted cache.
81
+
- If you want to erase the persisted cache after the `unsubscribe`, you can send a new `buster` to `persistQueryClientRestore` which will trigger the persister's `removeClient` function and discard the persisted cache.
99
82
100
83
```ts
101
-
persistQueryClientSave({
84
+
persistQueryClientSubscribe({
102
85
queryClient,
103
86
persister,
104
87
buster='',
105
88
dehydrateOptions=undefined,
106
89
})
107
90
```
108
91
109
-
### `persistQueryClientSubscribe`
92
+
### `persistQueryClientRestore`
110
93
111
-
This will subscribe to query cache updates which will run `persistQueryClientSave`. For example: you might initiate the `subscribe` when a user logs-in and checks "Remember me".
94
+
- Attempts to [`hydrate`](../reference/hydration#hydrate) a previously persisted dehydrated query/mutation cache from the persister back into the query cache of the passed query client.
95
+
- If a cache is found that is older than the `maxAge` (which by default is 24 hours), it will be discarded. This timing can be customized as you see fit.
112
96
113
-
- It returns an `unsubscribe` function which you can use to discontinue the monitor; ending the updates to the persisted cache.
114
-
- If you want to erase the persisted cache after the `unsubscribe`, you can send a new `buster` to `persistQueryClientRestore` which will trigger the persister's `removeClient` function and discard the persisted cache.
97
+
You can use this to restore the cache at moment(s) you choose.
115
98
116
99
```ts
117
-
persistQueryClientSubscribe({
100
+
persistQueryClientRestore({
118
101
queryClient,
119
102
persister,
103
+
maxAge=1000*60*60*24, // 24 hours
120
104
buster='',
121
-
dehydrateOptions=undefined,
105
+
hydrateOptions=undefined,
122
106
})
123
107
```
124
108
125
109
### `persistQueryClient`
126
110
127
-
This will automatically restore any persisted cache and subscribes to the query cache to persist any changes from the query cache to the persister. It returns an `unsubscribe` function which you can use to discontinue the monitor; ending the updates to the persisted cache.
111
+
Takes the following actions:
112
+
113
+
1. Immediately restores any persisted cache ([see `persistQueryClientRestore`](#persistqueryclientrestore))
114
+
2. Subscribes to the query cache and returns the `unsubscribe` function ([see `persistQueryClientSubscribe`](#persistqueryclientsubscribe)).
You can persist however you like. Here is an example of how to build an [Indexed DB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) persister. Compared to `Web Storage API`, Indexed DB is faster, stores more than 5MB, and doesn't require serialization. That means it can readily store Javascript native types, such as `Date` and `File`.
0 commit comments