fix(hydration): fix promise hydration bugs

* Include dehydratedAt and ignore hydrating old promises
  * This is an approximation of dataUpdatedAt, but is not perfect
* Refactor checks for if we should hydrate promises or not to fix infinite loop bug on failed queries
* Hydrate already resolved promises synchronously

Author: Ephem

packages/query-core/src/hydration.ts

@@ -1,3 +1,4 @@
+import { tryResolveSync } from './thenable'
 import type {
   DefaultError,
   MutationKey,
@@ -46,6 +47,10 @@ interface DehydratedQuery {
   state: QueryState
   promise?: Promise<unknown>
   meta?: QueryMeta
+  // This is only optional because older versions of Query might have dehydrated
+  // without it which we need to handle for backwards compatibility.
+  // This should be changed to required in the future.
+  dehydratedAt?: number
 }
 
 export interface DehydratedState {
@@ -74,6 +79,7 @@ function dehydrateQuery(
   shouldRedactErrors: (error: unknown) => boolean,
 ): DehydratedQuery {
   return {
+    dehydratedAt: Date.now(),
     state: {
       ...query.state,
       ...(query.state.data !== undefined && {
@@ -189,52 +195,73 @@ export function hydrate(
     )
   })
 
-  queries.forEach(({ queryKey, state, queryHash, meta, promise }) => {
-    let query = queryCache.get(queryHash)
-
-    const data =
-      state.data === undefined ? state.data : deserializeData(state.data)
-
-    // Do not hydrate if an existing query exists with newer data
-    if (query) {
-      if (query.state.dataUpdatedAt < state.dataUpdatedAt) {
-        // omit fetchStatus from dehydrated state
-        // so that query stays in its current fetchStatus
-        const { fetchStatus: _ignored, ...serializedState } = state
-        query.setState({
-          ...serializedState,
-          data,
+  queries.forEach(
+    ({ queryKey, state, queryHash, meta, promise, dehydratedAt }) => {
+      const syncData = promise ? tryResolveSync(promise) : undefined
+      const rawData = state.data === undefined ? syncData?.data : state.data
+      const data = rawData === undefined ? rawData : deserializeData(rawData)
+
+      let query = queryCache.get(queryHash)
+      const existingQueryIsPending = query?.state.status === 'pending'
+
+      // Do not hydrate if an existing query exists with newer data
+      if (query) {
+        const hasNewerSyncData =
+          syncData &&
+          // We only need this undefined check to handle older dehydration
+          // payloads that might not have dehydratedAt
+          dehydratedAt !== undefined &&
+          dehydratedAt > query.state.dataUpdatedAt
+        if (
+          state.dataUpdatedAt > query.state.dataUpdatedAt ||
+          hasNewerSyncData
+        ) {
+          // omit fetchStatus from dehydrated state
+          // so that query stays in its current fetchStatus
+          const { fetchStatus: _ignored, ...serializedState } = state
+          query.setState({
+            ...serializedState,
+            data,
+          })
+        }
+      } else {
+        // Restore query
+        query = queryCache.build(
+          client,
+          {
+            ...client.getDefaultOptions().hydrate?.queries,
+            ...options?.defaultOptions?.queries,
+            queryKey,
+            queryHash,
+            meta,
+          },
+          // Reset fetch status to idle to avoid
+          // query being stuck in fetching state upon hydration
+          {
+            ...state,
+            data,
+            fetchStatus: 'idle',
+            status: data !== undefined ? 'success' : state.status,
+          },
+        )
+      }
+
+      if (
+        promise &&
+        !existingQueryIsPending &&
+        // Only hydrate promise if no synchronous data was available to hydrate
+        !data &&
+        // Only hydrate if dehydration is newer than any existing data
+        dehydratedAt !== undefined &&
+        dehydratedAt > query.state.dataUpdatedAt
+      ) {
+        // this doesn't actually fetch - it just creates a retryer
+        // which will re-use the passed `initialPromise`
+        void query.fetch(undefined, {
+          // RSC transformed promises are not thenable
+          initialPromise: Promise.resolve(promise).then(deserializeData),
         })
       }
-    } else {
-      // Restore query
-      query = queryCache.build(
-        client,
-        {
-          ...client.getDefaultOptions().hydrate?.queries,
-          ...options?.defaultOptions?.queries,
-          queryKey,
-          queryHash,
-          meta,
-        },
-        // Reset fetch status to idle to avoid
-        // query being stuck in fetching state upon hydration
-        {
-          ...state,
-          data,
-          fetchStatus: 'idle',
-        },
-      )
-    }
-
-    if (promise) {
-      // Note: `Promise.resolve` required cause
-      // RSC transformed promises are not thenable
-      const initialPromise = Promise.resolve(promise).then(deserializeData)
-
-      // this doesn't actually fetch - it just creates a retryer
-      // which will re-use the passed `initialPromise`
-      void query.fetch(undefined, { initialPromise })
-    }
-  })
+    },
+  )
 }

packages/query-core/src/thenable.ts

@@ -80,3 +80,30 @@ export function pendingThenable<T>(): PendingThenable<T> {
 
   return thenable
 }
+
+/**
+ * This function takes a Promise-like input and detects whether the data
+ * is synchronously available or not.
+ *
+ * It does not inspect .status, .value or .reason properties of the promise,
+ * as those are not always available, and the .status of React's promises
+ * should not be considered part of the public API.
+ */
+export function tryResolveSync(promise: Promise<unknown> | Thenable<unknown>) {
+  let data: unknown
+
+  promise
+    .then((result) => {
+      data = result
+      return result
+    })
+    // This can be unavailable on certain kinds of thenable's
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    ?.catch(() => {})
+
+  if (data !== undefined) {
+    return { data }
+  }
+
+  return undefined
+}

packages/react-query/src/HydrationBoundary.tsx

@@ -24,13 +24,6 @@ export interface HydrationBoundaryProps {
   queryClient?: QueryClient
 }
 
-const hasProperty = <TKey extends string>(
-  obj: unknown,
-  key: TKey,
-): obj is { [k in TKey]: unknown } => {
-  return typeof obj === 'object' && obj !== null && key in obj
-}
-
 export const HydrationBoundary = ({
   children,
   options = {},
@@ -80,10 +73,11 @@ export const HydrationBoundary = ({
         } else {
           const hydrationIsNewer =
             dehydratedQuery.state.dataUpdatedAt >
-              existingQuery.state.dataUpdatedAt || // RSC special serialized then-able chunks
-            (hasProperty(dehydratedQuery.promise, 'status') &&
-              hasProperty(existingQuery.promise, 'status') &&
-              dehydratedQuery.promise.status !== existingQuery.promise.status)
+              existingQuery.state.dataUpdatedAt ||
+            (dehydratedQuery.promise &&
+              existingQuery.state.status !== 'pending' &&
+              dehydratedQuery.dehydratedAt !== undefined &&
+              dehydratedQuery.dehydratedAt > existingQuery.state.dataUpdatedAt)
 
           const queryAlreadyQueued = hydrationQueue?.find(
             (query) => query.queryHash === dehydratedQuery.queryHash,
@@ -116,6 +110,7 @@ export const HydrationBoundary = ({
   React.useEffect(() => {
     if (hydrationQueue) {
       hydrate(client, { queries: hydrationQueue }, optionsRef.current)
+      // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
       setHydrationQueue(undefined)
     }
   }, [client, hydrationQueue])