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

packages/query-async-storage-persister/package.json

@@ -59,6 +59,7 @@
     "!src/__tests__"
   ],
   "dependencies": {
+    "@tanstack/query-core": "workspace:*",
     "@tanstack/query-persist-client-core": "workspace:*"
   },
   "devDependencies": {

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

@@ -1,3 +1,4 @@
+import { timeoutManager } from '@tanstack/query-core'
 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) => timeoutManager.setTimeout(done, interval))
     }
     while (Date.now() < nextExecutionTime) {
       await new Promise((done) =>
-        setTimeout(done, nextExecutionTime - Date.now()),
+        timeoutManager.setTimeout(done, nextExecutionTime - Date.now()),
       )
     }
     isScheduled = false

packages/query-core/src/__tests__/timeoutManager.test.tsx

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  TimeoutManager,
+  defaultTimeoutProvider,
+  systemSetTimeoutZero,
+  timeoutManager,
+} from '../timeoutManager'
+
+describe('timeoutManager', () => {
+  function createMockProvider(name: string = 'custom') {
+    return {
+      __TEST_ONLY__name: name,
+      setTimeout: vi.fn(() => 123),
+      clearTimeout: vi.fn(),
+      setInterval: vi.fn(() => 456),
+      clearInterval: vi.fn(),
+    }
+  }
+
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    consoleErrorSpy = vi.spyOn(console, 'error')
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('TimeoutManager', () => {
+    let manager: TimeoutManager
+
+    beforeEach(() => {
+      manager = new TimeoutManager()
+    })
+
+    it('by default proxies calls to globalThis setTimeout/clearTimeout', () => {
+      const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout')
+      const clearTimeoutSpy = vi.spyOn(globalThis, 'clearTimeout')
+      const setIntervalSpy = vi.spyOn(globalThis, 'setInterval')
+      const clearIntervalSpy = vi.spyOn(globalThis, 'clearInterval')
+
+      const callback = vi.fn()
+      const timeoutId = manager.setTimeout(callback, 100)
+      expect(setTimeoutSpy).toHaveBeenCalledWith(callback, 100)
+      clearTimeout(Number(timeoutId))
+
+      manager.clearTimeout(200)
+      expect(clearTimeoutSpy).toHaveBeenCalledWith(200)
+
+      const intervalId = manager.setInterval(callback, 300)
+      expect(setIntervalSpy).toHaveBeenCalledWith(callback, 300)
+      clearInterval(Number(intervalId))
+
+      manager.clearInterval(400)
+      expect(clearIntervalSpy).toHaveBeenCalledWith(400)
+    })
+
+    describe('setTimeoutProvider', () => {
+      it('proxies calls to the configured timeout provider', () => {
+        const customProvider = createMockProvider()
+        manager.setTimeoutProvider(customProvider)
+
+        const callback = vi.fn()
+
+        manager.setTimeout(callback, 100)
+        expect(customProvider.setTimeout).toHaveBeenCalledWith(callback, 100)
+
+        manager.clearTimeout(999)
+        expect(customProvider.clearTimeout).toHaveBeenCalledWith(999)
+
+        manager.setInterval(callback, 200)
+        expect(customProvider.setInterval).toHaveBeenCalledWith(callback, 200)
+
+        manager.clearInterval(888)
+        expect(customProvider.clearInterval).toHaveBeenCalledWith(888)
+      })
+
+      it('warns when switching providers after making call', () => {
+        // 1. switching before making any calls does not warn
+        const customProvider = createMockProvider()
+        manager.setTimeoutProvider(customProvider)
+        expect(consoleErrorSpy).not.toHaveBeenCalled()
+
+        // Make a call. The next switch should warn
+        manager.setTimeout(vi.fn(), 100)
+
+        // 2. switching after making a call should warn
+        const customProvider2 = createMockProvider('custom2')
+        manager.setTimeoutProvider(customProvider2)
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          expect.stringMatching(
+            /\[timeoutManager\]: Switching .* might result in unexpected behavior\..*/,
+          ),
+          expect.anything(),
+        )
+
+        // 3. Switching again with no intermediate calls should not warn
+        vi.mocked(consoleErrorSpy).mockClear()
+        const customProvider3 = createMockProvider('custom3')
+        manager.setTimeoutProvider(customProvider3)
+        expect(consoleErrorSpy).not.toHaveBeenCalled()
+      })
+    })
+  })
+
+  describe('globalThis timeoutManager instance', () => {
+    it('should be an instance of TimeoutManager', () => {
+      expect(timeoutManager).toBeInstanceOf(TimeoutManager)
+    })
+  })
+
+  describe('exported functions', () => {
+    let provider: ReturnType<typeof createMockProvider>
+    beforeEach(() => {
+      provider = createMockProvider()
+      timeoutManager.setTimeoutProvider(provider)
+    })
+    afterEach(() => {
+      timeoutManager.setTimeoutProvider(defaultTimeoutProvider)
+    })
+
+    describe('systemSetTimeoutZero', () => {
+      it('should use globalThis setTimeout with 0 delay', () => {
+        const spy = vi.spyOn(globalThis, 'setTimeout')
+
+        const callback = vi.fn()
+        systemSetTimeoutZero(callback)
+
+        expect(spy).toHaveBeenCalledWith(callback, 0)
+        clearTimeout(spy.mock.results[0]?.value)
+      })
+    })
+  })
+})

packages/query-core/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'

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,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> = []

packages/query-core/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
     }
   }

packages/query-core/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
     }
   }