feat(persistQueryClient): PersistQueryClientProvider

defer subscription if we are hydrating

Author: TkDodo

src/core/queryObserver.ts

@@ -440,7 +440,7 @@ export class QueryObserver<
     let data: TData | undefined
 
     // Optimistically set result in fetching state if needed
-    if (options.optimisticResults) {
+    if (options._optimisticResults) {
       const mounted = this.hasListeners()
 
       const fetchOnMount = !mounted && shouldFetchOnMount(query, options)
@@ -456,6 +456,9 @@ export class QueryObserver<
           status = 'loading'
         }
       }
+      if (options._optimisticResults === 'isHydrating') {
+        fetchStatus = 'paused'
+      }
     }
 
     // Keep previous data if needed

src/core/types.ts

@@ -202,12 +202,8 @@ export interface QueryObserverOptions<
    * If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided.
    */
   placeholderData?: TQueryData | PlaceholderDataFunction<TQueryData>
-  /**
-   * If set, the observer will optimistically set the result in fetching state before the query has actually started fetching.
-   * This is to make sure the results are not lagging behind.
-   * Defaults to `true`.
-   */
-  optimisticResults?: boolean
+
+  _optimisticResults?: 'optimistic' | 'isHydrating'
 }
 
 type WithRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>

src/persistQueryClient/PersistQueryClientProvider.tsx

@@ -1,22 +1,24 @@
 import React from 'react'
 
 import { persistQueryClient, PersistQueryClientOptions } from './persist'
-import { QueryClientProvider, QueryClientProviderProps } from '../reactjs'
+import {
+  QueryClientProvider,
+  QueryClientProviderProps,
+  IsHydratingProvider,
+} from '../reactjs'
 
 export interface PersistQueryClientProviderProps
   extends QueryClientProviderProps {
   persistOptions: Omit<PersistQueryClientOptions, 'queryClient'>
-  loading?: React.ReactNode
 }
 
 export const PersistQueryClientProvider = ({
   client,
-  loading,
   children,
   persistOptions,
   ...props
 }: PersistQueryClientProviderProps): JSX.Element => {
-  const [initialized, setInitialized] = React.useState(false)
+  const [isHydrating, setIsHydrating] = React.useState(true)
   const options = React.useRef(persistOptions)
   React.useEffect(() => {
     let unsubscribe: (() => void) | undefined
@@ -26,21 +28,17 @@ export const PersistQueryClientProvider = ({
         ...options.current,
         queryClient: client,
       })
-      setInitialized(true)
+      setIsHydrating(false)
     }
 
     void run()
 
     return unsubscribe
   }, [client])
 
-  if (!initialized) {
-    return <>{loading}</>
-  }
-
   return (
     <QueryClientProvider client={client} {...props}>
-      {children}
+      <IsHydratingProvider value={isHydrating}>{children}</IsHydratingProvider>
     </QueryClientProvider>
   )
 }

src/persistQueryClient/tests/PersistQueryClientProvider.test.tsx

