@tanstack/query-core 5.101.4 → 5.102.1

package/src/queryObserver.ts

@@ -3,7 +3,6 @@ import { environmentManager } from './environmentManager'
 import { notifyManager } from './notifyManager'
 import { fetchState } from './query'
 import { Subscribable } from './subscribable'
-import { pendingThenable } from './thenable'
 import {
   isValidTimeout,
   noop,
@@ -17,7 +16,6 @@ import { timeoutManager } from './timeoutManager'
 import type { ManagedTimerId } from './timeoutManager'
 import type { FetchOptions, Query, QueryState } from './query'
 import type { QueryClient } from './queryClient'
-import type { PendingThenable, Thenable } from './thenable'
 import type {
   DefaultError,
   DefaultedQueryObserverOptions,
@@ -56,7 +54,6 @@ export class QueryObserver<
     TQueryData,
     TQueryKey
   >
-  #currentThenable: Thenable<TData>
   #selectError: TError | null
   #selectFn?: (data: TQueryData) => TData
   #selectResult?: TData
@@ -82,7 +79,6 @@ export class QueryObserver<
 
     this.#client = client
     this.#selectError = null
-    this.#currentThenable = pendingThenable()
 
     this.bindMethods()
     this.setOptions(options)
@@ -268,19 +264,6 @@ export class QueryObserver<
       get: (target, key) => {
         this.trackProp(key as keyof QueryObserverResult)
         onPropTracked?.(key as keyof QueryObserverResult)
-        if (key === 'promise') {
-          this.trackProp('data')
-          if (
-            !this.options.experimental_prefetchInRender &&
-            this.#currentThenable.status === 'pending'
-          ) {
-            this.#currentThenable.reject(
-              new Error(
-                'experimental_prefetchInRender feature flag is not enabled',
-              ),
-            )
-          }
-        }
         return Reflect.get(target, key)
       },
     })
@@ -317,7 +300,42 @@ export class QueryObserver<
       .getQueryCache()
       .build(this.#client, defaultedOptions)
 
-    return query.fetch().then(() => this.createResult(query, defaultedOptions))
+    let unsubscribe = () => {}
+    let resolveEarly:
+      | ((result: QueryObserverResult<TData, TError>) => void)
+      | undefined
+
+    const cachePromise = new Promise<QueryObserverResult<TData, TError>>(
+      (resolve) => {
+        resolveEarly = resolve
+        unsubscribe = this.#client.getQueryCache().subscribe((event) => {
+          if (
+            event.type === 'updated' &&
+            event.query.queryHash === query.queryHash &&
+            query.state.data !== undefined
+          ) {
+            unsubscribe()
+            resolve(this.createResult(query, defaultedOptions))
+          }
+        })
+      },
+    )
+
+    return Promise.race([
+      query
+        .fetch()
+        .then(() => {
+          const result = this.createResult(query, defaultedOptions)
+          // Settle the subscriber promise so both branches always settle.
+          // This value is ignored by Promise.race since the fetch branch already won.
+          resolveEarly?.(result)
+          return result
+        })
+        .finally(() => {
+          unsubscribe()
+        }),
+      cachePromise,
+    ])
   }
 
   protected fetch(
@@ -545,6 +563,10 @@ export class QueryObserver<
           this.#selectError = selectError as TError
         }
       }
+    } else if (data === undefined) {
+      // a stored select error belongs to previously selected data; once that
+      // data is gone (query switch or reset), it must not leak into this result
+      this.#selectError = null
     }
 
     if (this.#selectError) {
@@ -552,6 +574,7 @@ export class QueryObserver<
       data = this.#selectResult
       errorUpdatedAt = Date.now()
       status = 'error'
+      isPlaceholderData = false
     }
 
     const isFetching = newState.fetchStatus === 'fetching'
@@ -588,57 +611,11 @@ export class QueryObserver<
       isRefetchError: isError && hasData,
       isStale: isStale(query, options),
       refetch: this.refetch,
