@tanstack/query-core 5.83.1 → 5.87.4

package/src/queriesObserver.ts

@@ -1,7 +1,7 @@
 import { notifyManager } from './notifyManager'
 import { QueryObserver } from './queryObserver'
 import { Subscribable } from './subscribable'
-import { replaceEqualDeep } from './utils'
+import { replaceEqualDeep, shallowEqualObjects } from './utils'
 import type {
   DefaultedQueryObserverOptions,
   QueryObserverOptions,
@@ -118,30 +118,39 @@ export class QueriesObserver<
         observer.getCurrentResult(),
       )
 
+      const hasLengthChange = prevObservers.length !== newObservers.length
       const hasIndexChange = newObservers.some(
         (observer, index) => observer !== prevObservers[index],
       )
+      const hasStructuralChange = hasLengthChange || hasIndexChange
 
-      if (prevObservers.length === newObservers.length && !hasIndexChange) {
-        return
-      }
+      const hasResultChange = hasStructuralChange
+        ? true
+        : newResult.some((result, index) => {
+            const prev = this.#result[index]
+            return !prev || !shallowEqualObjects(result, prev)
+          })
 
-      this.#observers = newObservers
-      this.#result = newResult
+      if (!hasStructuralChange && !hasResultChange) return
 
-      if (!this.hasListeners()) {
-        return
+      if (hasStructuralChange) {
+        this.#observers = newObservers
       }
 
-      difference(prevObservers, newObservers).forEach((observer) => {
-        observer.destroy()
-      })
+      this.#result = newResult
 
-      difference(newObservers, prevObservers).forEach((observer) => {
-        observer.subscribe((result) => {
-          this.#onUpdate(observer, result)
+      if (!this.hasListeners()) return
+
+      if (hasStructuralChange) {
+        difference(prevObservers, newObservers).forEach((observer) => {
+          observer.destroy()
         })
-      })
+        difference(newObservers, prevObservers).forEach((observer) => {
+          observer.subscribe((result) => {
+            this.#onUpdate(observer, result)
+          })
+        })
+      }
 
       this.#notify()
     })

package/src/query.ts

@@ -8,7 +8,7 @@ import {
   timeUntilStale,
 } from './utils'
 import { notifyManager } from './notifyManager'
-import { canFetch, createRetryer, isCancelledError } from './retryer'
+import { CancelledError, canFetch, createRetryer } from './retryer'
 import { Removable } from './removable'
 import type { QueryCache } from './queryCache'
 import type { QueryClient } from './queryClient'
@@ -205,6 +205,18 @@ export class Query<
     this.options = { ...this.#defaultOptions, ...options }
 
     this.updateGcTime(this.options.gcTime)
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this.state && this.state.data === undefined) {
+      const defaultState = getDefaultState(this.options)
+      if (defaultState.data !== undefined) {
+        this.setData(defaultState.data, {
+          updatedAt: defaultState.dataUpdatedAt,
+          manual: true,
+        })
+        this.#initialState = defaultState
+      }
+    }
   }
 
   protected optionalRemove() {
@@ -372,11 +384,17 @@ export class Query<
     }
   }
 
-  fetch(
+  async fetch(
     options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     fetchOptions?: FetchOptions<TQueryFnData>,
   ): Promise<TData> {
-    if (this.state.fetchStatus !== 'idle') {
+    if (
+      this.state.fetchStatus !== 'idle' &&
+      // If the promise in the retyer is already rejected, we have to definitely
+      // re-start the fetch; there is a chance that the query is still in a
+      // pending state when that happens
+      this.#retryer?.status() !== 'rejected'
+    ) {
       if (this.state.data !== undefined && fetchOptions?.cancelRefetch) {
         // Silently cancel current fetch if the user wants to cancel refetch
         this.cancel({ silent: true })
@@ -495,69 +513,21 @@ export class Query<
       this.#dispatch({ type: 'fetch', meta: context.fetchOptions?.meta })
     }
 
-    const onError = (error: TError | { silent?: boolean }) => {
-      // Optimistically update state if needed
-      if (!(isCancelledError(error) && error.silent)) {
-        this.#dispatch({
-          type: 'error',
-          error: error as TError,
-        })
-      }
-
-      if (!isCancelledError(error)) {
-        // Notify cache callback
-        this.#cache.config.onError?.(
-          error as any,
-          this as Query<any, any, any, any>,
-        )
-        this.#cache.config.onSettled?.(
-          this.state.data,
-          error as any,
-          this as Query<any, any, any, any>,
-        )
-      }
-
-      // Schedule query gc after fetching
-      this.scheduleGc()
-    }
-
     // Try to fetch the data
     this.#retryer = createRetryer({
       initialPromise: fetchOptions?.initialPromise as
         | Promise<TData>
         | undefined,
       fn: context.fetchFn as () => Promise<TData>,
