@tanstack/query-core 5.56.1 → 5.59.0

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<