-      promise: this.#currentThenable,
       isEnabled: resolveQueryBoolean(options.enabled, query) !== false,
     }
 
     const nextResult = result as QueryObserverResult<TData, TError>
 
-    if (this.options.experimental_prefetchInRender) {
-      const hasResultData = nextResult.data !== undefined
-      const isErrorWithoutData = nextResult.status === 'error' && !hasResultData
-      const finalizeThenableIfPossible = (thenable: PendingThenable<TData>) => {
-        if (isErrorWithoutData) {
-          thenable.reject(nextResult.error)
-        } else if (hasResultData) {
-          thenable.resolve(nextResult.data as TData)
-        }
-      }
-
-      /**
-       * 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
-          // and we are still observing the same query
-          if (query.queryHash === prevQuery.queryHash) {
-            finalizeThenableIfPossible(prevThenable)
-          }
-          break
-        case 'fulfilled':
-          if (isErrorWithoutData || nextResult.data !== prevThenable.value) {
-            recreateThenable()
-          }
-          break
-        case 'rejected':
-          if (!isErrorWithoutData || nextResult.error !== prevThenable.reason) {
-            recreateThenable()
-          }
-          break
-      }
-    }
-
     return nextResult
   }
 

package/src/retryer.ts

@@ -1,9 +1,7 @@
 import { focusManager } from './focusManager'
 import { onlineManager } from './onlineManager'
-import { pendingThenable } from './thenable'
 import { environmentManager } from './environmentManager'
-import { sleep } from './utils'
-import type { Thenable } from './thenable'
+import { noop, sleep } from './utils'
 import type { CancelOptions, DefaultError, NetworkMode } from './types'
 
 // TYPES
@@ -32,6 +30,8 @@ export interface Retryer<TData = unknown> {
   status: () => 'pending' | 'resolved' | 'rejected'
 }
 
+type RetryerStatus = 'pending' | 'resolved' | 'rejected'
+
 export type RetryValue<TError> = boolean | number | ShouldRetryFunction<TError>
 
 type ShouldRetryFunction<TError = DefaultError> = (
@@ -79,11 +79,17 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   let isRetryCancelled = false
   let failureCount = 0
   let continueFn: ((value?: unknown) => void) | undefined
+  let status: RetryerStatus = 'pending'
+  let promiseResolve: (data: TData) => void
+  let promiseReject: (error: TError) => void
 
-  const thenable = pendingThenable<TData>()
+  const promise = new Promise<TData>((resolve, reject) => {
+    promiseResolve = resolve
+    promiseReject = reject
+  })
+  promise.catch(noop)
 
-  const isResolved = () =>
-    (thenable.status as Thenable<TData>['status']) !== 'pending'
+  const isResolved = () => status !== 'pending'
 
   const cancel = (cancelOptions?: CancelOptions): void => {
     if (!isResolved()) {
@@ -111,14 +117,16 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   const resolve = (value: any) => {
     if (!isResolved()) {
       continueFn?.()
-      thenable.resolve(value)
+      status = 'resolved'
+      promiseResolve(value)
     }
   }
 
   const reject = (value: any) => {
     if (!isResolved()) {
       continueFn?.()
-      thenable.reject(value)
+      status = 'rejected'
+      promiseReject(value)
     }
   }
 
@@ -206,12 +214,12 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   }
 
   return {
-    promise: thenable,
-    status: () => thenable.status,
+    promise,
+    status: () => status,
     cancel,
     continue: () => {
       continueFn?.()
-      return thenable
+      return promise
     },
     cancelRetry,
     continueRetry,
@@ -223,7 +231,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
       } else {
         pause().then(run)
       }
-      return thenable
+      return promise
     },
   }
 }

package/src/types.ts

@@ -79,6 +79,14 @@ export type DataTag<
       [dataTagErrorSymbol]: TError
     }
 
+export type QueryKeyWithDataTag<
+  TQueryKey extends QueryKey = QueryKey,
+  TQueryFnData = unknown,
+  TError = DefaultError,
+> = {
+  queryKey: DataTag<TQueryKey, TQueryFnData, TError>
+}
+
 export type InferDataFromTag<TQueryFnData, TTaggedQueryKey extends QueryKey> =
   TTaggedQueryKey extends DataTag<unknown, infer TaggedValue, unknown>
     ? TaggedValue
@@ -429,11 +437,6 @@ export interface QueryObserverOptions<
       >
 
   _optimisticResults?: 'optimistic' | 'isRestoring'
-
-  /**
-   * Enable prefetching during rendering
-   */
-  experimental_prefetchInRender?: boolean
 }
 
 export type WithRequired<TTarget, TKey extends keyof TTarget> = TTarget & {
@@ -486,6 +489,27 @@ export type DefaultedInfiniteQueryObserverOptions<
   'throwOnError' | 'refetchOnReconnect' | 'queryHash'
 >
 
+export interface QueryExecuteOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = never,
+> extends WithRequired<
+  QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey, TPageParam>,
+  'queryKey'
+> {
+  initialPageParam?: never
+  select?: (data: TQueryData) => TData
+  /**
+   * The time in milliseconds after data is considered stale.
+   * If the data is fresh it will be returned from the cache.
+   */
+  staleTime?: StaleTimeFunction<TQueryFnData, TError, TQueryData, TQueryKey>
+}
+
+/** @deprecated */
 export interface FetchQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -504,6 +528,7 @@ export interface FetchQueryOptions<
   staleTime?: StaleTimeFunction<TQueryFnData, TError, TData, TQueryKey>
 }
 
