@tanstack/query-core 5.56.2 → 5.59.4

package/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()
+  })
 })

package/src/queriesObserver.ts

@@ -38,6 +38,7 @@ export class QueriesObserver<
   #client: QueryClient
   #result!: Array<QueryObserverResult>
   #queries: Array<QueryObserverOptions>
+  #options?: QueriesObserverOptions<TCombinedResult>
   #observers: Array<QueryObserver>
   #combinedResult?: TCombinedResult
   #lastCombine?: CombineFn<TCombinedResult>
@@ -46,11 +47,12 @@ export class QueriesObserver<
   constructor(
     client: QueryClient,
     queries: Array<QueryObserverOptions<any, any, any, any, any>>,
-    _options?: QueriesObserverOptions<TCombinedResult>,
+    options?: QueriesObserverOptions<TCombinedResult>,
   ) {
     super()
 
     this.#client = client
+    this.#options = options
     this.#queries = []
     this.#observers = []
     this.#result = []
@@ -83,10 +85,11 @@ export class QueriesObserver<
 
   setQueries(
     queries: Array<QueryObserverOptions>,
-    _options?: QueriesObserverOptions<TCombinedResult>,
+    options?: QueriesObserverOptions<TCombinedResult>,
     notifyOptions?: NotifyOptions,
   ): void {
     this.#queries = queries
+    this.#options = options
 
     notifyManager.batch(() => {
       const prevObservers = this.#observers
@@ -268,11 +271,21 @@ export class QueriesObserver<
   }
 
   #notify(): void {
-    notifyManager.batch(() => {
-      this.listeners.forEach((listener) => {
-        listener(this.#result)
-      })
-    })
+    if (this.hasListeners()) {
+      const previousResult = this.#combinedResult
+      const newResult = this.#combineResult(
+        this.#result,
+        this.#options?.combine,
+      )
+
+      if (previousResult !== newResult) {
+        notifyManager.batch(() => {
+          this.listeners.forEach((listener) => {
+            listener(this.#result)
+          })
+        })
+      }
+    }
   }
 }
 

package/src/queryObserver.ts

@@ -1,3 +1,8 @@
+import { focusManager } from './focusManager'
+import { notifyManager } from './notifyManager'
+import { fetchState } from './query'
+import { Subscribable } from './subscribable'
+import { 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 { PendingThenable, Thenable } from './thenable'
 import type {
   DefaultError,
   DefaultedQueryObserverOptions,
@@ -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_prefetchInRender) {
+      this.#currentThenable.reject(
+        new Error('experimental_prefetchInRender 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>
@@ -593,6 +604,7 @@ export class QueryObserver<
       | undefined
 
     const nextResult = this.createResult(this.#currentQuery, this.options)
+
     this.#currentResultState = this.#currentQuery.state
     this.#currentResultOptions = this.options
 
@@ -605,6 +617,52 @@ export class QueryObserver<
       return
     }
 
+    if (this.options.experimental_prefetchInRender) {
+      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)
+      }
+
+      const prevThenable = this.#currentThenable
+      switch (prevThenable.status) {
+        case 'pending':
+          // Finalize the previous thenable if it was pending
+          finalizeThenableIfPossible(prevThenable)
+          break
+        case 'fulfilled':
+          if (
+            nextResult.status === 'error' ||
+            nextResult.data !== prevThenable.value
+          ) {
+            recreateThenable()
+          }
+          break
+        case 'rejected':
+          if (
+            nextResult.status !== 'error' ||
+            nextResult.error !== prevThenable.reason
+          ) {
+            recreateThenable()
+          }
+          break
+      }
+    }
+
     this.#currentResult = nextResult
 
     // Determine which callbacks to trigger
@@ -639,6 +697,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)
       })
     }

package/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
     },
   }
 }

package/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
+}

package/src/types.ts

@@ -380,6 +380,11 @@ export interface QueryObserverOptions<
       >
 
   _optimisticResults?: 'optimistic' | 'isRestoring'
+
+  /**
+   * Enable prefetching during rendering
+   */
+  experimental_prefetchInRender?: boolean
 }
 
 export type WithRequired<TTarget, TKey extends keyof TTarget> = TTarget & {
@@ -687,6 +692,55 @@ export interface QueryObserverBaseResult<
    * - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
    */
   fetchStatus: FetchStatus
+  /**
+   * A stable promise that will be resolved with the data of the query.
+   * Requires the `experimental_prefetchInRender` feature flag to be enabled.
+   * @example
+   *
+   * ### Enabling the feature flag
+   * ```ts
+   * const client = new QueryClient({
+   *   defaultOptions: {
+   *     queries: {
+   *       experimental_prefetchInRender: true,
+   *     },
+   *   },
+   * })
+   * ```
+   *
+   * ### Usage
+   * ```tsx
+   * import { useQuery } from '@tanstack/react-query'
+   * import React from 'react'
+   * import { fetchTodos, type Todo } from './api'
+   *
+   * function TodoList({ query }: { query: UseQueryResult<Todo[], Error> }) {
+   *   const data = React.use(query.promise)
+   *
+   *   return (
+   *     <ul>
+   *       {data.map(todo => (
+   *         <li key={todo.id}>{todo.title}</li>
+   *       ))}
+   *     </ul>
+   *   )
+   * }
+   *
+   * export function App() {
+   *   const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+   *
+   *   return (
+   *     <>
+   *       <h1>Todos</h1>
+   *       <React.Suspense fallback={<div>Loading...</div>}>
+   *         <TodoList query={query} />
+   *       </React.Suspense>
+   *     </>
+   *   )
+   * }
+   * ```
+   */
+  promise: Promise<TData>
 }
 
 export interface QueryObserverPendingResult<