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_promise: 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

@@ -12,6 +12,8 @@ import { notifyManager } from './notifyManager'
 import { focusManager } from './focusManager'
 import { Subscribable } from './subscribable'
 import { fetchState } from './query'
+import { pendingThenable } from './thenable'
+import type { PendingThenable, Thenable } from './thenable'
 import type { FetchOptions, Query, QueryState } from './query'
 import type { QueryClient } from './queryClient'
 import type {
@@ -57,6 +59,7 @@ export class QueryObserver<
     TQueryData,
     TQueryKey
   >
+  #currentThenable: Thenable<TData>
   #selectError: TError | null
   #selectFn?: (data: TQueryData) => TData
   #selectResult?: TData
@@ -82,6 +85,13 @@ export class QueryObserver<
 
     this.#client = client
     this.#selectError = null
+    this.#currentThenable = pendingThenable()
+    if (!this.options.experimental_promise) {
+      this.#currentThenable.reject(
+        new Error('experimental_promise feature flag is not enabled'),
+      )
+    }
+
     this.bindMethods()
     this.setOptions(options)
   }
@@ -582,6 +592,7 @@ export class QueryObserver<
       isRefetchError: isError && hasData,
       isStale: isStale(query, options),
       refetch: this.refetch,
+      promise: this.#currentThenable,
     }
 
     return result as QueryObserverResult<TData, TError>
@@ -591,8 +602,54 @@ export class QueryObserver<
     const prevResult = this.#currentResult as
       | QueryObserverResult<TData, TError>
       | undefined
+    const prevThenable = this.#currentThenable
 
     const nextResult = this.createResult(this.#currentQuery, this.options)
+
+    if (this.options.experimental_promise) {
+      const finalizeThenableIfPossible = (thenable: PendingThenable<TData>) => {
+        if (nextResult.status === 'error') {
+          thenable.reject(nextResult.error)
+        } else if (nextResult.data !== undefined) {
+          thenable.resolve(nextResult.data)
+        }
+      }
+
+      /**
+       * Create a new thenable and result promise when the results have changed
+       */
+      const recreateThenable = () => {
+        const pending =
+          (this.#currentThenable =
+          nextResult.promise =
+            pendingThenable())
+
+        finalizeThenableIfPossible(pending)
+      }
+      switch (prevThenable.status) {
+        case 'pending':
+          finalizeThenableIfPossible(prevThenable)
+          break
+        case 'fulfilled': {
+          if (
+            nextResult.data !== prevThenable.value ||
+            nextResult.status === 'error'
+          ) {
+            recreateThenable()
+          }
+          break
+        }
+        case 'rejected': {
+          if (
+            nextResult.status !== 'error' ||
+            nextResult.error !== prevThenable.reason
+          ) {
+            recreateThenable()
+          }
+          break
+        }
+      }
+    }
     this.#currentResultState = this.#currentQuery.state
     this.#currentResultOptions = this.options
 

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,82 @@
+/**
+ * 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
+}
+interface Rejected {
+  status: 'rejected'
+  reason: unknown
+}
+interface Pending<T> {
+  status: 'pending'
+
+  /**
+   * 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
+}