feat(shared): Introduce TimerHandle for setTimeout type (#4801)

ilyaliao · web-flow · commit 319d821a658e · 2025-06-19T08:03:39.000Z
diff --git a/packages/core/onLongPress/index.ts b/packages/core/onLongPress/index.ts
@@ -1,3 +1,4 @@
+import type { TimerHandle } from '@vueuse/shared'
 import type { Position } from '../types'
 import type { MaybeElementRef } from '../unrefElement'
 import { computed } from 'vue'
@@ -48,7 +49,7 @@ export function onLongPress(
 ) {
   const elementRef = computed(() => unrefElement(target))
 
-  let timeout: ReturnType<typeof setTimeout> | undefined
+  let timeout: TimerHandle
   let posStart: Position | undefined
   let startTimestamp: number | undefined
   let hasLongPressed = false
diff --git a/packages/core/useElementHover/index.ts b/packages/core/useElementHover/index.ts
@@ -1,3 +1,4 @@
+import type { TimerHandle } from '@vueuse/shared'
 import type { MaybeRefOrGetter, ShallowRef } from 'vue'
 import type { ConfigurableWindow } from '../_configurable'
 import type { MaybeComputedElementRef } from '../unrefElement'
@@ -22,7 +23,7 @@ export function useElementHover(el: MaybeRefOrGetter<EventTarget | null | undefi
   } = options
 
   const isHovered = shallowRef(false)
-  let timer: ReturnType<typeof setTimeout> | undefined
+  let timer: TimerHandle
 
   const toggle = (entering: boolean) => {
     const delay = entering ? delayEnter : delayLeave
diff --git a/packages/core/useIdle/index.ts b/packages/core/useIdle/index.ts
@@ -1,4 +1,4 @@
-import type { ConfigurableEventFilter } from '@vueuse/shared'
+import type { ConfigurableEventFilter, TimerHandle } from '@vueuse/shared'
 import type { ShallowRef } from 'vue'
 import type { ConfigurableWindow } from '../_configurable'
 import type { WindowEventName } from '../useEventListener'
@@ -58,7 +58,7 @@ export function useIdle(
   const idle = shallowRef(initialState)
   const lastActive = shallowRef(timestamp())
 
-  let timer: any
+  let timer: TimerHandle
 
   const reset = () => {
     idle.value = false
diff --git a/packages/core/useWebSocket/index.ts b/packages/core/useWebSocket/index.ts
@@ -1,4 +1,4 @@
-import type { Fn } from '@vueuse/shared'
+import type { Fn, TimerHandle } from '@vueuse/shared'
 import type { MaybeRefOrGetter, Ref, ShallowRef } from 'vue'
 import { isClient, isWorker, toRef, tryOnScopeDispose, useIntervalFn } from '@vueuse/shared'
 import { ref as deepRef, shallowRef, toValue, watch } from 'vue'
@@ -183,8 +183,8 @@ export function useWebSocket<Data = any>(
 
   let bufferedData: (string | ArrayBuffer | Blob)[] = []
 
-  let retryTimeout: ReturnType<typeof setTimeout> | undefined
-  let pongTimeoutWait: ReturnType<typeof setTimeout> | undefined
+  let retryTimeout: TimerHandle
+  let pongTimeoutWait: TimerHandle
 
   const _sendBuffer = () => {
     if (bufferedData.length && wsRef.value && status.value === 'OPEN') {
diff --git a/packages/shared/refAutoReset/index.ts b/packages/shared/refAutoReset/index.ts
@@ -1,4 +1,5 @@
 import type { MaybeRefOrGetter, Ref } from 'vue'
+import type { TimerHandle } from '../utils'
 import { customRef, toValue } from 'vue'
 import { tryOnScopeDispose } from '../tryOnScopeDispose'
 
@@ -14,7 +15,7 @@ export type RefAutoResetReturn<T = any> = Ref<T>
 export function refAutoReset<T>(defaultValue: MaybeRefOrGetter<T>, afterMs: MaybeRefOrGetter<number> = 10000): RefAutoResetReturn<T> {
   return customRef<T>((track, trigger) => {
     let value: T = toValue(defaultValue)
-    let timer: any
+    let timer: TimerHandle
 
     const resetAfter = () =>
       setTimeout(() => {
diff --git a/packages/shared/useTimeoutFn/index.ts b/packages/shared/useTimeoutFn/index.ts
@@ -1,5 +1,5 @@
 import type { MaybeRefOrGetter } from 'vue'
-import type { AnyFn, Stoppable } from '../utils'
+import type { AnyFn, Stoppable, TimerHandle } from '../utils'
 import { shallowReadonly, shallowRef, toValue } from 'vue'
 import { tryOnScopeDispose } from '../tryOnScopeDispose'
 import { isClient } from '../utils'
@@ -41,12 +41,12 @@ export function useTimeoutFn<CallbackFn extends AnyFn>(
 
   const isPending = shallowRef(false)
 
-  let timer: ReturnType<typeof setTimeout> | null = null
+  let timer: TimerHandle
 
   function clear() {
     if (timer) {
       clearTimeout(timer)
-      timer = null
+      timer = undefined
     }
   }
 
@@ -62,7 +62,7 @@ export function useTimeoutFn<CallbackFn extends AnyFn>(
     isPending.value = true
     timer = setTimeout(() => {
       isPending.value = false
-      timer = null
+      timer = undefined
 
       cb(...args)
     }, toValue(interval))
diff --git a/packages/shared/utils/filters.ts b/packages/shared/utils/filters.ts
@@ -1,5 +1,5 @@
 import type { MaybeRefOrGetter } from 'vue'
-import type { AnyFn, ArgumentsType, Awaited, Pausable, Promisify } from './types'
+import type { AnyFn, ArgumentsType, Awaited, Pausable, Promisify, TimerHandle } from './types'
 import { isRef, readonly, toValue } from 'vue'
 import { toRef } from '../toRef'
 import { noop } from './is'
@@ -65,11 +65,11 @@ export const bypassFilter: EventFilter = (invoke) => {
  * Create an EventFilter that debounce the events
  */
 export function debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFilterOptions = {}) {
-  let timer: ReturnType<typeof setTimeout> | undefined
-  let maxTimer: ReturnType<typeof setTimeout> | undefined | null
+  let timer: TimerHandle
+  let maxTimer: TimerHandle
   let lastRejector: AnyFn = noop
 
-  const _clearTimeout = (timer: ReturnType<typeof setTimeout>) => {
+  const _clearTimeout = (timer: TimerHandle) => {
     clearTimeout(timer)
     lastRejector()
     lastRejector = noop
@@ -87,7 +87,7 @@ export function debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFi
     if (duration <= 0 || (maxDuration !== undefined && maxDuration <= 0)) {
       if (maxTimer) {
         _clearTimeout(maxTimer)
-        maxTimer = null
+        maxTimer = undefined
       }
       return Promise.resolve(invoke())
     }
@@ -100,7 +100,7 @@ export function debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFi
         maxTimer = setTimeout(() => {
           if (timer)
             _clearTimeout(timer)
-          maxTimer = null
+          maxTimer = undefined
           resolve(lastInvoker())
         }, maxDuration)
       }
@@ -109,7 +109,7 @@ export function debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFi
       timer = setTimeout(() => {
         if (maxTimer)
           _clearTimeout(maxTimer)
-        maxTimer = null
+        maxTimer = undefined
         resolve(invoke())
       }, duration)
     })
@@ -150,7 +150,7 @@ export function throttleFilter(ms: MaybeRefOrGetter<number>, trailing?: boolean,
 export function throttleFilter(options: ThrottleFilterOptions): EventFilter
 export function throttleFilter(...args: any[]) {
   let lastExec = 0
-  let timer: ReturnType<typeof setTimeout> | undefined
+  let timer: TimerHandle
   let isLeading = true
   let lastRejector: AnyFn = noop
   let lastValue: any
diff --git a/packages/shared/utils/types.ts b/packages/shared/utils/types.ts
@@ -148,3 +148,8 @@ export type IfAny<T, Y, N> = 0 extends (1 & T) ? Y : N
  * will return `true` if `T` is `any`, or `false` otherwise
  */
 export type IsAny<T> = IfAny<T, true, false>
+
+/**
+ * Universal timer handle that works in both browser and Node.js environments
+ */
+export type TimerHandle = ReturnType<typeof setTimeout> | undefined
