@tanstack/query-core 5.101.4 → 5.102.0

package/src/hydration.ts

@@ -1,4 +1,3 @@
-import { tryResolveSync } from './thenable'
 import { noop } from './utils'
 import type {
   DefaultError,
@@ -16,8 +15,24 @@ import type { Mutation, MutationState } from './mutation'
 
 // TYPES
 type TransformerFn = (data: any) => any
-function defaultTransformerFn(data: any): any {
-  return data
+
+function tryResolveSync(promise: PromiseLike<unknown>) {
+  let data: unknown
+
+  const thenResult = promise.then((result) => {
+    data = result
+    return result
+  }, noop) as Promise<unknown> | undefined
+
+  // .catch can be unavailable on certain kinds of thenable's
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  thenResult?.catch?.(noop)
+
+  if (data !== undefined) {
+    return { data }
+  }
+
+  return undefined
 }
 
 export interface DehydrateOptions {
@@ -71,51 +86,57 @@ function dehydrateMutation(mutation: Mutation): DehydratedMutation {
   }
 }
 
+function dehydratePromise(
+  query: Query,
+  serializeData?: TransformerFn,
+  shouldRedactErrors?: (error: unknown) => boolean,
+): Promise<unknown> | undefined {
+  const promise = query.promise?.then(serializeData).catch((error) => {
+    if (shouldRedactErrors?.(error) === false) {
+      // Reject original error if it should not be redacted
+      return Promise.reject(error)
+    }
+    // If not in production, log original error before rejecting redacted error
+    if (process.env.NODE_ENV !== 'production') {
+      console.error(
+        `A query that was dehydrated as pending ended up rejecting. [${query.queryHash}]: ${error}; The error will be redacted in production builds`,
+      )
+    }
+    return Promise.reject(new Error('redacted'))
+  })
+
+  // Avoid unhandled promise rejections
+  // We need the promise we dehydrate to reject to get the correct result into
+  // the query cache, but we also want to avoid unhandled promise rejections
+  // in whatever environment the prefetches are happening in.
+  promise?.catch(noop)
+
+  return promise
+}
+
 // Most config is not dehydrated but instead meant to configure again when
 // consuming the de/rehydrated data, typically with useQuery on the client.
 // Sometimes it might make sense to prefetch data on the server and include
 // in the html-payload, but not consume it on the initial render.
-function dehydrateQuery(
+export function dehydrateQuery(
   query: Query,
-  serializeData: TransformerFn,
-  shouldRedactErrors: (error: unknown) => boolean,
+  serializeData?: TransformerFn,
+  shouldRedactErrors?: (error: unknown) => boolean,
 ): DehydratedQuery {
-  const dehydratePromise = () => {
-    const promise = query.promise?.then(serializeData).catch((error) => {
-      if (!shouldRedactErrors(error)) {
-        // Reject original error if it should not be redacted
-        return Promise.reject(error)
-      }
-      // If not in production, log original error before rejecting redacted error
-      if (process.env.NODE_ENV !== 'production') {
-        console.error(
-          `A query that was dehydrated as pending ended up rejecting. [${query.queryHash}]: ${error}; The error will be redacted in production builds`,
-        )
-      }
-      return Promise.reject(new Error('redacted'))
-    })
-
-    // Avoid unhandled promise rejections
-    // We need the promise we dehydrate to reject to get the correct result into
-    // the query cache, but we also want to avoid unhandled promise rejections
-    // in whatever environment the prefetches are happening in.
-    promise?.catch(noop)
-
-    return promise
-  }
-
   return {
     dehydratedAt: Date.now(),
     state: {
       ...query.state,
       ...(query.state.data !== undefined && {
-        data: serializeData(query.state.data),
+        data: serializeData
+          ? serializeData(query.state.data)
+          : query.state.data,
       }),
     },
     queryKey: query.queryKey,
     queryHash: query.queryHash,
     ...(query.state.status === 'pending' && {
-      promise: dehydratePromise(),
+      promise: dehydratePromise(query, serializeData, shouldRedactErrors),
     }),
     ...(query.meta && { meta: query.meta }),
     ...(query.queryType && { queryType: query.queryType }),
@@ -130,10 +151,6 @@ export function defaultShouldDehydrateQuery(query: Query) {
   return query.state.status === 'success'
 }
 
-function defaultShouldRedactErrors(_: unknown) {
-  return true
-}
-
 export function dehydrate(
   client: QueryClient,
   options: DehydrateOptions = {},
@@ -157,13 +174,10 @@ export function dehydrate(
 
   const shouldRedactErrors =
     options.shouldRedactErrors ??
-    client.getDefaultOptions().dehydrate?.shouldRedactErrors ??
-    defaultShouldRedactErrors
+    client.getDefaultOptions().dehydrate?.shouldRedactErrors
 
   const serializeData =
-    options.serializeData ??
-    client.getDefaultOptions().dehydrate?.serializeData ??
-    defaultTransformerFn
+    options.serializeData ?? client.getDefaultOptions().dehydrate?.serializeData
 
   const queries = client
     .getQueryCache()
@@ -190,8 +204,7 @@ export function hydrate(
   const queryCache = client.getQueryCache()
   const deserializeData =
     options?.defaultOptions?.deserializeData ??
-    client.getDefaultOptions().hydrate?.deserializeData ??
-    defaultTransformerFn
+    client.getDefaultOptions().hydrate?.deserializeData
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   const mutations = (dehydratedState as DehydratedState).mutations || []
@@ -222,7 +235,12 @@ export function hydrate(
     }) => {
       const syncData = promise ? tryResolveSync(promise) : undefined
       const rawData = state.data === undefined ? syncData?.data : state.data
-      const data = rawData === undefined ? rawData : deserializeData(rawData)
+      const data =
+        rawData === undefined
+          ? rawData
+          : deserializeData
+            ? deserializeData(rawData)
+            : rawData
 
       let query = queryCache.get(queryHash)
       const existingQueryIsPending = query?.state.status === 'pending'

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   defaultShouldDehydrateMutation,
   defaultShouldDehydrateQuery,
   dehydrate,
+  dehydrateQuery,
   hydrate,
 } from './hydration'
 export { InfiniteQueryObserver } from './infiniteQueryObserver'

package/src/mutation.ts

@@ -165,8 +165,11 @@ export class Mutation<
   continue(): Promise<unknown> {
     return (
       this.#retryer?.continue() ??
-      // continuing a mutation assumes that variables are set, mutation must have been dehydrated before
-      this.execute(this.state.variables!)
+      // continuing a mutation assumes that variables are set, mutation must have been dehydrated before.
+      // a settled mutation has no retryer to continue and must not run again
+      (this.state.status === 'pending'
+        ? this.execute(this.state.variables!)
+        : Promise.resolve())
     )
   }
 
@@ -181,7 +184,7 @@ export class Mutation<
       mutationKey: this.options.mutationKey,
     } satisfies MutationFunctionContext
 
-    this.#retryer = createRetryer({
+    const retryer = (this.#retryer = createRetryer({
       fn: () => {
         if (!this.options.mutationFn) {
           return Promise.reject(new Error('No mutationFn found'))
@@ -200,10 +203,10 @@ export class Mutation<
       retryDelay: this.options.retryDelay,
       networkMode: this.options.networkMode,
       canRun: () => this.#mutationCache.canRun(this),
-    })
+    }))
 
     const restored = this.state.status === 'pending'
-    const isPaused = !this.#retryer.canStart()
+    const isPaused = !retryer.canStart()
 
     try {
       if (restored) {
@@ -232,7 +235,7 @@ export class Mutation<
           })
         }
       }
-      const data = await this.#retryer.start()
+      const data = await retryer.start()
 
       // Notify cache callback
       await this.#mutationCache.config.onSuccess?.(
@@ -324,6 +327,11 @@ export class Mutation<
       this.#dispatch({ type: 'error', error: error as TError })
       throw error
     } finally {
+      // The settled retryer's promise would otherwise pin this mutation's
+      // result, variables and context for as long as the cache keeps it
+      if (this.#retryer === retryer) {
+        this.#retryer = undefined
+      }
       this.#mutationCache.runNext(this)
     }
   }