-      abort: abortController.abort.bind(abortController),
-      onSuccess: (data) => {
-        if (data === undefined) {
-          if (process.env.NODE_ENV !== 'production') {
-            console.error(
-              `Query data cannot be undefined. Please make sure to return a value other than undefined from your query function. Affected query key: ${this.queryHash}`,
-            )
-          }
-          onError(new Error(`${this.queryHash} data is undefined`) as any)
-          return
+      onCancel: (error) => {
+        if (error instanceof CancelledError && error.revert) {
+          this.setState({
+            ...this.#revertState,
+            fetchStatus: 'idle' as const,
+          })
         }
-
-        try {
-          this.setData(data)
-        } catch (error) {
-          onError(error as TError)
-          return
-        }
-
-        // Notify cache callback
-        this.#cache.config.onSuccess?.(data, this as Query<any, any, any, any>)
-        this.#cache.config.onSettled?.(
-          data,
-          this.state.error as any,
-          this as Query<any, any, any, any>,
-        )
-
-        // Schedule query gc after fetching
-        this.scheduleGc()
+        abortController.abort()
       },
-      onError,
       onFail: (failureCount, error) => {
         this.#dispatch({ type: 'failed', failureCount, error })
       },
@@ -573,7 +543,66 @@ export class Query<
       canRun: () => true,
     })
 
-    return this.#retryer.start()
+    try {
+      const data = await this.#retryer.start()
+      // this is more of a runtime guard
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (data === undefined) {
+        if (process.env.NODE_ENV !== 'production') {
+          console.error(
+            `Query data cannot be undefined. Please make sure to return a value other than undefined from your query function. Affected query key: ${this.queryHash}`,
+          )
+        }
+        throw new Error(`${this.queryHash} data is undefined`)
+      }
+
+      this.setData(data)
+
+      // Notify cache callback
+      this.#cache.config.onSuccess?.(data, this as Query<any, any, any, any>)
+      this.#cache.config.onSettled?.(
+        data,
+        this.state.error as any,
+        this as Query<any, any, any, any>,
+      )
+      return data
+    } catch (error) {
+      if (error instanceof CancelledError) {
+        if (error.silent) {
+          // silent cancellation implies a new fetch is going to be started,
+          // so we piggyback onto that promise
+          return this.#retryer.promise
+        } else if (error.revert) {
+          // transform error into reverted state data
+          // if the initial fetch was cancelled, we have no data, so we have
+          // to get reject with a CancelledError
+          if (this.state.data === undefined) {
+            throw error
+          }
+          return this.state.data
+        }
+      }
+      this.#dispatch({
+        type: 'error',
+        error: error as TError,
+      })
+
+      // Notify cache callback
+      this.#cache.config.onError?.(
+        error as any,
+        this as Query<any, any, any, any>,
+      )
+      this.#cache.config.onSettled?.(
+        this.state.data,
+        error as any,
+        this as Query<any, any, any, any>,
+      )
+
+      throw error // rethrow the error for further handling
+    } finally {
+      // Schedule query gc after fetching
+      this.scheduleGc()
+    }
   }
 
   #dispatch(action: Action<TData, TError>): void {
@@ -604,29 +633,27 @@ export class Query<
             fetchMeta: action.meta ?? null,
           }
         case 'success':