+/** @deprecated */
 export interface EnsureQueryDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -520,6 +545,7 @@ export interface EnsureQueryDataOptions<
   revalidateIfStale?: boolean
 }
 
+/** @deprecated */
 export type EnsureInfiniteQueryDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -536,13 +562,34 @@ export type EnsureInfiniteQueryDataOptions<
   revalidateIfStale?: boolean
 }
 
-type FetchInfiniteQueryPages<TQueryFnData = unknown, TPageParam = unknown> =
+type InfiniteQueryPages<TQueryFnData = unknown, TPageParam = unknown> =
   | { pages?: never }
   | {
       pages: number
       getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>
     }
 
+export type InfiniteQueryExecuteOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = InfiniteData<TQueryFnData>,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+> = Omit<
+  QueryExecuteOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    InfiniteData<TQueryFnData, TPageParam>,
+    TQueryKey,
+    TPageParam
+  >,
+  'initialPageParam'
+> &
+  InitialPageParam<TPageParam> &
+  InfiniteQueryPages<TQueryFnData, TPageParam>
+
+/** @deprecated */
 export type FetchInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -560,7 +607,7 @@ export type FetchInfiniteQueryOptions<
   'initialPageParam'
 > &
   InitialPageParam<TPageParam> &
-  FetchInfiniteQueryPages<TQueryFnData, TPageParam>
+  InfiniteQueryPages<TQueryFnData, TPageParam>
 
 export interface ResultOptions {
   throwOnError?: boolean
@@ -743,55 +790,6 @@ 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<
@@ -1178,14 +1176,28 @@ export interface MutateOptions<
   ) => void
 }
 
+export type MutateFunctionRest<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> = undefined extends TVariables
+  ? [
+      variables?: TVariables,
+      options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+    ]
+  : [
+      variables: TVariables,
+      options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+    ]
+
 export type MutateFunction<
   TData = unknown,
   TError = DefaultError,
   TVariables = void,
   TOnMutateResult = unknown,
 > = (
-  variables: TVariables,
-  options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+  ...rest: MutateFunctionRest<TData, TError, TVariables, TOnMutateResult>
 ) => Promise<TData>
 
 export interface MutationObserverBaseResult<