feat(query-core): default networkMode to 'offlineFirst' when persisters are present (#6046)

* feat(query-core): default networkMode to 'offlineFirst' when persisters are present

* chore: stabilize test

* test: remove flaky test

Author: TkDodo

docs/react/plugins/createPersister.md

@@ -36,6 +36,8 @@ yarn add @tanstack/query-persist-client-core
 
 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.
 
+Garbage 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.
+
 ```tsx
 import AsyncStorage from '@react-native-async-storage/async-storage'
 import { QueryClient } from '@tanstack/react-query'
@@ -44,15 +46,20 @@ import { experimental_createPersister } from '@tanstack/query-persist-client-cor
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
-      gcTime: 1000 * 60 * 60 * 24, // 24 hours
+      gcTime: 1000 * 30, // 30 seconds
       persister: experimental_createPersister({
         storage: AsyncStorage,
+        maxAge: 1000 * 60 * 60 * 12 // 12 hours
       }),
     },
   },
 })
 ```
 
+### Adapted defaults
+
+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.
+
 ## API
 
 ### `experimental_createPersister`
@@ -88,6 +95,7 @@ export interface StoragePersisterOptions {
    * The max-allowed age of the cache in milliseconds.
    * If a persisted cache is found that is older than this
    * time, it will be discarded
+   * @default 24 hours
    */
   maxAge?: number
   /**

packages/query-core/src/queryClient.ts

@@ -489,6 +489,13 @@ export class QueryClient {
       defaultedOptions.throwOnError = !!defaultedOptions.suspense
     }
 
+    if (
+      typeof defaultedOptions.networkMode === 'undefined' &&
+      defaultedOptions.persister
+    ) {
+      defaultedOptions.networkMode = 'offlineFirst'
+    }
+
     return defaultedOptions as DefaultedQueryObserverOptions<
       TQueryFnData,
       TError,

packages/query-core/src/tests/queryClient.test.tsx

@@ -150,6 +150,45 @@ describe('queryClient', () => {
     })
   })
 
+  describe('defaultQueryOptions', () => {
+    test('should default networkMode when persister is present', async () => {
+      expect(
+        createQueryClient({
+          defaultOptions: {
+            queries: {
+              persister: 'ignore' as any,
+            },
+          },
+        }).defaultQueryOptions({ queryKey: queryKey() }).networkMode,
+      ).toBe('offlineFirst')
+    })
+
+    test('should not default networkMode without persister', async () => {
+      expect(
+        createQueryClient({
+          defaultOptions: {
+            queries: {
+              staleTime: 1000,
+            },
+          },
+        }).defaultQueryOptions({ queryKey: queryKey() }).networkMode,
+      ).toBe(undefined)
+    })
+
+    test('should not default networkMode when already present', async () => {
+      expect(
+        createQueryClient({
+          defaultOptions: {
+            queries: {
+              persister: 'ignore' as any,
+              networkMode: 'always',
+            },
+          },
+        }).defaultQueryOptions({ queryKey: queryKey() }).networkMode,
+      ).toBe('always')
+    })
+  })
+
   describe('setQueryData', () => {
     test('should not crash if query could not be found', () => {
       const key = queryKey()

packages/react-query/src/__tests__/useQuery.test.tsx

@@ -1154,7 +1154,6 @@ describe('useQuery', () => {
 
   it('should update query stale state and refetch when invalidated with invalidateQueries', async () => {
     const key = queryKey()
-    const states: Array<UseQueryResult<number>> = []
     let count = 0
 
     function Page() {
@@ -1166,59 +1165,33 @@ describe('useQuery', () => {
           return count
         },
         staleTime: Infinity,
-        notifyOnChangeProps: 'all',
       })
 
-      states.push(state)
-
       return (
         <div>
           <button
             onClick={() => queryClient.invalidateQueries({ queryKey: key })}
           >
             invalidate
           </button>
-          data: {state.data}
+          data: {state.data}, isStale: {String(state.isStale)}, isFetching:{' '}
+          {String(state.isFetching)}
         </div>
       )
     }
 
     const rendered = renderWithClient(queryClient, <Page />)
 
-    await waitFor(() => rendered.getByText('data: 1'))
+    await waitFor(() =>
+      rendered.getByText('data: 1, isStale: false, isFetching: false'),
+    )
     fireEvent.click(rendered.getByRole('button', { name: /invalidate/i }))
-    await waitFor(() => rendered.getByText('data: 2'))
-
-    await waitFor(() => expect(states.length).toBe(4))
-
-    expect(states[0]).toMatchObject({
-      data: undefined,
-      isFetching: true,
-      isRefetching: false,
-      isSuccess: false,
-      isStale: true,
-    })
-    expect(states[1]).toMatchObject({
-      data: 1,
-      isFetching: false,
-      isRefetching: false,
-      isSuccess: true,
-      isStale: false,
-    })
-    expect(states[2]).toMatchObject({
-      data: 1,
-      isFetching: true,
-      isRefetching: true,
-      isSuccess: true,
-      isStale: true,
-    })
-    expect(states[3]).toMatchObject({
-      data: 2,
-      isFetching: false,
-      isRefetching: false,
-      isSuccess: true,
-      isStale: false,
-    })
+    await waitFor(() =>
+      rendered.getByText('data: 1, isStale: true, isFetching: true'),
+    )
+    await waitFor(() =>
+      rendered.getByText('data: 2, isStale: false, isFetching: false'),
+    )
   })
 
   it('should not update disabled query when refetched with refetchQueries', async () => {

packages/solid-query/src/__tests__/createQuery.test.tsx

@@ -1511,98 +1511,6 @@ describe('createQuery', () => {
     })
   })
 
-  it('should keep the previous data on disabled query when placeholderData is set to identity function', async () => {
-    const key = queryKey()
-    const states: Array<CreateQueryResult<number>> = []
-
-    function Page() {
-      const [count, setCount] = createSignal(0)
-
-      const state = createQuery(() => ({
-        queryKey: [key, count()],
-        queryFn: async () => {
-          await sleep(10)
-          return count()
-        },
-        enabled: false,
-        placeholderData: keepPreviousData,
-        notifyOnChangeProps: 'all',
-      }))
-
-      createRenderEffect(() => {
-        states.push({ ...state })
-      })
-
-      createEffect(() => {
-        const refetch = state.refetch
-        refetch()
-
-        setActTimeout(() => {
-          setCount(1)
-        }, 20)
-
-        setActTimeout(() => {
-          refetch()
-        }, 30)
-      })
-
-      return null
-    }
-
-    render(() => (
-      <QueryClientProvider client={queryClient}>
-        <Page />
-      </QueryClientProvider>
-    ))
-
-    await sleep(100)
-
-    expect(states.length).toBe(6)
-
-    // Disabled query
-    expect(states[0]).toMatchObject({
-      data: undefined,
-      isFetching: false,
-      isSuccess: false,
-      isPlaceholderData: false,
-    })
-    // Fetching query
-    expect(states[1]).toMatchObject({
-      data: undefined,
-      isFetching: true,
-      isSuccess: false,
-      isPlaceholderData: false,
-    })
-    // Fetched query
-    expect(states[2]).toMatchObject({
-      data: 0,
-      isFetching: false,
-      isSuccess: true,
-      isPlaceholderData: false,
-    })
-    // Set state
-    expect(states[3]).toMatchObject({
-      data: 0,
-      isFetching: false,
-      isSuccess: true,
-      isPlaceholderData: true,
-    })
-    // Fetching new query
-    expect(states[4]).toMatchObject({
-      data: 0,
-      isFetching: true,
-      isSuccess: true,
-      isPlaceholderData: true,
-    })
-    // Fetched new query
-    expect(states[5]).toMatchObject({
-      data: 1,
-      isFetching: false,
-      isSuccess: true,
-      isPlaceholderData: false,
-    })
-  })
-
   it('should keep the previous data on disabled query when placeholderData is set and switching query key multiple times', async () => {
     const key = queryKey()
     const states: Array<CreateQueryResult<number>> = []