feat: add support for React.use()

packages/query-core/src/__tests__/queryObserver.test.tsx

@@ -16,7 +16,13 @@ describe('queryObserver', () => {
   let queryClient: QueryClient
 
   beforeEach(() => {
-    queryClient = createQueryClient()
+    queryClient = createQueryClient({
+      defaultOptions: {
+        queries: {
+          experimental_prefetchInRender: true,
+        },
+      },
+    })
     queryClient.mount()
   })
 
@@ -1133,4 +1139,98 @@ describe('queryObserver', () => {
 
     unsubscribe()
   })
+
+  test('should return a promise that resolves when data is present', async () => {
+    const results: Array<QueryObserverResult> = []
+    const key = queryKey()
+    let count = 0
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: () => {
+        if (++count > 9) {
+          return Promise.resolve('data')
+        }
+        throw new Error('rejected')
+      },
+      retry: 10,
+      retryDelay: 0,
+    })
+    const unsubscribe = observer.subscribe(() => {
+      results.push(observer.getCurrentResult())
+    })
+
+    await waitFor(() => {
+      expect(results.at(-1)?.data).toBe('data')
+    })
+
+    const numberOfUniquePromises = new Set(
+      results.map((result) => result.promise),
+    ).size
+    expect(numberOfUniquePromises).toBe(1)
+
+    unsubscribe()
+  })
+
+  test('should return a new promise after recovering from an error', async () => {
+    const results: Array<QueryObserverResult> = []
+    const key = queryKey()
+
+    let succeeds = false
+    let idx = 0
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: () => {
+        if (succeeds) {
+          return Promise.resolve('data')
+        }
+        throw new Error(`rejected #${++idx}`)
+      },
+      retry: 5,
+      retryDelay: 0,
+    })
+    const unsubscribe = observer.subscribe(() => {
+      results.push(observer.getCurrentResult())
+    })
+
+    await waitFor(() => {
+      expect(results.at(-1)?.status).toBe('error')
+    })
+
+    expect(
+      results.every((result) => result.promise === results[0]!.promise),
+    ).toBe(true)
+
+    {
+      // fail again
+      const lengthBefore = results.length
+      observer.refetch()
+      await waitFor(() => {
+        expect(results.length).toBeGreaterThan(lengthBefore)
+        expect(results.at(-1)?.status).toBe('error')
+      })
+
+      const numberOfUniquePromises = new Set(
+        results.map((result) => result.promise),
+      ).size
+
+      expect(numberOfUniquePromises).toBe(2)
+    }
+    {
+      // succeed
+      succeeds = true
+      observer.refetch()
+
+      await waitFor(() => {
+        results.at(-1)?.status === 'success'
+      })
+
+      const numberOfUniquePromises = new Set(
+        results.map((result) => result.promise),
+      ).size
+
+      expect(numberOfUniquePromises).toBe(3)
+    }
+
+    unsubscribe()
+  })
 })

packages/query-core/src/queryObserver.ts

@@ -1,3 +1,8 @@
+import { focusManager } from './focusManager'
+import { notifyManager } from './notifyManager'
+import { fetchState } from './query'
+import { Subscribable } from './subscribable'
+import { isThenableEqual, pendingThenable } from './thenable'
 import {
   isServer,
   isValidTimeout,
@@ -8,12 +13,9 @@ import {
   shallowEqualObjects,
   timeUntilStale,
 } from './utils'
-import { notifyManager } from './notifyManager'
-import { focusManager } from './focusManager'
-import { Subscribable } from './subscribable'
-import { fetchState } from './query'
 import type { FetchOptions, Query, QueryState } from './query'
 import type { QueryClient } from './queryClient'
+import type { Thenable } from './thenable'
 import type {
   DefaultError,
   DefaultedQueryObserverOptions,
@@ -38,6 +40,10 @@ interface ObserverFetchOptions extends FetchOptions {
   throwOnError?: boolean
 }
 
+const cancellationError = new Error(
+  'No data or error and the query is not fetching - query was most likely cancelled',
+)
+
 export class QueryObserver<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -57,6 +63,7 @@ export class QueryObserver<
     TQueryData,
     TQueryKey
   >
+  #currentThenable: Thenable<TData>
   #selectError: TError | null
   #selectFn?: (data: TQueryData) => TData
   #selectResult?: TData
@@ -82,6 +89,13 @@ export class QueryObserver<
 
     this.#client = client
     this.#selectError = null
+    this.#currentThenable = pendingThenable()
+    if (!this.options.experimental_prefetchInRender) {
+      this.#currentThenable.reject(
+        new Error('experimental_prefetchInRender feature flag is not enabled'),
+      )
+    }
+
     this.bindMethods()
     this.setOptions(options)
   }
@@ -582,6 +596,7 @@ export class QueryObserver<
       isRefetchError: isError && hasData,
       isStale: isStale(query, options),
       refetch: this.refetch,
+      promise: this.#currentThenable,
     }
 
     return result as QueryObserverResult<TData, TError>