-          // If fetching ends successfully, we don't need revertState as a fallback anymore.
-          this.#revertState = undefined
-          return {
+          const newState = {
             ...state,
             data: action.data,
             dataUpdateCount: state.dataUpdateCount + 1,
             dataUpdatedAt: action.dataUpdatedAt ?? Date.now(),
             error: null,
             isInvalidated: false,
-            status: 'success',
+            status: 'success' as const,
             ...(!action.manual && {
-              fetchStatus: 'idle',
+              fetchStatus: 'idle' as const,
               fetchFailureCount: 0,
               fetchFailureReason: null,
             }),
           }
+          // If fetching ends successfully, we don't need revertState as a fallback anymore.
+          // For manual updates, capture the state to revert to it in case of a cancellation.
+          this.#revertState = action.manual ? newState : undefined
+
+          return newState
         case 'error':
           const error = action.error
-
-          if (isCancelledError(error) && error.revert && this.#revertState) {
-            return { ...this.#revertState, fetchStatus: 'idle' }
-          }
-
           return {
             ...state,
             error,

package/src/queryObserver.ts

@@ -13,6 +13,8 @@ import {
   shallowEqualObjects,
   timeUntilStale,
 } from './utils'
+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'
@@ -62,8 +64,8 @@ export class QueryObserver<
   // This property keeps track of the last query with defined data.
   // It will be used to pass the previous data and query to the placeholder function between renders.
   #lastQueryWithDefinedData?: Query<TQueryFnData, TError, TQueryData, TQueryKey>
-  #staleTimeoutId?: ReturnType<typeof setTimeout>
-  #refetchIntervalId?: ReturnType<typeof setInterval>
+  #staleTimeoutId?: ManagedTimerId
+  #refetchIntervalId?: ManagedTimerId
   #currentRefetchInterval?: number | false
   #trackedProps = new Set<keyof QueryObserverResult>()
 
@@ -82,11 +84,6 @@ 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)
@@ -272,6 +269,17 @@ export class QueryObserver<
       get: (target, key) => {
         this.trackProp(key as keyof QueryObserverResult)
         onPropTracked?.(key as keyof QueryObserverResult)
+        if (
+          key === 'promise' &&
+          !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)
       },
     })
@@ -359,7 +367,7 @@ export class QueryObserver<
     // To mitigate this issue we always add 1 ms to the timeout.
     const timeout = time + 1
 
-    this.#staleTimeoutId = setTimeout(() => {
+    this.#staleTimeoutId = timeoutManager.setTimeout(() => {
       if (!this.#currentResult.isStale) {
         this.updateResult()
       }
@@ -388,7 +396,7 @@ export class QueryObserver<
       return
     }
 