package/src/mutationObserver.ts

@@ -93,6 +93,14 @@ export class MutationObserver<
     }
   }
 
+  protected onSubscribe(): void {
+    if (this.listeners.size === 1 && this.#currentMutation) {
+      this.#currentMutation.addObserver(this)
+
+      this.#updateResult()
+    }
+  }
+
   protected onUnsubscribe(): void {
     if (!this.hasListeners()) {
       this.#currentMutation?.removeObserver(this)

package/src/queriesObserver.ts

@@ -40,7 +40,7 @@ export class QueriesObserver<
   #queries: Array<QueryObserverOptions>
   #options?: QueriesObserverOptions<TCombinedResult>
   #observers: Array<QueryObserver>
-  #combinedResult?: TCombinedResult
+  #combinedResult!: TCombinedResult
   #lastCombine?: CombineFn<TCombinedResult>
   #lastResult?: Array<QueryObserverResult>
   #lastQueryHashes?: Array<string>
@@ -200,14 +200,19 @@ export class QueriesObserver<
     result: Array<QueryObserverResult>,
     matches: Array<QueryObserverMatch>,
   ) {
+    const trackedProps = new Set<keyof QueryObserverResult>()
+
     return matches.map((match, index) => {
       const observerResult = result[index]!
       return !match.defaultedQueryOptions.notifyOnChangeProps
         ? match.observer.trackResult(observerResult, (accessedProp) => {
             // track property on all observers to ensure proper (synchronized) tracking (#7000)
-            matches.forEach((m) => {
-              m.observer.trackProp(accessedProp)
-            })
+            if (!trackedProps.has(accessedProp)) {
+              trackedProps.add(accessedProp)
+              matches.forEach((m) => {
+                m.observer.trackProp(accessedProp)
+              })
+            }
           })
         : observerResult
     })
@@ -227,7 +232,6 @@ export class QueriesObserver<
           queryHashes.some((hash, i) => hash !== lastHashes[i]))
 
       if (
-        !this.#combinedResult ||
         this.#result !== this.#lastResult ||
         queryHashesChanged ||
         combine !== this.#lastCombine
@@ -251,7 +255,7 @@ export class QueriesObserver<
 
   #shouldSkipCombine(): boolean {
     return (
-      this.#options?.combine !== undefined &&
+      !this.#options?.combine ||
       this.#observers.some((observer, index) => {
         return (
           observer.options.suspense && this.#result[index]?.data === undefined
@@ -305,12 +309,14 @@ export class QueriesObserver<
 
   #notify(): void {
     if (this.hasListeners()) {
-      const newTracked = this.#trackResult(this.#result, this.#observerMatches)
       const shouldSkipCombine = this.#shouldSkipCombine()
       const previousResult = this.#combinedResult
       const newResult = shouldSkipCombine
         ? previousResult
-        : this.#combineResult(newTracked, this.#options?.combine)
+        : this.#combineResult(
+            this.#trackResult(this.#result, this.#observerMatches),
+            this.#options?.combine,
+          )
 
       if (shouldSkipCombine || previousResult !== newResult) {
         notifyManager.batch(() => {

package/src/query.ts

@@ -360,8 +360,9 @@ export class Query<
   }
 
   removeObserver(observer: QueryObserver<any, any, any, any, any>): void {
-    if (this.observers.includes(observer)) {
-      this.observers = this.observers.filter((x) => x !== observer)
+    const index = this.observers.indexOf(observer)
+    if (index !== -1) {
+      this.observers.splice(index, 1)
 
       if (!this.observers.length) {
         // If the transport layer does not support cancellation
@@ -533,7 +534,7 @@ export class Query<
     }
 
     // Try to fetch the data
-    this.#retryer = createRetryer({
+    const retryer = (this.#retryer = createRetryer({
       initialPromise: fetchOptions?.initialPromise as
         | Promise<TData>
         | undefined,
@@ -560,10 +561,10 @@ export class Query<
       retryDelay: context.options.retryDelay,
       networkMode: context.options.networkMode,
       canRun: () => true,
-    })
+    }))
 
     try {
-      const data = await this.#retryer.start()
+      const data = await retryer.start()
       // this is more of a runtime guard
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
       if (data === undefined) {
@@ -619,6 +620,11 @@ export class Query<
 
       throw error // rethrow the error for further handling
     } finally {
+      // The settled retryer's promise would otherwise pin this fetch's raw
+      // result (a second copy after structural sharing) for the query's lifetime
+      if (this.#retryer === retryer) {
+        this.#retryer = undefined
+      }
       // Schedule query gc after fetching
       this.scheduleGc()
     }
@@ -698,7 +704,9 @@ export class Query<
     this.state = reducer(this.state)
 
     notifyManager.batch(() => {
-      this.observers.forEach((observer) => {
+      // Keep the current iteration stable if an observer unsubscribes
+      // synchronously while it is being notified.
+      this.observers.slice().forEach((observer) => {
         observer.onQueryUpdate()
       })
 

package/src/queryClient.ts

@@ -24,6 +24,7 @@ import type {
   InferDataFromTag,
   InferErrorFromTag,
   InfiniteData,
+  InfiniteQueryExecuteOptions,
   InvalidateOptions,
   InvalidateQueryFilters,
   MutationKey,
@@ -31,6 +32,7 @@ import type {
   MutationOptions,
   OmitKeyof,
   QueryClientConfig,
+  QueryExecuteOptions,
   QueryKey,
   QueryObserverOptions,
   QueryOptions,
@@ -135,6 +137,9 @@ export class QueryClient {
       .data
   }
 
+  /**
+   * @deprecated Use queryClient.query({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.
+   */
   ensureQueryData<
     TQueryFnData,
     TError = DefaultError,
@@ -260,13 +265,15 @@ export class QueryClient {
     const queryCache = this.#queryCache
 
     return notifyManager.batch(() => {
-      queryCache.findAll(filters).forEach((query) => {
+      const matched = queryCache.findAll(filters)
+      const queriesToRefetch = new Set(matched)
+      matched.forEach((query) => {
         query.reset()
       })
       return this.refetchQueries(
         {
           type: 'active',
-          ...filters,
+          predicate: (query) => queriesToRefetch.has(query),
         },
         options,
       )
@@ -336,6 +343,52 @@ export class QueryClient {
     return Promise.all(promises).then(noop)
   }
 
+  async query<
+    TQueryFnData,
+    TError = DefaultError,
+    TData = TQueryFnData,
+    TQueryData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+    TPageParam = never,
+  >(
+    options: QueryExecuteOptions<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryData,
+      TQueryKey,
+      TPageParam
+    >,
+  ): Promise<TData> {
+    const defaultedOptions = this.defaultQueryOptions(options)
+
+    // https://github.com/tannerlinsley/react-query/issues/652
+    if (defaultedOptions.retry === undefined) {
+      defaultedOptions.retry = false
+    }
+
+    const query = this.#queryCache.build(this, defaultedOptions)
+
+    const isStale = query.isStaleByTime(
+      resolveStaleTime(defaultedOptions.staleTime, query),
+    )
+
+    const queryData = isStale
+      ? await query.fetch(defaultedOptions)
+      : (query.state.data as TQueryData)
+
+    const select = defaultedOptions.select
+
+    if (select) {
+      return select(queryData)
+    }
+
+    return queryData as unknown as TData
+  }
+
+  /**
+   * @deprecated Use queryClient.query(options) instead. This method will be removed in the next major version.
+   */
   fetchQuery<
     TQueryFnData,
     TError = DefaultError,
@@ -367,6 +420,9 @@ export class QueryClient {
       : Promise.resolve(query.state.data as TData)
   }
 
+  /**
+   * @deprecated Use queryClient.query(options) instead. You can swallow errors with `.catch(noop)`. This method will be removed in the next major version.
+   */
   prefetchQuery<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -378,6 +434,32 @@ export class QueryClient {
     return this.fetchQuery(options).then(noop).catch(noop)
   }
 
+  infiniteQuery<
+    TQueryFnData,
+    TError = DefaultError,
+    TData = InfiniteData<TQueryFnData>,
+    TQueryKey extends QueryKey = QueryKey,
+    TPageParam = unknown,
+  >(
+    options: InfiniteQueryExecuteOptions<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryKey,
+      TPageParam
+    >,
+  ): Promise<
+    Array<TData> extends Array<InfiniteData<TQueryFnData>>
+      ? InfiniteData<TQueryFnData, TPageParam>
+      : TData
+  > {
+    options._type = 'infinite'
+    return this.query(options as any)
+  }
+
+  /**
+   * @deprecated Use queryClient.infiniteQuery(options) instead. This method will be removed in the next major version.
+   */
   fetchInfiniteQuery<
     TQueryFnData,
     TError = DefaultError,
@@ -397,6 +479,9 @@ export class QueryClient {
     return this.fetchQuery(options as any)
   }
 
+  /**
+   * @deprecated Use queryClient.infiniteQuery(options) instead. You can swallow errors with `.catch(noop)`. This method will be removed in the next major version.
+   */
   prefetchInfiniteQuery<
     TQueryFnData,
     TError = DefaultError,
@@ -415,6 +500,9 @@ export class QueryClient {
     return this.fetchInfiniteQuery(options).then(noop).catch(noop)
   }
 
+  /**
+   * @deprecated Use queryClient.infiniteQuery({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.
+   */
   ensureInfiniteQueryData<
     TQueryFnData,
     TError = DefaultError,

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
   }