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

docs/config.json

@@ -757,6 +757,10 @@
         {
           "label": "notifyManager",
           "to": "reference/notifyManager"
+        },
+        {
+          "label": "timeoutManager",
+          "to": "reference/timeoutManager"
         }
       ],
       "frameworks": [

docs/framework/react/plugins/persistQueryClient.md

@@ -21,7 +21,7 @@ It should be set as the same value or higher than persistQueryClient's `maxAge`
 
 You can also pass it `Infinity` to disable garbage collection behavior entirely.
 
-Due to a Javascript limitation, the maximum allowed `gcTime` is about 24 days (see [more](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value)).
+Due to a JavaScript limitation, the maximum allowed `gcTime` is about [24 days](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value), although it is possible to work around this limit using [timeoutManager.setTimeoutProvider](../../../../reference/timeoutManager.md#timeoutmanagersettimeoutprovider).
 
 ```tsx
 const queryClient = new QueryClient({

docs/framework/react/reference/useMutation.md

@@ -55,7 +55,7 @@ mutate(variables, {
 - `gcTime: number | Infinity`
   - The time in milliseconds that unused/inactive cache data remains in memory. When a mutation's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different cache times are specified, the longest one will be used.
   - If set to `Infinity`, will disable garbage collection
-  - Note: the maximum allowed time is about 24 days. See [more](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value).
+  - Note: the maximum allowed time is about [24 days](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value), although it is possible to work around this limit using [timeoutManager.setTimeoutProvider](../../../../reference/timeoutManager.md#timeoutmanagersettimeoutprovider).
 - `mutationKey: unknown[]`
   - Optional
   - A mutation key can be set to inherit defaults set with `queryClient.setMutationDefaults`.

docs/framework/react/reference/useQuery.md

@@ -101,7 +101,7 @@ const {
 - `gcTime: number | Infinity`
   - Defaults to `5 * 60 * 1000` (5 minutes) or `Infinity` during SSR
   - The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used.
-  - Note: the maximum allowed time is about 24 days. See [more](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value).
+  - Note: the maximum allowed time is about [24 days](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value), although it is possible to work around this limit using [timeoutManager.setTimeoutProvider](../../../../reference/timeoutManager.md#timeoutmanagersettimeoutprovider).
   - If set to `Infinity`, will disable garbage collection
 - `queryKeyHashFn: (queryKey: QueryKey) => string`
   - Optional

docs/framework/solid/reference/useQuery.md

@@ -223,7 +223,7 @@ function App() {
   - ##### `gcTime: number | Infinity`
     - Defaults to `5 * 60 * 1000` (5 minutes) or `Infinity` during SSR
     - The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used.
-    - Note: the maximum allowed time is about 24 days. See [more](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value).
+    - Note: the maximum allowed time is about [24 days](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value), although it is possible to work around this limit using [timeoutManager.setTimeoutProvider](../../../../reference/timeoutManager.md#timeoutmanagersettimeoutprovider).
     - If set to `Infinity`, will disable garbage collection
   - ##### `networkMode: 'online' | 'always' | 'offlineFirst`
     - optional

docs/reference/timeoutManager.md

@@ -0,0 +1,119 @@
+---
+id: TimeoutManager
+title: TimeoutManager
+---
+
+The `TimeoutManager` handles `setTimeout` and `setInterval` timers in TanStack Query.
+
+TanStack Query uses timers to implement features like query `staleTime` and `gcTime`, as well as retries, throttling, and debouncing.
+
+By default, TimeoutManager uses the global `setTimeout` and `setInterval`, but it can be configured to use custom implementations instead.
+
+Its available methods are:
+
+- [`timeoutManager.setTimeoutProvider`](#timeoutmanagersettimeoutprovider)
+  - [`TimeoutProvider`](#timeoutprovider)
+- [`timeoutManager.setTimeout`](#timeoutmanagersettimeout)
+- [`timeoutManager.clearTimeout`](#timeoutmanagercleartimeout)
+- [`timeoutManager.setInterval`](#timeoutmanagersetinterval)
+- [`timeoutManager.clearInterval`](#timeoutmanagerclearinterval)
+
+## `timeoutManager.setTimeoutProvider`
+
+`setTimeoutProvider` can be used to set a custom implementation of the `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` functions, called a `TimeoutProvider`.
+
+This may be useful if you notice event loop performance issues with thousands of queries. A custom TimeoutProvider could also support timer delays longer than the global `setTimeout` maximum delay value of about [24 days](https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout#maximum_delay_value).
+
+It is important to call `setTimeoutProvider` before creating a QueryClient or queries, so that the same provider is used consistently for all timers in the application, since different TimeoutProviders cannot cancel each others' timers.
+
+```tsx
+import { timeoutManager, QueryClient } from '@tanstack/react-query'
+import { CustomTimeoutProvider } from './CustomTimeoutProvider'
+
+timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())
+
+export const queryClient = new QueryClient()
+```
+
+### `TimeoutProvider`
+
+Timers are very performance sensitive. Short term timers (such as those with delays less than 5 seconds) tend to be latency sensitive, where long-term timers may benefit more from [timer coalescing](https://en.wikipedia.org/wiki/Timer_coalescing) - batching timers with similar deadlines together - using a data structure like a [hierarchical time wheel](https://www.npmjs.com/package/timer-wheel).
+
+The `TimeoutProvider` type requires that implementations handle timer ID objects that can be converted to `number` via [Symbol.toPrimitive][toPrimitive] because runtimes like NodeJS return [objects][nodejs-timeout] from their global `setTimeout` and `setInterval` functions. TimeoutProvider implementations are free to coerce timer IDs to number internally, or to return their own custom object type that implements `{ [Symbol.toPrimitive]: () => number }`.
+
+[nodejs-timeout]: https://nodejs.org/api/timers.html#class-timeout
+[toPrimitive]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive
+
+```tsx
+type ManagedTimerId = number | { [Symbol.toPrimitive]: () => number }
+
+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
+}
+```
+
+## `timeoutManager.setTimeout`
+
+`setTimeout(callback, delayMs)` schedules a callback to run after approximately `delay` milliseconds, like the global [setTimeout function](https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout).The callback can be canceled with `timeoutManager.clearTimeout`.
+
+It returns a timer ID, which may be a number or an object that can be coerced to a number via [Symbol.toPrimitive][toPrimitive].
+
+```tsx
+import { timeoutManager } from '@tanstack/react-query'
+
+const timeoutId = timeoutManager.setTimeout(
+  () => console.log('ran at:', new Date()),
+  1000,
+)
+
+const timeoutIdNumber: number = Number(timeoutId)
+```
+
+## `timeoutManager.clearTimeout`
+
+`clearTimeout(timerId)` cancels a timeout callback scheduled with `setTimeout`, like the global [clearTimeout function](https://developer.mozilla.org/en-US/docs/Web/API/Window/clearTimeout). It should be called with a timer ID returned by `timeoutManager.setTimeout`.
+
+```tsx
+import { timeoutManager } from '@tanstack/react-query'
+
+const timeoutId = timeoutManager.setTimeout(
+  () => console.log('ran at:', new Date()),
+  1000,
+)
+
+timeoutManager.clearTimeout(timeoutId)
+```
+
+## `timeoutManager.setInterval`
+
+`setInterval(callback, intervalMs)` schedules a callback to be called approximately every `intervalMs`, like the global [setInterval function](https://developer.mozilla.org/en-US/docs/Web/API/Window/setInterval).
+
+Like `setTimeout`, it returns a timer ID, which may be a number or an object that can be coerced to a number via [Symbol.toPrimitive](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive).
+
+```tsx
+import { timeoutManager } from '@tanstack/react-query'
+
+const intervalId = timeoutManager.setInterval(
+  () => console.log('ran at:', new Date()),
+  1000,
+)
+```
+
+## `timeoutManager.clearInterval`
+
+`clearInterval(intervalId)` can be used to cancel an interval, like the global [clearInterval function](https://developer.mozilla.org/en-US/docs/Web/API/Window/clearInterval). It should be called with an interval ID returned by `timeoutManager.setInterval`.
+
+```tsx
+import { timeoutManager } from '@tanstack/react-query'
+
+const intervalId = timeoutManager.setInterval(
+  () => console.log('ran at:', new Date()),
+  1000,
+)
+
+timeoutManager.clearInterval(intervalId)
+```

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)
+      })
+    })
+  })
+})