timeoutManager

01무엇

timeoutManager는 TanStack Query가 내부에서 쓰는 setTimeout/setInterval을 감싸는 전역 매니저다. staleTime 판정, 가비지 컬렉션, 재시도, 스로틀링 같은 타이머 기반 동작이 전부 이걸 거친다.

import { timeoutManager } from '@tanstack/react-query'

02무슨 일이 일어나나

기본은 전역 setTimeout/setInterval을 그대로 쓴다. setTimeoutProvider로 커스텀 구현을 넣으면, 그 이후 만들어지는 타이머가 전부 그 구현을 탄다. QueryClient를 만들기 전에 설정해야 앱 전체에 일관되게 적용된다. 타이머 ID는 숫자가 아니어도 되고, Symbol.toPrimitive로 숫자를 반환하는 객체면 된다.

03사용법

커스텀 타이머 구현은 setTimeoutProvider로 주입한다. QueryClient를 만들기 전에 호출하는 게 중요하다.

import { timeoutManager, QueryClient } from '@tanstack/react-query'

timeoutManager.setTimeoutProvider({
  setTimeout: (callback, delay) => globalThis.setTimeout(callback, delay),
  clearTimeout: (id) => globalThis.clearTimeout(id),
  setInterval: (callback, delay) => globalThis.setInterval(callback, delay),
  clearInterval: (id) => globalThis.clearInterval(id),
})

export const queryClient = new QueryClient()

직접 스케줄링할 때는 setTimeout/setInterval을 그대로 쓴다.

const id = timeoutManager.setTimeout(() => console.log('실행됨'), 1000)
timeoutManager.clearTimeout(id)

04실무 예시

쿼리가 수천 개로 늘어나는 대시보드류 앱에서, 타이머를 코얼레싱(coalescing)하거나 표준 setTimeout의 지연 한도(약 24일)를 넘는 지연을 지원하는 구현으로 교체하는 정도가 실사용처다. 대부분의 앱에는 해당하지 않는다.

05왜 중요한가

거의 모든 앱은 기본 타이머로 충분하다. 이 매니저는 쿼리 수가 아주 많거나 표준 타이머의 한계에 부딪히는 극단적인 상황을 위한 확장 지점이다. 존재를 알아 두는 정도로 충분하고, 손댈 일은 드물다.

Reference