Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

createPersister.md

203 lines7.8 KB

1---
2id: createPersister
3title: experimental_createQueryPersister
4---
5​
6## Installation
7​
8This utility comes as a separate package and is available under the `'@tanstack/query-persist-client-core'` import.
9​
10```bash
11npm install @tanstack/query-persist-client-core
12```
13​
14or
15​
16```bash
17pnpm add @tanstack/query-persist-client-core
18```
19​
20or
21​
22```bash
23yarn add @tanstack/query-persist-client-core
24```
25​
26or
27​
28```bash
29bun add @tanstack/query-persist-client-core
30```
31​
32> Note: This util is also included in the `@tanstack/react-query-persist-client` package, so you do not need to install it separately if you are using that package.
33​
34## Usage
35​
36- Import the `experimental_createQueryPersister` function
37- Create a new `experimental_createQueryPersister`
38 - you can pass any `storage` to it that adheres to the `AsyncStorage` interface - the example below uses the async-storage from React Native.
39- Pass that `persister` as an option to your Query. This can be done either by passing it to the `defaultOptions` of the `QueryClient` or to any `useQuery` hook instance.
40 - If you pass this `persister` as `defaultOptions`, all queries will be persisted to the provided `storage`. You can additionally narrow this down by passing `filters`. In contrast to the `persistClient` plugin, this will not persist the whole query client as a single item, but each query separately. As a key, the query hash is used.
41 - If you provide this `persister` to a single `useQuery` hook, only this Query will be persisted.
42- Note: `queryClient.setQueryData()` operations are not persisted, this means that if you perform an optimistic update and refresh the page before the query has been invalidated, your changes to the query data will be lost. See https://github.com/TanStack/query/issues/6310
43​
44This way, you do not need to store whole `QueryClient`, but choose what is worth to be persisted in your application. Each query is lazily restored (when the Query is first used) and persisted (after each run of the `queryFn`), so it does not need to be throttled. `staleTime` is also respected after restoring the Query, so if data is considered `stale`, it will be refetched immediately after restoring. If data is `fresh`, the `queryFn` will not run.
45​
46Garbage collecting a Query from memory **does not** affect the persisted data. That means Queries can be kept in memory for a shorter period of time to be more **memory efficient**. If they are used the next time, they will just be restored from the persistent storage again.
47​
48```tsx
49import AsyncStorage from '@react-native-async-storage/async-storage'
50import { QueryClient } from '@tanstack/react-query'
51import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'
52​
53const persister = experimental_createQueryPersister({
54 storage: AsyncStorage,
55 maxAge: 1000 * 60 * 60 * 12, // 12 hours
56})
57​
58const queryClient = new QueryClient({
59 defaultOptions: {
60 queries: {
61 gcTime: 1000 * 30, // 30 seconds
62 persister: persister.persisterFn,
63 },
64 },
65})
66```
67​
68### Adapted defaults
69​
70The `createPersister` plugin technically wraps the `queryFn`, so it doesn't restore if the `queryFn` doesn't run. In that way, it acts as a caching layer between the Query and the network. Thus, the `networkMode` defaults to `'offlineFirst'` when a persister is used, so that restoring from the persistent storage can also happen even if there is no network connection.
71​
72## Additional utilities
73​
74Invoking `experimental_createQueryPersister` returns additional utilities in addition to `persisterFn` for easier implementation of userland functionalities.
75​
76### `persistQueryByKey(queryKey: QueryKey, queryClient: QueryClient): Promise<void>`
77​
78This function will persist `Query` to storage and key defined when creating persister.
79This utility might be used along `setQueryData` to persist optimistic update to storage without waiting for invalidation.
80​
81```tsx
82const persister = experimental_createQueryPersister({
83 storage: AsyncStorage,
84 maxAge: 1000 * 60 * 60 * 12, // 12 hours
85})
86​
87const queryClient = useQueryClient()
88​
89useMutation({
90 mutationFn: updateTodo,
91 onMutate: async (newTodo) => {
92 ...
93 // Optimistically update to the new value
94 queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
95 // And persist it to storage
96 persister.persistQueryByKey(['todos'], queryClient)
97 ...
98 },
99})
100```
101​
102### `retrieveQuery<T>(queryHash: string): Promise<T | undefined>`
103​
104This function would attempt to retrieve persisted query by `queryHash`.
105If `query` is `expired`, `busted` or `malformed` it would be removed from the storage instead, and `undefined` would be returned.
106​
107### `persisterGc(): Promise<void>`
108​
109This function can be used to sporadically clean up stoage from `expired`, `busted` or `malformed` entries.
110​
111For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.
112For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
113​
114### `restoreQueries(queryClient: QueryClient, filters): Promise<void>`
115​
116This function can be used to restore queries that are currently stored by persister.
117For example when your app is starting up in offline mode, or you want all or only specific data from previous session to be immediately available without intermediate `loading` state.
118​
119The filter object supports the following properties:
120​
121- `queryKey?: QueryKey`
122 - Set this property to define a query key to match on.
123- `exact?: boolean`
124 - If you don't want to search queries inclusively by query key, you can pass the `exact: true` option to return only the query with the exact query key you have passed.
125​
126For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.
127For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
128​
129## API
130​
131### `experimental_createQueryPersister`
132​
133```tsx
134experimental_createQueryPersister(options: StoragePersisterOptions)
135```
136​
137#### `Options`
138​
139```tsx
140export interface StoragePersisterOptions {
141 /** The storage client used for setting and retrieving items from cache.
142 * For SSR pass in `undefined`.
143 */
144 storage: AsyncStorage | Storage | undefined | null
145 /**
146 * How to serialize the data to storage.
147 * @default `JSON.stringify`
148 */
149 serialize?: (persistedQuery: PersistedQuery) => string
150 /**
151 * How to deserialize the data from storage.
152 * @default `JSON.parse`
153 */
154 deserialize?: (cachedString: string) => PersistedQuery
155 /**
156 * A unique string that can be used to forcefully invalidate existing caches,
157 * if they do not share the same buster string
158 */
159 buster?: string
160 /**
161 * The max-allowed age of the cache in milliseconds.
162 * If a persisted cache is found that is older than this
163 * time, it will be discarded
164 * @default 24 hours
165 */
166 maxAge?: number
167 /**
168 * Prefix to be used for storage key.
169 * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.
170 */
171 prefix?: string
172 /**
173 * If set to `true`, the query will refetch on successful query restoration if the data is stale.
174 * If set to `false`, the query will not refetch on successful query restoration.
175 * If set to `'always'`, the query will always refetch on successful query restoration.
176 * Defaults to `true`.
177 */
178 refetchOnRestore?: boolean | 'always'
179 /**
180 * Filters to narrow down which Queries should be persisted.
181 */
182 filters?: QueryFilters
184​
185interface AsyncStorage<TStorageValue = string> {
186 getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
187 setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
188 removeItem: (key: string) => MaybePromise<void>
189 entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
191```
192​
193The default options are:
194​
195```tsx
197 prefix = 'tanstack-query',
198 maxAge = 1000 * 60 * 60 * 24,
199 serialize = JSON.stringify,
200 deserialize = JSON.parse,
201 refetchOnRestore = true,
203```