@tanstack/query-core 5.86.0 → 5.87.1

package/src/index.ts

@@ -1,50 +1,55 @@
 /* istanbul ignore file */
 
-export { CancelledError } from './retryer'
-export { QueryCache } from './queryCache'
-export type { QueryCacheNotifyEvent } from './queryCache'
-export { QueryClient } from './queryClient'
-export { QueryObserver } from './queryObserver'
-export { QueriesObserver } from './queriesObserver'
+export { focusManager } from './focusManager'
+export {
+  defaultShouldDehydrateMutation,
+  defaultShouldDehydrateQuery,
+  dehydrate,
+  hydrate,
+} from './hydration'
 export { InfiniteQueryObserver } from './infiniteQueryObserver'
 export { MutationCache } from './mutationCache'
 export type { MutationCacheNotifyEvent } from './mutationCache'
 export { MutationObserver } from './mutationObserver'
-export { notifyManager, defaultScheduler } from './notifyManager'
-export { focusManager } from './focusManager'
+export { defaultScheduler, notifyManager } from './notifyManager'
 export { onlineManager } from './onlineManager'
+export { QueriesObserver } from './queriesObserver'
+export { QueryCache } from './queryCache'
+export type { QueryCacheNotifyEvent } from './queryCache'
+export { QueryClient } from './queryClient'
+export { QueryObserver } from './queryObserver'
+export { CancelledError, isCancelledError } from './retryer'
+export {
+  timeoutManager,
+  type ManagedTimerId,
+  type TimeoutCallback,
+  type TimeoutProvider,
+} from './timeoutManager'
 export {
   hashKey,
-  partialMatchKey,
-  replaceEqualDeep,
   isServer,
-  matchQuery,
-  matchMutation,
   keepPreviousData,
-  skipToken,
+  matchMutation,
+  matchQuery,
   noop,
+  partialMatchKey,
+  replaceEqualDeep,
   shouldThrowError,
+  skipToken,
 } from './utils'
-export type { MutationFilters, QueryFilters, Updater, SkipToken } from './utils'
-export { isCancelledError } from './retryer'
-export {
-  dehydrate,
-  hydrate,
-  defaultShouldDehydrateQuery,
-  defaultShouldDehydrateMutation,
-} from './hydration'
+export type { MutationFilters, QueryFilters, SkipToken, Updater } from './utils'
 
 export { streamedQuery as experimental_streamedQuery } from './streamedQuery'
 
 // Types
-export * from './types'
-export type { QueryState } from './query'
-export { Query } from './query'
-export type { MutationState } from './mutation'
-export { Mutation } from './mutation'
 export type {
-  DehydrateOptions,
   DehydratedState,
+  DehydrateOptions,
   HydrateOptions,
 } from './hydration'
+export { Mutation } from './mutation'
+export type { MutationState } from './mutation'
 export type { QueriesObserverOptions } from './queriesObserver'
+export { Query } from './query'
+export type { QueryState } from './query'
+export * from './types'

package/src/notifyManager.ts

@@ -1,5 +1,7 @@
 // TYPES
 
+import { systemSetTimeoutZero } from './timeoutManager'
+
 type NotifyCallback = () => void
 
 type NotifyFunction = (callback: () => void) => void
@@ -10,7 +12,7 @@ type BatchCallsCallback<T extends Array<unknown>> = (...args: T) => void
 
 type ScheduleFunction = (callback: () => void) => void
 
-export const defaultScheduler: ScheduleFunction = (cb) => setTimeout(cb, 0)
+export const defaultScheduler: ScheduleFunction = systemSetTimeoutZero
 
 export function createNotifyManager() {
   let queue: Array<NotifyCallback> = []

package/src/query.ts

@@ -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() {

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>()
 
@@ -365,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()
       }
@@ -394,7 +396,7 @@ export class QueryObserver<
       return
     }
 