@@ -593,6 +608,42 @@ export class QueryObserver<
       | undefined
 
     const nextResult = this.createResult(this.#currentQuery, this.options)
+
+    if (this.options.experimental_prefetchInRender) {
+      const nextThenable = (() => {
+        const thenable = pendingThenable<TData>()
+
+        if (nextResult.status === 'error') {
+          thenable.reject(nextResult.error)
+        } else if (nextResult.data !== undefined) {
+          thenable.resolve(nextResult.data)
+        } else if (!nextResult.isFetching) {
+          thenable.reject(cancellationError)
+        }
+        return thenable as Thenable<TData>
+      })()
+
+      const prevThenable = this.#currentThenable
+
+      switch (prevThenable.status) {
+        case 'pending':
+          if (nextThenable.status === 'fulfilled') {
+            prevThenable.resolve(nextThenable.value)
+          } else if (nextThenable.status === 'rejected') {
+            prevThenable.reject(nextThenable.reason)
+          }
+          break
+
+        case 'fulfilled':
+        case 'rejected':
+          if (!isThenableEqual(prevThenable, nextThenable)) {
+            // Replace the thenable when the results have changed
+            this.#currentThenable = nextResult.promise = nextThenable
+          }
+          break
+      }
+    }
+
     this.#currentResultState = this.#currentQuery.state
     this.#currentResultOptions = this.options
 
@@ -639,6 +690,7 @@ export class QueryObserver<
       return Object.keys(this.#currentResult).some((key) => {
         const typedKey = key as keyof QueryObserverResult
         const changed = this.#currentResult[typedKey] !== prevResult[typedKey]
+
         return changed && includedProps.has(typedKey)
       })
     }

packages/query-core/src/retryer.ts

@@ -1,5 +1,6 @@
 import { focusManager } from './focusManager'
 import { onlineManager } from './onlineManager'
+import { pendingThenable } from './thenable'
 import { isServer, sleep } from './utils'
 import type { CancelOptions, DefaultError, NetworkMode } from './types'
 
@@ -75,13 +76,8 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   let failureCount = 0
   let isResolved = false
   let continueFn: ((value?: unknown) => void) | undefined
-  let promiseResolve: (data: TData) => void
-  let promiseReject: (error: TError) => void
 
-  const promise = new Promise<TData>((outerResolve, outerReject) => {
-    promiseResolve = outerResolve
-    promiseReject = outerReject
-  })
+  const thenable = pendingThenable<TData>()
 
   const cancel = (cancelOptions?: CancelOptions): void => {
     if (!isResolved) {
@@ -110,7 +106,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
       isResolved = true
       config.onSuccess?.(value)
       continueFn?.()
-      promiseResolve(value)
+      thenable.resolve(value)
     }
   }
 
@@ -119,7 +115,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
       isResolved = true
       config.onError?.(value)
       continueFn?.()
-      promiseReject(value)
+      thenable.reject(value)
     }
   }
 
@@ -207,11 +203,11 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   }
 
   return {
-    promise,
+    promise: thenable,
     cancel,
     continue: () => {
       continueFn?.()
-      return promise
+      return thenable
     },
     cancelRetry,
     continueRetry,
@@ -223,7 +219,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
       } else {
         pause().then(run)
       }
-      return promise
+      return thenable
     },
   }
 }

packages/query-core/src/thenable.ts

@@ -0,0 +1,92 @@
+/**
+ * Thenable types which matches React's types for promises
+ *
+ * React seemingly uses `.status`, `.value` and `.reason` properties on a promises to optimistically unwrap data from promises
+ *
+ * @see https://github.com/facebook/react/blob/main/packages/shared/ReactTypes.js#L112-L138
+ * @see https://github.com/facebook/react/blob/4f604941569d2e8947ce1460a0b2997e835f37b9/packages/react-debug-tools/src/ReactDebugHooks.js#L224-L227
+ */
+
+interface Fulfilled<T> {
+  status: 'fulfilled'
+  value: T
+
+  reason?: never
+}
+interface Rejected {
+  status: 'rejected'
+  reason: unknown
+
+  value?: never
+}
+interface Pending<T> {
+  status: 'pending'
+
+  reason?: never
+  value?: never
+  /**
+   * Resolve the promise with a value.
+   * Will remove the `resolve` and `reject` properties from the promise.
+   */
+  resolve: (value: T) => void
+  /**
+   * Reject the promise with a reason.
+   * Will remove the `resolve` and `reject` properties from the promise.
+   */
+  reject: (reason: unknown) => void
+}
+
+export type FulfilledThenable<T> = Promise<T> & Fulfilled<T>
+export type RejectedThenable<T> = Promise<T> & Rejected
+export type PendingThenable<T> = Promise<T> & Pending<T>
+
+export type Thenable<T> =
+  | FulfilledThenable<T>
+  | RejectedThenable<T>
+  | PendingThenable<T>
+
+export function pendingThenable<T>(): PendingThenable<T> {
+  let resolve: Pending<T>['resolve']
+  let reject: Pending<T>['reject']
+  // this could use `Promise.withResolvers()` in the future
+  const thenable = new Promise((_resolve, _reject) => {
+    resolve = _resolve
+    reject = _reject
+  }) as PendingThenable<T>
+
+  thenable.status = 'pending'
+  thenable.catch(() => {
+    // prevent unhandled rejection errors
+  })
+
+  function finalize(data: Fulfilled<T> | Rejected) {
+    Object.assign(thenable, data)
+
+    // clear pending props props to avoid calling them twice
+    delete (thenable as Partial<PendingThenable<T>>).resolve
+    delete (thenable as Partial<PendingThenable<T>>).reject
+  }
+
+  thenable.resolve = (value) => {
+    finalize({
+      status: 'fulfilled',
+      value,
+    })
+
+    resolve(value)
+  }
+  thenable.reject = (reason) => {
+    finalize({
+      status: 'rejected',
+      reason,
+    })
+
+    reject(reason)
+  }
+
+  return thenable
+}
+
+export function isThenableEqual<T>(a: Thenable<T>, b: Thenable<T>): boolean {
+  return a.status === b.status && a.value === b.value && a.reason === b.reason
+}