feat(query-core): add timeoutManager to allow changing setTimeout/setInterval

packages/query-async-storage-persister/src/asyncThrottle.ts

@@ -1,3 +1,4 @@
+import { managedSetTimeout } from '../../query-core/src/timeoutManager'
 import { noop } from './utils'
 
 interface AsyncThrottleOptions {
@@ -21,11 +22,11 @@ export function asyncThrottle<TArgs extends ReadonlyArray<unknown>>(
     if (isScheduled) return
     isScheduled = true
     while (isExecuting) {
-      await new Promise((done) => setTimeout(done, interval))
+      await new Promise((done) => managedSetTimeout(done, interval))
     }
     while (Date.now() < nextExecutionTime) {
       await new Promise((done) =>
-        setTimeout(done, nextExecutionTime - Date.now()),
+        managedSetTimeout(done, nextExecutionTime - Date.now()),
       )
     }
     isScheduled = false

packages/query-core/src/index.ts

@@ -11,6 +11,15 @@ export { MutationCache } from './mutationCache'
 export type { MutationCacheNotifyEvent } from './mutationCache'
 export { MutationObserver } from './mutationObserver'
 export { notifyManager, defaultScheduler } from './notifyManager'
+export {
+  managedSetTimeout,
+  managedClearTimeout,
+  managedSetInterval,
+  managedClearInterval,
+  systemSetTimeoutZero,
+  defaultTimeoutProvider,
+  type ManagedTimerId,
+} from './timeoutManager'
 export { focusManager } from './focusManager'
 export { onlineManager } from './onlineManager'
 export {

packages/query-core/src/notifyManager.ts

@@ -1,5 +1,7 @@
 // TYPES
 
+import { systemSetTimeoutZero } from './timeoutManager'
+
 type NotifyCallback = () => void
 
 type NotifyFunction = (callback: () => void) => void
@@ -10,7 +12,8 @@ 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 = (cb) =>
+  systemSetTimeoutZero(cb)
 
 export function createNotifyManager() {
   let queue: Array<NotifyCallback> = []

packages/query-core/src/queryObserver.ts

@@ -13,6 +13,13 @@ import {
   shallowEqualObjects,
   timeUntilStale,
 } from './utils'
+import {
+  managedClearInterval,
+  managedClearTimeout,
+  managedSetInterval,
+  managedSetTimeout,
+} 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 +69,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 +372,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 = managedSetTimeout(() => {
       if (!this.#currentResult.isStale) {
         this.updateResult()
       }
@@ -394,7 +401,7 @@ export class QueryObserver<
       return
     }
 
-    this.#refetchIntervalId = setInterval(() => {
+    this.#refetchIntervalId = managedSetInterval(() => {
       if (
         this.options.refetchIntervalInBackground ||
         focusManager.isFocused()
@@ -411,14 +418,14 @@ export class QueryObserver<
 
   #clearStaleTimeout(): void {
     if (this.#staleTimeoutId) {
-      clearTimeout(this.#staleTimeoutId)
+      managedClearTimeout(this.#staleTimeoutId)
       this.#staleTimeoutId = undefined
     }
   }
 
   #clearRefetchInterval(): void {
     if (this.#refetchIntervalId) {
-      clearInterval(this.#refetchIntervalId)
+      managedClearInterval(this.#refetchIntervalId)
       this.#refetchIntervalId = undefined
     }
   }

packages/query-core/src/removable.ts

@@ -1,8 +1,10 @@
+import { managedClearTimeout, managedSetTimeout } 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 = managedSetTimeout(() => {
         this.optionalRemove()
       }, this.gcTime)
     }
@@ -28,7 +30,7 @@ export abstract class Removable {
 
   protected clearGcTimeout() {
     if (this.#gcTimeout) {
-      clearTimeout(this.#gcTimeout)
+      managedClearTimeout(this.#gcTimeout)
       this.#gcTimeout = undefined
     }
   }

packages/query-core/src/timeoutManager.ts

@@ -0,0 +1,174 @@
+/**
+ * Timeout manager does not support passing arguments to the callback.
+ * (`void` is the argument type inferred by TypeScript's default typings for `setTimeout(cb, number)`)
+ */
+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.
+ *
+ * Still, we can downlevel `NodeJS.Timeout` to `number` as it implements
+ * Symbol.toPrimitive.
+ */
+export type TimeoutProviderId = number | { [Symbol.toPrimitive]: () => number }
+
+/**
+ * Backend for timer functions.
+ */
+export type TimeoutProvider = {
+  /** Used in error messages. */
+  readonly name: string
+
+  readonly setTimeout: (
+    callback: TimeoutCallback,
+    delay: number,
+  ) => TimeoutProviderId
+  readonly clearTimeout: (timeoutId: number | undefined) => void
+
+  readonly setInterval: (
+    callback: TimeoutCallback,
+    delay: number,
+  ) => TimeoutProviderId
+  readonly clearInterval: (intervalId: number | undefined) => void
+}
+
+export const defaultTimeoutProvider: TimeoutProvider = {
+  name: 'default',
+
+  setTimeout: (callback, delay) => setTimeout(callback, delay),
+  clearTimeout: (timeoutId) => clearTimeout(timeoutId),
+
+  setInterval: (callback, delay) => setInterval(callback, delay),
+  clearInterval: (intervalId) => clearInterval(intervalId),
+}
+
+/** Timeout ID returned by {@link TimeoutManager} */
+export type ManagedTimerId = number
+
+/**
+ * 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'> {
+  #provider: TimeoutProvider = defaultTimeoutProvider
+  #providerCalled = false
+
+  setTimeoutProvider(provider: TimeoutProvider): void {
+    if (provider === this.#provider) {
+      return
+    }
+
+    if (this.#providerCalled) {
+      // 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.warn(
+        `[timeoutManager]: Switching to ${provider.name} provider after calls to ${this.#provider.name} provider might result in unexpected behavior.`,
+      )
+    }
+
+    this.#provider = provider
+    this.#providerCalled = false
+  }
+
+  setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId {
+    this.#providerCalled = true
+    return providerIdToNumber(
+      this.#provider,
+      this.#provider.setTimeout(callback, delay),
+    )
+  }
+
+  clearTimeout(timeoutId: ManagedTimerId | undefined): void {
+    this.#provider.clearTimeout(timeoutId)
+  }
+
+  setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId {
+    this.#providerCalled = true
+    return providerIdToNumber(
+      this.#provider,
+      this.#provider.setInterval(callback, delay),
+    )
+  }
+
+  clearInterval(intervalId: ManagedTimerId | undefined): void {
+    this.#provider.clearInterval(intervalId)
+  }
+}
+
+function providerIdToNumber(
+  provider: TimeoutProvider,
+  providerId: TimeoutProviderId,
+): ManagedTimerId {
+  const numberId = Number(providerId)
+  if (isNaN(numberId)) {
+    throw new Error(
+      `TimeoutManager: could not convert ${provider.name} provider timeout ID to valid number`,
+    )
+  }
+  return numberId
+}
+
+export const timeoutManager = new TimeoutManager()
+
+// Exporting functions that use `setTimeout` to reduce bundle size impact, since
+// method names on objects are usually not minified.
+
+/** A version of `setTimeout` controlled by {@link timeoutManager}. */
+export function managedSetTimeout(
+  callback: TimeoutCallback,
+  delay: number,
+): ManagedTimerId {
+  return timeoutManager.setTimeout(callback, delay)
+}
+
+/** A version of `clearTimeout` controlled by {@link timeoutManager}. */
+export function managedClearTimeout(
+  timeoutId: ManagedTimerId | undefined,
+): void {
+  timeoutManager.clearTimeout(timeoutId)
+}
+
+/** A version of `setInterval` controlled by {@link timeoutManager}. */
+export function managedSetInterval(
+  callback: TimeoutCallback,
+  delay: number,
+): ManagedTimerId {
+  return timeoutManager.setInterval(callback, delay)
+}
+
+/** A version of `clearInterval` controlled by {@link timeoutManager}. */
+export function managedClearInterval(
+  intervalId: ManagedTimerId | undefined,
+): void {
+  timeoutManager.clearInterval(intervalId)
+}
+
+/**
+ * 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)
+}

packages/query-core/src/utils.ts

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

packages/query-persist-client-core/src/createPersister.ts

@@ -1,4 +1,9 @@
-import { hashKey, matchQuery, partialMatchKey } from '@tanstack/query-core'
+import {
+  hashKey,
+  matchQuery,
+  partialMatchKey,
+  systemSetTimeoutZero,
+} from '@tanstack/query-core'
 import type {
   Query,
   QueryClient,
@@ -125,7 +130,7 @@ export function experimental_createQueryPersister<TStorageValue = string>({
           } else {
             if (afterRestoreMacroTask) {
               // Just after restoring we want to get fresh data from the server if it's stale
-              setTimeout(() => afterRestoreMacroTask(persistedQuery), 0)
+              systemSetTimeoutZero(() => afterRestoreMacroTask(persistedQuery))
             }
             // We must resolve the promise here, as otherwise we will have `loading` state in the app until `queryFn` resolves
             return persistedQuery.state.data as T
@@ -213,9 +218,9 @@ export function experimental_createQueryPersister<TStorageValue = string>({
 
     if (matchesFilter && storage != null) {
       // Persist if we have storage defined, we use timeout to get proper state to be persisted
-      setTimeout(() => {
+      systemSetTimeoutZero(() => {
         persistQuery(query)
-      }, 0)
+      })
     }
 
     return Promise.resolve(queryFnResult)

packages/query-sync-storage-persister/src/index.ts

@@ -1,4 +1,6 @@
+import { managedSetTimeout } from '@tanstack/query-core'
 import { noop } from './utils'
+import type { ManagedTimerId } from '@tanstack/query-core'
 import type {
   PersistRetryer,
   PersistedClient,
@@ -100,12 +102,12 @@ function throttle<TArgs extends Array<any>>(
   func: (...args: TArgs) => any,
   wait = 100,
 ) {
-  let timer: ReturnType<typeof setTimeout> | null = null
+  let timer: ManagedTimerId | null = null
   let params: TArgs
   return function (...args: TArgs) {
     params = args
     if (timer === null) {
-      timer = setTimeout(() => {
+      timer = managedSetTimeout(() => {
         func(...params)
         timer = null
       }, wait)