fix(query-persist-client-core): add option to change behavior of refetch after restore (#9745)

Author: DamianOsipiuk

.changeset/pretty-geese-scream.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/query-persist-client-core': minor
+---
+
+Added a refetchOnRestore setting to control refetching after restoring persisted queries

docs/framework/react/plugins/createPersister.md

@@ -169,6 +169,13 @@ export interface StoragePersisterOptions {
    * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.
    */
   prefix?: string
+  /**
+   * If set to `true`, the query will refetch on successful query restoration if the data is stale.
+   * If set to `false`, the query will not refetch on successful query restoration.
+   * If set to `'always'`, the query will always refetch on successful query restoration.
+   * Defaults to `true`.
+   */
+  refetchOnRestore?: boolean | 'always'
   /**
    * Filters to narrow down which Queries should be persisted.
    */
@@ -191,5 +198,6 @@ The default options are:
   maxAge = 1000 * 60 * 60 * 24,
   serialize = JSON.stringify,
   deserialize = JSON.parse,
+  refetchOnRestore = true,
 }
 ```

docs/framework/vue/plugins/createPersister.md

@@ -33,10 +33,11 @@ bun add @tanstack/query-persist-client-core
 
 - Import the `experimental_createQueryPersister` function
 - Create a new `experimental_createQueryPersister`
-  - you can pass any `storage` to it that adheres to the `AsyncStorage` or `Storage` interface
+  - you can pass any `storage` to it that adheres to the `AsyncStorage` interface
 - 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.
   - 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.
   - If you provide this `persister` to a single `useQuery` hook, only this Query will be persisted.
+- 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
 
 This 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.
 
@@ -65,6 +66,63 @@ const queryClient = new QueryClient({
 
 The `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.
 
+## Additional utilities
+
+Invoking `experimental_createQueryPersister` returns additional utilities in addition to `persisterFn` for easier implementation of userland functionalities.
+
+### `persistQueryByKey(queryKey: QueryKey, queryClient: QueryClient): Promise<void>`
+
+This function will persist `Query` to storage and key defined when creating persister.  
+This utility might be used along `setQueryData` to persist optimistic update to storage without waiting for invalidation.
+
+```tsx
+const persister = experimental_createQueryPersister({
+  storage: AsyncStorage,
+  maxAge: 1000 * 60 * 60 * 12, // 12 hours
+})
+
+const queryClient = useQueryClient()
+
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    ...
+    // Optimistically update to the new value
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+    // And persist it to storage
+    persister.persistQueryByKey(['todos'], queryClient)
+    ...
+  },
+})
+```
+
+### `retrieveQuery<T>(queryHash: string): Promise<T | undefined>`
+
+This function would attempt to retrieve persisted query by `queryHash`.  
+If `query` is `expired`, `busted` or `malformed` it would be removed from the storage instead, and `undefined` would be returned.
+
+### `persisterGc(): Promise<void>`
+
+This function can be used to sporadically clean up stoage from `expired`, `busted` or `malformed` entries.
+
+For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.  
+For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
+
+### `restoreQueries(queryClient: QueryClient, filters): Promise<void>`
+
+This function can be used to restore queries that are currently stored by persister.  
+For 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.
+
+The filter object supports the following properties:
+
+- `queryKey?: QueryKey`
+  - Set this property to define a query key to match on.
+- `exact?: boolean`
+  - 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.
+
+For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.  
+For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
+
 ## API
 
 ### `experimental_createQueryPersister`
@@ -108,16 +166,24 @@ export interface StoragePersisterOptions {
    * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.
    */
   prefix?: string
+  /**
+   * If set to `true`, the query will refetch on successful query restoration if the data is stale.
+   * If set to `false`, the query will not refetch on successful query restoration.
+   * If set to `'always'`, the query will always refetch on successful query restoration.
+   * Defaults to `true`.
+   */
+  refetchOnRestore?: boolean | 'always'
   /**
    * Filters to narrow down which Queries should be persisted.
    */
   filters?: QueryFilters
 }
 
-interface AsyncStorage {
-  getItem: (key: string) => Promise<string | undefined | null>
-  setItem: (key: string, value: string) => Promise<unknown>
-  removeItem: (key: string) => Promise<void>
+interface AsyncStorage<TStorageValue = string> {
+  getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
+  setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
+  removeItem: (key: string) => MaybePromise<void>
+  entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
 }
 ```
 
@@ -129,5 +195,6 @@ The default options are:
   maxAge = 1000 * 60 * 60 * 24,
   serialize = JSON.stringify,
   deserialize = JSON.parse,
+  refetchOnRestore = true,
 }
 ```

packages/query-persist-client-core/src/__tests__/createPersister.test.ts

@@ -260,6 +260,62 @@ describe('createPersister', () => {
     expect(query.fetch).toHaveBeenCalledTimes(1)
   })
 
+  test('should restore item from the storage and refetch when `refetchOnRestore` is set to `always`', async () => {
+    const storage = getFreshStorage()
+    const { context, persister, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+        refetchOnRestore: 'always',
+      },
+    )
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: '',
+        state: { dataUpdatedAt: Date.now() + 1000, data: '' },
+      }),
+    )
+
+    await persister.persisterFn(queryFn, context, query)
+    query.state.isInvalidated = true
+    query.fetch = vi.fn()
+
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(queryFn).toHaveBeenCalledTimes(0)
+    expect(query.fetch).toHaveBeenCalledTimes(1)
+  })
+
+  test('should restore item from the storage and NOT refetch when `refetchOnRestore` is set to false', async () => {
+    const storage = getFreshStorage()
+    const { context, persister, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+        refetchOnRestore: false,
+      },
+    )
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: '',
+        state: { dataUpdatedAt: Date.now(), data: '' },
+      }),
+    )
+
+    await persister.persisterFn(queryFn, context, query)
+    query.state.isInvalidated = true
+    query.fetch = vi.fn()
+
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(queryFn).toHaveBeenCalledTimes(0)
+    expect(query.fetch).toHaveBeenCalledTimes(0)
+  })
+
   test('should store item after successful fetch', async () => {
     const storage = getFreshStorage()
     const {

packages/query-persist-client-core/src/createPersister.ts

@@ -62,6 +62,13 @@ export interface StoragePersisterOptions<TStorageValue = string> {
    * @default 'tanstack-query'
    */
   prefix?: string
+  /**
+   * If set to `true`, the query will refetch on successful query restoration if the data is stale.
+   * If set to `false`, the query will not refetch on successful query restoration.
+   * If set to `'always'`, the query will always refetch on successful query restoration.
+   * Defaults to `true`.
+   */
+  refetchOnRestore?: boolean | 'always'
   /**
    * Filters to narrow down which Queries should be persisted.
    */
@@ -96,6 +103,7 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     StoragePersisterOptions<TStorageValue>
   >['deserialize'],
   prefix = PERSISTER_KEY_PREFIX,
+  refetchOnRestore = true,
   filters,
 }: StoragePersisterOptions<TStorageValue>) {
   function isExpiredOrBusted(persistedQuery: PersistedQuery) {
@@ -204,7 +212,10 @@ export function experimental_createQueryPersister<TStorageValue = string>({
             errorUpdatedAt: persistedQuery.state.errorUpdatedAt,
           })
 
-          if (query.isStale()) {
+          if (
+            refetchOnRestore === 'always' ||
+            (refetchOnRestore === true && query.isStale())
+          ) {
             query.fetch()
           }
         },