@@ -29,25 +29,95 @@ describe('PersistQueryClientProvider', () => {
     const states: UseQueryResult<string>[] = []
 
     const queryClient = new QueryClient()
-    await queryClient.prefetchQuery(key, () => Promise.resolve('prefetched'))
+    await queryClient.prefetchQuery(key, () => Promise.resolve('hydrated'))
 
     const persister = createMockPersister()
 
     await persistQueryClientSave({ queryClient, persister })
 
     queryClient.clear()
 
-    const initialData = jest.fn().mockReturnValue('initial')
+    function Page() {
+      const state = useQuery(key, async () => {
+        await sleep(10)
+        return 'fetched'
+      })
+
+      states.push(state)
+
+      return (
+        <div>
+          <h1>{state.data}</h1>
+          <h2>fetchStatus: {state.fetchStatus}</h2>
+        </div>
+      )
+    }
+
+    const rendered = render(
+      <PersistQueryClientProvider
+        client={queryClient}
+        persistOptions={{ persister }}
+      >
+        <Page />
+      </PersistQueryClientProvider>
+    )
+
+    await waitFor(() => rendered.getByText('fetchStatus: paused'))
+    await waitFor(() => rendered.getByText('hydrated'))
+    await waitFor(() => rendered.getByText('fetched'))
+
+    expect(states).toHaveLength(4)
+
+    expect(states[0]).toMatchObject({
+      status: 'loading',
+      fetchStatus: 'paused',
+      data: undefined,
+    })
+
+    expect(states[1]).toMatchObject({
+      status: 'success',
+      fetchStatus: 'fetching',
+      data: 'hydrated',
+    })
+
+    expect(states[2]).toMatchObject({
+      status: 'success',
+      fetchStatus: 'fetching',
+      data: 'hydrated',
+    })
+
+    expect(states[3]).toMatchObject({
+      status: 'success',
+      fetchStatus: 'idle',
+      data: 'fetched',
+    })
+  })
+
+  test('should show initialData while restoring', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<string>[] = []
+
+    const queryClient = new QueryClient()
+    await queryClient.prefetchQuery(key, () => Promise.resolve('hydrated'))
+
+    const persister = createMockPersister()
+
+    await persistQueryClientSave({ queryClient, persister })
+
+    queryClient.clear()
 
     function Page() {
       const state = useQuery(
         key,
         async () => {
           await sleep(10)
-          return 'test'
+          return 'fetched'
         },
         {
-          initialData,
+          initialData: 'initial',
+          // make sure that initial data is older than the hydration data
+          // otherwise initialData would be newer and takes precedence
+          initialDataUpdatedAt: 1,
         }
       )
 
@@ -56,6 +126,7 @@ describe('PersistQueryClientProvider', () => {
       return (
         <div>
           <h1>{state.data}</h1>
+          <h2>fetchStatus: {state.fetchStatus}</h2>
         </div>
       )
     }
@@ -64,38 +135,48 @@ describe('PersistQueryClientProvider', () => {
       <PersistQueryClientProvider
         client={queryClient}
         persistOptions={{ persister }}
-        loading="loading"
       >
         <Page />
       </PersistQueryClientProvider>
     )
 
-    await waitFor(() => rendered.getByText('loading'))
-    await waitFor(() => rendered.getByText('prefetched'))
-    await waitFor(() => rendered.getByText('test'))
+    await waitFor(() => rendered.getByText('initial'))
+    await waitFor(() => rendered.getByText('hydrated'))
+    await waitFor(() => rendered.getByText('fetched'))
 
-    expect(states).toHaveLength(2)
+    expect(states).toHaveLength(4)
 
     expect(states[0]).toMatchObject({
       status: 'success',
-      isFetching: true,
-      data: 'prefetched',
+      fetchStatus: 'paused',
+      data: 'initial',
     })
 
     expect(states[1]).toMatchObject({
       status: 'success',
-      isFetching: false,
-      data: 'test',
+      fetchStatus: 'fetching',
+      data: 'hydrated',
     })
 
-    expect(initialData).toHaveBeenCalledTimes(0)
+    expect(states[2]).toMatchObject({
+      status: 'success',
+      fetchStatus: 'fetching',
+      data: 'hydrated',
+    })
+
+    expect(states[3]).toMatchObject({
+      status: 'success',
+      fetchStatus: 'idle',
+      data: 'fetched',
+    })
   })
+
   test('should not refetch after restoring when data is fresh', async () => {
     const key = queryKey()
     const states: UseQueryResult<string>[] = []
 
     const queryClient = new QueryClient()
-    await queryClient.prefetchQuery(key, () => Promise.resolve('prefetched'))
+    await queryClient.prefetchQuery(key, () => Promise.resolve('hydrated'))
 
     const persister = createMockPersister()
 
@@ -108,7 +189,7 @@ describe('PersistQueryClientProvider', () => {
         key,
         async () => {
           await sleep(10)
-          return 'test'
+          return 'fetched'
         },
         {
           staleTime: Infinity,
@@ -120,6 +201,7 @@ describe('PersistQueryClientProvider', () => {
       return (
         <div>
           <h1>{state.data}</h1>
+          <h2>fetchStatus: {state.fetchStatus}</h2>
         </div>
       )
     }
@@ -128,21 +210,32 @@ describe('PersistQueryClientProvider', () => {
       <PersistQueryClientProvider
         client={queryClient}
         persistOptions={{ persister }}
-        loading="loading"
       >
         <Page />
       </PersistQueryClientProvider>
     )
 
-    await waitFor(() => rendered.getByText('loading'))
-    await waitFor(() => rendered.getByText('prefetched'))
+    await waitFor(() => rendered.getByText('fetchStatus: paused'))
+    await waitFor(() => rendered.getByText('fetchStatus: idle'))
 
-    expect(states).toHaveLength(1)
+    expect(states).toHaveLength(3)
 
     expect(states[0]).toMatchObject({
+      status: 'loading',
+      fetchStatus: 'paused',
+      data: undefined,
+    })
+
+    expect(states[1]).toMatchObject({
+      status: 'success',
+      fetchStatus: 'idle',
+      data: 'hydrated',
+    })
+
+    expect(states[2]).toMatchObject({
       status: 'success',
-      isFetching: false,
-      data: 'prefetched',
+      fetchStatus: 'idle',
+      data: 'hydrated',
     })
   })
 })

src/reactjs/Hydrate.tsx

@@ -3,6 +3,11 @@ import React from 'react'
 import { hydrate, HydrateOptions } from '../core'
 import { useQueryClient } from './QueryClientProvider'
 
+const IsHydratingContext = React.createContext(false)
+
+export const useIsHydrating = () => React.useContext(IsHydratingContext)
+export const IsHydratingProvider = IsHydratingContext.Provider
+
 export function useHydrate(state: unknown, options?: HydrateOptions) {
   const queryClient = useQueryClient()
 

src/reactjs/index.ts

@@ -13,7 +13,12 @@ export { useMutation } from './useMutation'
 export { useQuery } from './useQuery'
 export { useQueries } from './useQueries'
 export { useInfiniteQuery } from './useInfiniteQuery'
-export { useHydrate, Hydrate } from './Hydrate'
+export {
+  useHydrate,
+  Hydrate,
+  IsHydratingProvider,
+  useIsHydrating,
+} from './Hydrate'
 
 // Types
 export * from './types'