-    this.#refetchIntervalId = setInterval(() => {
+    this.#refetchIntervalId = timeoutManager.setInterval(() => {
       if (
         this.options.refetchIntervalInBackground ||
         focusManager.isFocused()
@@ -405,14 +413,14 @@ export class QueryObserver<
 
   #clearStaleTimeout(): void {
     if (this.#staleTimeoutId) {
-      clearTimeout(this.#staleTimeoutId)
+      timeoutManager.clearTimeout(this.#staleTimeoutId)
       this.#staleTimeoutId = undefined
     }
   }
 
   #clearRefetchInterval(): void {
     if (this.#refetchIntervalId) {
-      clearInterval(this.#refetchIntervalId)
+      timeoutManager.clearInterval(this.#refetchIntervalId)
       this.#refetchIntervalId = undefined
     }
   }

package/src/removable.ts

@@ -1,8 +1,10 @@
+import { timeoutManager } from './timeoutManager'
 import { isServer, isValidTimeout } from './utils'
+import type { ManagedTimerId } from './timeoutManager'
 
 export abstract class Removable {
   gcTime!: number
-  #gcTimeout?: ReturnType<typeof setTimeout>
+  #gcTimeout?: ManagedTimerId
 
   destroy(): void {
     this.clearGcTimeout()
@@ -12,7 +14,7 @@ export abstract class Removable {
     this.clearGcTimeout()
 
     if (isValidTimeout(this.gcTime)) {
-      this.#gcTimeout = setTimeout(() => {
+      this.#gcTimeout = timeoutManager.setTimeout(() => {
         this.optionalRemove()
       }, this.gcTime)
     }
@@ -28,7 +30,7 @@ export abstract class Removable {
 
   protected clearGcTimeout() {
     if (this.#gcTimeout) {
-      clearTimeout(this.#gcTimeout)
+      timeoutManager.clearTimeout(this.#gcTimeout)
       this.#gcTimeout = undefined
     }
   }

package/src/retryer.ts

@@ -2,6 +2,7 @@ import { focusManager } from './focusManager'
 import { onlineManager } from './onlineManager'
 import { pendingThenable } from './thenable'
 import { isServer, sleep } from './utils'
+import type { Thenable } from './thenable'
 import type { CancelOptions, DefaultError, NetworkMode } from './types'
 
 // TYPES
@@ -9,9 +10,7 @@ import type { CancelOptions, DefaultError, NetworkMode } from './types'
 interface RetryerConfig<TData = unknown, TError = DefaultError> {
   fn: () => TData | Promise<TData>
   initialPromise?: Promise<TData>
-  abort?: () => void
-  onError?: (error: TError) => void
-  onSuccess?: (data: TData) => void
+  onCancel?: (error: TError) => void
   onFail?: (failureCount: number, error: TError) => void
   onPause?: () => void
   onContinue?: () => void
@@ -29,6 +28,7 @@ export interface Retryer<TData = unknown> {
   continueRetry: () => void
   canStart: () => boolean
   start: () => Promise<TData>
+  status: () => 'pending' | 'resolved' | 'rejected'
 }
 
 export type RetryValue<TError> = boolean | number | ShouldRetryFunction<TError>
@@ -65,6 +65,9 @@ export class CancelledError extends Error {
   }
 }
 
+/**
+ * @deprecated Use instanceof `CancelledError` instead.
+ */
 export function isCancelledError(value: any): value is CancelledError {
   return value instanceof CancelledError
 }
@@ -74,16 +77,19 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
 ): Retryer<TData> {
   let isRetryCancelled = false
   let failureCount = 0
-  let isResolved = false
   let continueFn: ((value?: unknown) => void) | undefined
 
   const thenable = pendingThenable<TData>()
 
+  const isResolved = () =>
+    (thenable.status as Thenable<TData>['status']) !== 'pending'
+
   const cancel = (cancelOptions?: CancelOptions): void => {
-    if (!isResolved) {
-      reject(new CancelledError(cancelOptions))
+    if (!isResolved()) {
+      const error = new CancelledError(cancelOptions) as TError
+      reject(error)
 
-      config.abort?.()
+      config.onCancel?.(error)
     }
   }
   const cancelRetry = () => {
@@ -102,18 +108,14 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   const canStart = () => canFetch(config.networkMode) && config.canRun()
 
   const resolve = (value: any) => {
-    if (!isResolved) {
-      isResolved = true
-      config.onSuccess?.(value)
+    if (!isResolved()) {
       continueFn?.()
       thenable.resolve(value)
     }
   }
 
   const reject = (value: any) => {
-    if (!isResolved) {
-      isResolved = true
-      config.onError?.(value)
+    if (!isResolved()) {
       continueFn?.()
       thenable.reject(value)
     }
@@ -122,14 +124,14 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   const pause = () => {
     return new Promise((continueResolve) => {
       continueFn = (value) => {
-        if (isResolved || canContinue()) {
+        if (isResolved() || canContinue()) {
           continueResolve(value)
         }
       }
       config.onPause?.()
     }).then(() => {
       continueFn = undefined
-      if (!isResolved) {
+      if (!isResolved()) {
         config.onContinue?.()
       }
     })
@@ -138,7 +140,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   // Create loop function
   const run = () => {
     // Do nothing if already resolved
-    if (isResolved) {
+    if (isResolved()) {
       return
     }
 
@@ -159,7 +161,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
       .then(resolve)
       .catch((error) => {
         // Stop if the fetch is already resolved
-        if (isResolved) {
+        if (isResolved()) {
           return
         }
 
@@ -204,6 +206,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
 
   return {
     promise: thenable,
+    status: () => thenable.status,
     cancel,
     continue: () => {
       continueFn?.()

package/src/streamedQuery.ts

@@ -1,6 +1,34 @@
 import { addToEnd } from './utils'
 import type { QueryFunction, QueryFunctionContext, QueryKey } from './types'
 
+type BaseStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = {
+  streamFn: (
+    context: QueryFunctionContext<TQueryKey>,
+  ) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>
+  refetchMode?: 'append' | 'reset' | 'replace'
+}
+
+type SimpleStreamedQueryParams<
+  TQueryFnData,
+  TQueryKey extends QueryKey,
+> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
+  reducer?: never
+  initialValue?: never
+}
+
+type ReducibleStreamedQueryParams<
+  TQueryFnData,
+  TData,
+  TQueryKey extends QueryKey,
+> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
+  reducer: (acc: TData, chunk: TQueryFnData) => TData
+  initialValue: TData
+}
+
+type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> =
+  | SimpleStreamedQueryParams<TQueryFnData, TQueryKey>
+  | ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey>
+
 /**
  * This is a helper function to create a query function that streams data from an AsyncIterable.
  * Data will be an Array of all the chunks received.
@@ -11,31 +39,29 @@ import type { QueryFunction, QueryFunctionContext, QueryKey } from './types'
  * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.
  * Set to `'append'` to append new data to the existing data.
  * Set to `'replace'` to write all data to the cache once the stream ends.
- * @param maxChunks - The maximum number of chunks to keep in the cache.
- * Defaults to `undefined`, meaning all chunks will be kept.
- * If `undefined` or `0`, the number of chunks is unlimited.
- * If the number of chunks exceeds this number, the oldest chunk will be removed.
+ * @param reducer - A function to reduce the streamed chunks into the final data.
+ * Defaults to a function that appends chunks to the end of the array.
+ * @param initialValue - Initial value to be used while the first chunk is being fetched.
  */
 export function streamedQuery<
   TQueryFnData = unknown,
+  TData = Array<TQueryFnData>,
   TQueryKey extends QueryKey = QueryKey,
 >({
-  queryFn,
+  streamFn,
   refetchMode = 'reset',
-  maxChunks,
-}: {
-  queryFn: (
-    context: QueryFunctionContext<TQueryKey>,
-  ) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>
-  refetchMode?: 'append' | 'reset' | 'replace'
-  maxChunks?: number
-}): QueryFunction<Array<TQueryFnData>, TQueryKey> {
+  reducer = (items, chunk) =>
+    addToEnd(items as Array<TQueryFnData>, chunk) as TData,
+  initialValue = [] as TData,
+}: StreamedQueryParams<TQueryFnData, TData, TQueryKey>): QueryFunction<
+  TData,
+  TQueryKey
+> {
   return async (context) => {
     const query = context.client
       .getQueryCache()
       .find({ queryKey: context.queryKey, exact: true })
     const isRefetch = !!query && query.state.data !== undefined
-
     if (isRefetch && refetchMode === 'reset') {
       query.setState({
         status: 'pending',
@@ -45,8 +71,9 @@ export function streamedQuery<
       })
     }
 
-    let result: Array<TQueryFnData> = []
-    const stream = await queryFn(context)
+    let result = initialValue
+
+    const stream = await streamFn(context)
 
     for await (const chunk of stream) {
       if (context.signal.aborted) {
@@ -55,19 +82,16 @@ export function streamedQuery<
 
       // don't append to the cache directly when replace-refetching
       if (!isRefetch || refetchMode !== 'replace') {
-        context.client.setQueryData<Array<TQueryFnData>>(
-          context.queryKey,
-          (prev = []) => {
-            return addToEnd(prev, chunk, maxChunks)
-          },
+        context.client.setQueryData<TData>(context.queryKey, (prev) =>
+          reducer(prev === undefined ? initialValue : prev, chunk),
         )
       }
-      result = addToEnd(result, chunk, maxChunks)
+      result = reducer(result, chunk)
     }
 
     // finalize result: replace-refetching needs to write to the cache
     if (isRefetch && refetchMode === 'replace' && !context.signal.aborted) {
-      context.client.setQueryData<Array<TQueryFnData>>(context.queryKey, result)
+      context.client.setQueryData<TData>(context.queryKey, result)
     }
 
     return context.client.getQueryData(context.queryKey)!