-    this.#refetchIntervalId = setInterval(() => {
+    this.#refetchIntervalId = timeoutManager.setInterval(() => {
       if (
         this.options.refetchIntervalInBackground ||
         focusManager.isFocused()
@@ -411,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/timeoutManager.ts

@@ -0,0 +1,135 @@
+/**
+ * {@link TimeoutManager} does not support passing arguments to the callback.
+ *
+ * `(_: void)` is the argument type inferred by TypeScript's default typings for
+ * `setTimeout(cb, number)`.
+ * If we don't accept a single void argument, then
+ * `new Promise(resolve => timeoutManager.setTimeout(resolve, N))` is a type error.
+ */
+export type TimeoutCallback = (_: void) => void
+
+/**
+ * Wrapping `setTimeout` is awkward from a typing perspective because platform
+ * typings may extend the return type of `setTimeout`. For example, NodeJS
+ * typings add `NodeJS.Timeout`; but a non-default `timeoutManager` may not be
+ * able to return such a type.
+ */
+export type ManagedTimerId = number | { [Symbol.toPrimitive]: () => number }
+
+/**
+ * Backend for timer functions.
+ */
+export type TimeoutProvider<TTimerId extends ManagedTimerId = ManagedTimerId> =
+  {
+    readonly setTimeout: (callback: TimeoutCallback, delay: number) => TTimerId
+    readonly clearTimeout: (timeoutId: TTimerId | undefined) => void
+
+    readonly setInterval: (callback: TimeoutCallback, delay: number) => TTimerId
+    readonly clearInterval: (intervalId: TTimerId | undefined) => void
+  }
+
+export const defaultTimeoutProvider: TimeoutProvider<
+  ReturnType<typeof setTimeout>
+> = {
+  // We need the wrapper function syntax below instead of direct references to
+  // global setTimeout etc.
+  //
+  // BAD: `setTimeout: setTimeout`
+  // GOOD: `setTimeout: (cb, delay) => setTimeout(cb, delay)`
+  //
+  // If we use direct references here, then anything that wants to spy on or
+  // replace the global setTimeout (like tests) won't work since we'll already
+  // have a hard reference to the original implementation at the time when this
+  // file was imported.
+  setTimeout: (callback, delay) => setTimeout(callback, delay),
+  clearTimeout: (timeoutId) => clearTimeout(timeoutId),
+
+  setInterval: (callback, delay) => setInterval(callback, delay),
+  clearInterval: (intervalId) => clearInterval(intervalId),
+}
+
+/**
+ * Allows customization of how timeouts are created.
+ *
+ * @tanstack/query-core makes liberal use of timeouts to implement `staleTime`
+ * and `gcTime`. The default TimeoutManager provider uses the platform's global
+ * `setTimeout` implementation, which is known to have scalability issues with
+ * thousands of timeouts on the event loop.
+ *
+ * If you hit this limitation, consider providing a custom TimeoutProvider that
+ * coalesces timeouts.
+ */
+export class TimeoutManager implements Omit<TimeoutProvider, 'name'> {
+  // We cannot have TimeoutManager<T> as we must instantiate it with a concrete
+  // type at app boot; and if we leave that type, then any new timer provider
+  // would need to support ReturnType<typeof setTimeout>, which is infeasible.
+  //
+  // We settle for type safety for the TimeoutProvider type, and accept that
+  // this class is unsafe internally to allow for extension.
+  #provider: TimeoutProvider<any> = defaultTimeoutProvider
+  #providerCalled = false
+
+  setTimeoutProvider<TTimerId extends ManagedTimerId>(
+    provider: TimeoutProvider<TTimerId>,
+  ): void {
+    if (process.env.NODE_ENV !== 'production') {
+      if (this.#providerCalled && provider !== this.#provider) {
+        // After changing providers, `clearTimeout` will not work as expected for
+        // timeouts from the previous provider.
+        //
+        // Since they may allocate the same timeout ID, clearTimeout may cancel an
+        // arbitrary different timeout, or unexpected no-op.
+        //
+        // We could protect against this by mixing the timeout ID bits
+        // deterministically with some per-provider bits.
+        //
+        // We could internally queue `setTimeout` calls to `TimeoutManager` until
+        // some API call to set the initial provider.
+        console.error(
+          `[timeoutManager]: Switching provider after calls to previous provider might result in unexpected behavior.`,
+          { previous: this.#provider, provider },
+        )
+      }
+    }
+
+    this.#provider = provider
+    if (process.env.NODE_ENV !== 'production') {
+      this.#providerCalled = false
+    }
+  }
+
+  setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId {
+    if (process.env.NODE_ENV !== 'production') {
+      this.#providerCalled = true
+    }
+    return this.#provider.setTimeout(callback, delay)
+  }
+
+  clearTimeout(timeoutId: ManagedTimerId | undefined): void {
+    this.#provider.clearTimeout(timeoutId)
+  }
+
+  setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId {
+    if (process.env.NODE_ENV !== 'production') {
+      this.#providerCalled = true
+    }
+    return this.#provider.setInterval(callback, delay)
+  }
+
+  clearInterval(intervalId: ManagedTimerId | undefined): void {
+    this.#provider.clearInterval(intervalId)
+  }
+}
+
+export const timeoutManager = new TimeoutManager()
+
+/**
+ * In many cases code wants to delay to the next event loop tick; this is not
+ * mediated by {@link timeoutManager}.
+ *
+ * This function is provided to make auditing the `tanstack/query-core` for
+ * incorrect use of system `setTimeout` easier.
+ */
+export function systemSetTimeoutZero(callback: TimeoutCallback): void {
+  setTimeout(callback, 0)
+}

package/src/utils.ts

@@ -1,3 +1,4 @@
+import { timeoutManager } from './timeoutManager'
 import type {
   DefaultError,
   Enabled,
@@ -361,7 +362,7 @@ function hasObjectPrototype(o: any): boolean {
 
 export function sleep(timeout: number): Promise<void> {
   return new Promise((resolve) => {
-    setTimeout(resolve, timeout)
+    timeoutManager.setTimeout(resolve, timeout)
   })
 }