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
@@ -48,31 +50,91 @@ You can also pass it `Infinity` to disable garbage collection behavior entirely.
48
50
49
51
## How does it work?
50
52
51
-
As you use your application:
53
+
- A check for window `undefined` is performed prior to saving/restoring/removing your data (avoids build errors).
52
54
53
-
- 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.
55
+
### Storing
54
56
55
-
When you reload/bootstrap your app:
57
+
As you use your application:
56
58
57
-
- Attempts to load a previously persisted dehydrated query/mutation cache from the persister
58
-
- 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.
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.
59
60
60
-
## Cache Busting
61
+
####Cache Busting
61
62
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.
- 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.
75
+
76
+
### Removal
77
+
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.
79
+
68
80
## API
69
81
82
+
### `persistQueryClientRestore`
83
+
84
+
This will attempt to restore a persister's stored cached to the query cache of the passed queryClient.
85
+
86
+
```ts
87
+
persistQueryClientRestore({
88
+
queryClient,
89
+
persister,
90
+
maxAge=1000*60*60*24, // 24 hours
91
+
buster='',
92
+
hydrateOptions=undefined,
93
+
})
94
+
```
95
+
96
+
### `persistQueryClientSave`
97
+
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.
99
+
100
+
```ts
101
+
persistQueryClientSave({
102
+
queryClient,
103
+
persister,
104
+
buster='',
105
+
dehydrateOptions=undefined,
106
+
})
107
+
```
108
+
109
+
### `persistQueryClientSubscribe`
110
+
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".
112
+
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.
115
+
116
+
```ts
117
+
persistQueryClientSubscribe({
118
+
queryClient,
119
+
persister,
120
+
buster='',
121
+
dehydrateOptions=undefined,
122
+
})
123
+
```
124
+
70
125
### `persistQueryClient`
71
126
72
-
Pass this function a `QueryClient` instance and a persister that will persist your cache. Both are **required**
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.
The hydration API requires values to be JSON serializable. If you need to dehydrate values that are not automatically serializable to JSON (like `Error` or `undefined`), you have to serialize them for yourself. Since only successful queries are included per default, to also include `Errors`, you have to provide `shouldDehydrateQuery`, e.g.:
51
+
Some storage systems (such as browser [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)) require values to be JSON serializable. If you need to dehydrate values that are not automatically serializable to JSON (like `Error` or `undefined`), you have to serialize them for yourself. Since only successful queries are included per default, to also include `Errors`, you have to provide `shouldDehydrateQuery`, e.g.:
52
52
53
53
```js
54
54
// server
55
55
conststate=dehydrate(client, { shouldDehydrateQuery: () =>true }) // to also include Errors
56
56
constserializedState=mySerialize(state) // transform Error instances to objects
57
57
58
58
// client
59
-
conststate=myDeserialize(serializedState) // transform objects back to Error instances
59
+
conststate=myDeserialize(serializedState) // transform objects back to Error instances
60
60
hydrate(client, state)
61
61
```
62
62
63
63
## `hydrate`
64
64
65
-
`hydrate` adds a previously dehydrated state into a `cache`. If the queries included in dehydration already exist in the queryCache, `hydrate` does not overwrite them.
65
+
`hydrate` adds a previously dehydrated state into a `cache`.
-`mutations: MutationOptions` The default mutation options to use for the hydrated mutations.
86
86
-`queries: QueryOptions` The default query options to use for the hydrated queries.
87
87
88
+
### Limitations
89
+
90
+
If the queries included in dehydration already exist in the queryCache, `hydrate` does not overwrite them and they will be **silently** discarded.
91
+
88
92
## `useHydrate`
89
93
90
94
`useHydrate` adds a previously dehydrated state into the `queryClient` that would be returned by `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on update timestamp.
0 commit comments