fix(persistQueryClient): rename isHydrating to isRestoring (#3512)

* fix(devtools): devtools should not import relatively from react-query

* fix(hydration): properly remove unused hydration entry point

hydration moved to the core, and the build entry point was already removed for v4. this is just a proper cleanup.

* fix(persistQueryClient): rename isHydrating to isRestoring

as we currently have no plans to re-use this for useHydrate, it would be confusing to not get true for this value in those cases

* fix(persistQueryClient): document useIsRestoring

* fix: make QueryErrorResetBoundary value stable

we want a constant value for the lifetime of the QueryErrorResetBoundary component; useMemo doesn't guarantee that.

* chore: remove resolutions from package.json

as discussed here: #2688 (comment)

* fix: log message

we don't have a queryKey at this point if a string was used due to how the overloads try to spread things

* Update docs/src/pages/plugins/persistQueryClient.md

Author: TkDodo

docs/src/pages/plugins/persistQueryClient.md

@@ -220,6 +220,10 @@ ReactDOM.createRoot(rootElement).render(
   - will be called when the initial restore is finished
   - can be used to [resumePausedMutations](../reference/QueryClient#queryclientresumepausedmutations)
 
+### useIsRestoring
+
+If you are using the `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid race conditions between the restore and mounting queries.
+
 ## Persisters
 
 ### Persisters Interface

examples/offline/src/App.js

@@ -5,7 +5,7 @@ import {
   QueryClient,
   MutationCache,
   onlineManager,
-  useIsHydrating,
+  useisRestoring,
 } from "react-query";
 import { ReactQueryDevtools } from "react-query/devtools";
 import toast, { Toaster } from "react-hot-toast";
@@ -76,7 +76,7 @@ export default function App() {
 }
 
 function Movies() {
-  const isHydrating = useIsHydrating();
+  const isRestoring = isRestoring();
   return (
     <Router
       location={location}
@@ -93,7 +93,7 @@ function Movies() {
             queryClient.getQueryData(movieKeys.detail(movieId)) ??
             // do not load if we are offline or hydrating because it returns a promise that is pending until we go online again
             // we just let the Detail component handle it
-            (onlineManager.isOnline() && !isHydrating
+            (onlineManager.isOnline() && !isRestoring
               ? queryClient.fetchQuery(movieKeys.detail(movieId), () =>
                   api.fetchMovie(movieId)
                 )

package.json

@@ -147,10 +147,6 @@
     "type-fest": "^0.21.0",
     "typescript": "4.5.3"
   },
-  "resolutions": {
-    "@types/react": "^16.9.41",
-    "@types/react-dom": "^16.9.8"
-  },
   "bundlewatch": {
     "files": [
       {

src/core/query.ts

@@ -366,8 +366,7 @@ export class Query<
     if (!Array.isArray(this.options.queryKey)) {
       if (process.env.NODE_ENV !== 'production') {
         this.logger.error(
-          'As of v4, queryKey needs to be an Array, but the queryKey used was:',
-          JSON.stringify(this.options.queryKey)
+          `As of v4, queryKey needs to be an Array. If you are using a string like 'repoData', please change it to an Array, e.g. ['repoData']`
         )
       }
     }

src/core/queryObserver.ts

@@ -439,7 +439,7 @@ export class QueryObserver<
           status = 'loading'
         }
       }
-      if (options._optimisticResults === 'isHydrating') {
+      if (options._optimisticResults === 'isRestoring') {
         fetchStatus = 'idle'
       }
     }

src/core/types.ts

@@ -231,7 +231,7 @@ export interface QueryObserverOptions<
    */
   placeholderData?: TQueryData | PlaceholderDataFunction<TQueryData>
 
-  _optimisticResults?: 'optimistic' | 'isHydrating'
+  _optimisticResults?: 'optimistic' | 'isRestoring'
 }
 
 type WithRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>

src/devtools/devtools.tsx

@@ -1,10 +1,10 @@
 import React from 'react'
 import { useSyncExternalStore } from 'use-sync-external-store/shim'
-import { notifyManager } from '../core'
 import {
   Query,
   useQueryClient,
   onlineManager,
+  notifyManager,
   QueryCache,
   QueryClient,
   QueryKey as QueryKeyType,

src/devtools/utils.ts

@@ -1,5 +1,5 @@
 import React from 'react'
-import { Query } from '../core'
+import type { Query } from 'react-query'
 
 import { Theme, useTheme } from './theme'
 import useMediaQuery from './useMediaQuery'

src/hydration/index.ts

@@ -2,7 +2,7 @@ import React from 'react'
 
 import { persistQueryClient, PersistQueryClientOptions } from './persist'
 import { QueryClientProvider, QueryClientProviderProps } from '../reactjs'
-import { IsHydratingProvider } from '../reactjs/Hydrate'
+import { IsRestoringProvider } from '../reactjs/isRestoring'
 
 export type PersistQueryClientProviderProps = QueryClientProviderProps & {
   persistOptions: Omit<PersistQueryClientOptions, 'queryClient'>
@@ -16,7 +16,7 @@ export const PersistQueryClientProvider = ({
   onSuccess,
   ...props
 }: PersistQueryClientProviderProps): JSX.Element => {
-  const [isHydrating, setIsHydrating] = React.useState(true)
+  const [isRestoring, setIsRestoring] = React.useState(true)
   const refs = React.useRef({ persistOptions, onSuccess })
 
   React.useEffect(() => {
@@ -25,7 +25,7 @@ export const PersistQueryClientProvider = ({
 
   React.useEffect(() => {
     let isStale = false
-    setIsHydrating(true)
+    setIsRestoring(true)
     const [unsubscribe, promise] = persistQueryClient({
       ...refs.current.persistOptions,
       queryClient: client,
@@ -34,7 +34,7 @@ export const PersistQueryClientProvider = ({
     promise.then(() => {
       if (!isStale) {
         refs.current.onSuccess?.()
-        setIsHydrating(false)
+        setIsRestoring(false)
       }
     })
 
@@ -46,7 +46,7 @@ export const PersistQueryClientProvider = ({
 
   return (
     <QueryClientProvider client={client} {...props}>
-      <IsHydratingProvider value={isHydrating}>{children}</IsHydratingProvider>
+      <IsRestoringProvider value={isRestoring}>{children}</IsRestoringProvider>
     </QueryClientProvider>
   )
 }

src/persistQueryClient/PersistQueryClientProvider.tsx

@@ -3,11 +3,6 @@ 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({ context: options.context })
 

src/reactjs/Hydrate.tsx

@@ -41,7 +41,7 @@ export interface QueryErrorResetBoundaryProps {
 export const QueryErrorResetBoundary = ({
   children,
 }: QueryErrorResetBoundaryProps) => {
-  const value = React.useMemo(() => createValue(), [])
+  const [value] = React.useState(() => createValue())
   return (
     <QueryErrorResetBoundaryContext.Provider value={value}>
       {typeof children === 'function'

src/reactjs/QueryErrorResetBoundary.tsx

@@ -16,7 +16,8 @@ export { useMutation } from './useMutation'
 export { useQuery } from './useQuery'
 export { useQueries } from './useQueries'
 export { useInfiniteQuery } from './useInfiniteQuery'
-export { useHydrate, Hydrate, useIsHydrating } from './Hydrate'
+export { useHydrate, Hydrate } from './Hydrate'
+export { useIsRestoring } from './isRestoring'
 
 // Types
 export * from './types'

src/reactjs/index.ts

@@ -0,0 +1,6 @@
+import React from 'react'
+
+const IsRestoringContext = React.createContext(false)
+
+export const useIsRestoring = () => React.useContext(IsRestoringContext)
+export const IsRestoringProvider = IsRestoringContext.Provider

src/reactjs/isRestoring.tsx

@@ -6,7 +6,7 @@ import { useQueryErrorResetBoundary } from './QueryErrorResetBoundary'
 import { useQueryClient } from './QueryClientProvider'
 import { UseBaseQueryOptions } from './types'
 import { shouldThrowError } from './utils'
-import { useIsHydrating } from './Hydrate'
+import { useIsRestoring } from './isRestoring'
 
 export function useBaseQuery<
   TQueryFnData,
@@ -25,13 +25,13 @@ export function useBaseQuery<
   Observer: typeof QueryObserver
 ) {
   const queryClient = useQueryClient({ context: options.context })
-  const isHydrating = useIsHydrating()
+  const isRestoring = useIsRestoring()
   const errorResetBoundary = useQueryErrorResetBoundary()
   const defaultedOptions = queryClient.defaultQueryOptions(options)
 
   // Make sure results are optimistically set in fetching state before subscribing or updating options
-  defaultedOptions._optimisticResults = isHydrating
-    ? 'isHydrating'
+  defaultedOptions._optimisticResults = isRestoring
+    ? 'isRestoring'
     : 'optimistic'
 
   // Include callbacks in batch renders
@@ -81,10 +81,10 @@ export function useBaseQuery<
   useSyncExternalStore(
     React.useCallback(
       onStoreChange =>
-        isHydrating
+        isRestoring
           ? () => undefined
           : observer.subscribe(notifyManager.batchCalls(onStoreChange)),
-      [observer, isHydrating]
+      [observer, isRestoring]
     ),
     () => observer.getCurrentResult(),
     () => observer.getCurrentResult()
@@ -105,7 +105,7 @@ export function useBaseQuery<
     defaultedOptions.suspense &&
     result.isLoading &&
     result.isFetching &&
-    !isHydrating
+    !isRestoring
   ) {
     throw observer
       .fetchOptimistic(defaultedOptions)

src/reactjs/useBaseQuery.ts

@@ -6,7 +6,7 @@ import { notifyManager } from '../core/notifyManager'
 import { QueriesObserver } from '../core/queriesObserver'
 import { useQueryClient } from './QueryClientProvider'
 import { UseQueryOptions, UseQueryResult } from './types'
-import { useIsHydrating } from './Hydrate'
+import { useIsRestoring } from './isRestoring'
 
 // This defines the `UseQueryOptions` that are accepted in `QueriesOptions` & `GetOptions`.
 // - `context` is omitted as it is passed as a root-level option to `useQueries` instead.
@@ -144,21 +144,21 @@ export function useQueries<T extends any[]>({
   context?: UseQueryOptions['context']
 }): QueriesResults<T> {
   const queryClient = useQueryClient({ context })
-  const isHydrating = useIsHydrating()
+  const isRestoring = useIsRestoring()
 
   const defaultedQueries = React.useMemo(
     () =>
       queries.map(options => {
         const defaultedOptions = queryClient.defaultQueryOptions(options)
 
         // Make sure the results are already in fetching state before subscribing or updating options
-        defaultedOptions._optimisticResults = isHydrating
-          ? 'isHydrating'
+        defaultedOptions._optimisticResults = isRestoring
+          ? 'isRestoring'
           : 'optimistic'
 
         return defaultedOptions
       }),
-    [queries, queryClient, isHydrating]
+    [queries, queryClient, isRestoring]
   )
 
   const [observer] = React.useState(
@@ -170,10 +170,10 @@ export function useQueries<T extends any[]>({
   useSyncExternalStore(
     React.useCallback(
       onStoreChange =>
-        isHydrating
+        isRestoring
           ? () => undefined
           : observer.subscribe(notifyManager.batchCalls(onStoreChange)),
-      [observer, isHydrating]
+      [observer, isRestoring]
     ),
     () => observer.getCurrentResult(),
     () => observer.getCurrentResult()