feat: support configurable scheduler for timed composables (#5129)

Author: 9romise

packages/core/_configurable.ts

@@ -1,3 +1,4 @@
+import type { Fn, Pausable } from '@vueuse/shared'
 import { isClient } from '@vueuse/shared'
 
 export interface ConfigurableWindow {
@@ -48,3 +49,10 @@ export interface ConfigurableDeepRefs<D extends boolean> {
    */
   deepRefs?: D
 }
+
+export interface ConfigurableScheduler {
+  /**
+   * Custom scheduler to use for interval execution.
+   */
+  scheduler?: (cb: Fn) => Pausable
+}

packages/core/useCountdown/index.md

@@ -4,7 +4,7 @@ category: Time
 
 # useCountdown
 
-Wrapper for `useIntervalFn` that provides a countdown timer.
+Reactive countdown timer in seconds.
 
 ## Usage
 

packages/core/useCountdown/index.ts

@@ -1,11 +1,27 @@
-import type { Pausable } from '@vueuse/shared'
+import type { AnyFn, Pausable } from '@vueuse/shared'
 import type { MaybeRefOrGetter, ShallowRef } from 'vue'
+import type { ConfigurableScheduler } from '../_configurable'
 import { useIntervalFn } from '@vueuse/shared'
 import { shallowRef, toValue } from 'vue'
 
-export interface UseCountdownOptions {
+function getDefaultScheduler(options: UseCountdownOptions) {
+  if ('interval' in options || 'immediate' in options) {
+    const {
+      interval = 1000,
+      immediate = false,
+    } = options
+
+    return (cb: AnyFn) => useIntervalFn(cb, interval, { immediate })
+  }
+
+  return (cb: AnyFn) => useIntervalFn(cb, 1000, { immediate: false })
+}
+
+export interface UseCountdownOptions extends ConfigurableScheduler {
   /**
    *  Interval for the countdown in milliseconds. Default is 1000ms.
+   *
+   * @deprecated Please use `scheduler` option instead
    */
   interval?: MaybeRefOrGetter<number>
   /**
@@ -19,6 +35,7 @@ export interface UseCountdownOptions {
   /**
    * Start the countdown immediately
    *
+   * @deprecated Please use `scheduler` option instead
    * @default false
    */
   immediate?: boolean
@@ -44,55 +61,61 @@ export interface UseCountdownReturn extends Pausable {
 }
 
 /**
- * Wrapper for `useIntervalFn` that provides a countdown timer in seconds.
+ * Reactive countdown timer in seconds.
  *
  * @param initialCountdown
  * @param options
  *
  * @see https://vueuse.org/useCountdown
  */
-export function useCountdown(initialCountdown: MaybeRefOrGetter<number>, options?: UseCountdownOptions): UseCountdownReturn {
+export function useCountdown(initialCountdown: MaybeRefOrGetter<number>, options: UseCountdownOptions = {}): UseCountdownReturn {
   const remaining = shallowRef(toValue(initialCountdown))
 
-  const intervalController = useIntervalFn(() => {
+  const {
+    scheduler = getDefaultScheduler(options),
+    onTick,
+    onComplete,
+  } = options
+
+  const controls = scheduler(() => {
     const value = remaining.value - 1
     remaining.value = value < 0 ? 0 : value
-    options?.onTick?.()
+    onTick?.()
     if (remaining.value <= 0) {
-      intervalController.pause()
-      options?.onComplete?.()
+      controls.pause()
+      onComplete?.()
     }
-  }, options?.interval ?? 1000, { immediate: options?.immediate ?? false })
+  })
 
   const reset = (countdown?: MaybeRefOrGetter<number>) => {
     remaining.value = toValue(countdown) ?? toValue(initialCountdown)
   }
 
   const stop = () => {
-    intervalController.pause()
+    controls.pause()
     reset()
   }
 
   const resume = () => {
-    if (!intervalController.isActive.value) {
+    if (!controls.isActive.value) {
       if (remaining.value > 0) {
-        intervalController.resume()
+        controls.resume()
       }
     }
   }
 
   const start = (countdown?: MaybeRefOrGetter<number>) => {
     reset(countdown)
-    intervalController.resume()
+    controls.resume()
   }
 
   return {
     remaining,
     reset,
     stop,
     start,
-    pause: intervalController.pause,
+    pause: controls.pause,
     resume,
-    isActive: intervalController.isActive,
+    isActive: controls.isActive,
   }
 }

packages/core/useElementByPoint/index.ts

@@ -1,17 +1,34 @@
-import type { Pausable } from '@vueuse/shared'
+import type { AnyFn, Pausable } from '@vueuse/shared'
 import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue'
-import type { ConfigurableDocument } from '../_configurable'
+import type { ConfigurableDocument, ConfigurableScheduler } from '../_configurable'
 import { useIntervalFn } from '@vueuse/shared'
 import { shallowRef, toValue } from 'vue'
 import { defaultDocument } from '../_configurable'
 import { useRafFn } from '../useRafFn'
 import { useSupported } from '../useSupported'
 
-export interface UseElementByPointOptions<Multiple extends boolean = false> extends ConfigurableDocument {
+function getDefaultScheduler(options: UseElementByPointOptions<boolean>) {
+  if ('interval' in options || 'immediate' in options) {
+    const {
+      interval = 'requestAnimationFrame',
+      immediate = true,
+    } = options
+
+    return interval === 'requestAnimationFrame'
+      ? (cb: AnyFn) => useRafFn(cb, { immediate })
+      : (cb: AnyFn) => useIntervalFn(cb, interval, { immediate })
+  }
+
+  return useRafFn
+}
+
+export interface UseElementByPointOptions<Multiple extends boolean = false> extends ConfigurableDocument, ConfigurableScheduler {
   x: MaybeRefOrGetter<number>
   y: MaybeRefOrGetter<number>
   multiple?: MaybeRefOrGetter<Multiple>
+  /** @deprecated Please use `scheduler` option instead */
   immediate?: boolean
+  /** @deprecated Please use `scheduler` option instead */
   interval?: 'requestAnimationFrame' | number
 }
 
@@ -32,8 +49,7 @@ export function useElementByPoint<M extends boolean = false>(options: UseElement
     y,
     document = defaultDocument,
     multiple,
-    interval = 'requestAnimationFrame',
-    immediate = true,
+    scheduler = getDefaultScheduler(options),
   } = options
 
   const isSupported = useSupported(() => {
@@ -45,15 +61,11 @@ export function useElementByPoint<M extends boolean = false>(options: UseElement
 
   const element = shallowRef<any>(null)
 
-  const cb = () => {
+  const controls = scheduler(() => {
     element.value = toValue(multiple)
       ? document?.elementsFromPoint(toValue(x), toValue(y)) ?? []
       : document?.elementFromPoint(toValue(x), toValue(y)) ?? null
-  }
-
-  const controls: Pausable = interval === 'requestAnimationFrame'
-    ? useRafFn(cb, { immediate })
-    : useIntervalFn(cb, interval, { immediate })
+  })
 
   return {
     isSupported,

packages/core/useMemory/index.ts

@@ -1,8 +1,27 @@
-import type { UseIntervalFnOptions } from '@vueuse/shared'
+import type { AnyFn } from '@vueuse/shared'
+import type { ComputedRef, Ref } from 'vue'
+import type { ConfigurableScheduler } from '../_configurable'
 import { useIntervalFn } from '@vueuse/shared'
 import { ref as deepRef } from 'vue'
 import { useSupported } from '../useSupported'
 
+function getDefaultScheduler(options: UseMemoryOptions) {
+  if ('interval' in options || 'immediate' in options || 'immediateCallback' in options) {
+    const {
+      interval = 1000,
+      immediate,
+      immediateCallback,
+    } = options
+
+    return (cb: AnyFn) => useIntervalFn(cb, interval, {
+      immediate,
+      immediateCallback,
+    })
+  }
+
+  return useIntervalFn
+}
+
 /**
  * Performance.memory
  *
@@ -25,10 +44,32 @@ export interface MemoryInfo {
   [Symbol.toStringTag]: 'MemoryInfo'
 }
 
-export interface UseMemoryOptions extends UseIntervalFnOptions {
+export interface UseMemoryOptions extends ConfigurableScheduler {
+  /**
+   * Start the timer immediately
+   *
+   * @deprecated Please use `scheduler` option instead
+   * @default true
+   */
+  immediate?: boolean
+
+  /**
+   * Execute the callback immediately after calling `resume`
+   *
+   * @deprecated Please use `scheduler` option instead
+   * @default false
+   */
+  immediateCallback?: boolean
+
+  /** @deprecated Please use `scheduler` option instead */
   interval?: number
 }
 
+export interface UseMemoryReturn {
+  isSupported: ComputedRef<boolean>
+  memory: Ref<MemoryInfo | undefined>
+}
+
 type PerformanceMemory = Performance & {
   memory: MemoryInfo
 }
@@ -41,18 +82,19 @@ type PerformanceMemory = Performance & {
  *
  * @__NO_SIDE_EFFECTS__
  */
-export function useMemory(options: UseMemoryOptions = {}) {
+export function useMemory(options: UseMemoryOptions = {}): UseMemoryReturn {
   const memory = deepRef<MemoryInfo>()
   const isSupported = useSupported(() => typeof performance !== 'undefined' && 'memory' in performance)
 
   if (isSupported.value) {
-    const { interval = 1000 } = options
-    useIntervalFn(() => {
+    const {
+      scheduler = getDefaultScheduler,
+    } = options
+
+    scheduler(() => {
       memory.value = (performance as PerformanceMemory).memory
-    }, interval, { immediate: options.immediate, immediateCallback: options.immediateCallback })
+    })
   }
 
   return { isSupported, memory }
 }
-
-export type UseMemoryReturn = ReturnType<typeof useMemory>

packages/core/useNow/component.ts

@@ -25,6 +25,7 @@ export const UseNow = /* #__PURE__ */ defineComponent<
   {
     name: 'UseNow',
     props: [
+      'scheduler',
       'immediate',
       'interval',
     ],

packages/core/useNow/index.ts

@@ -1,10 +1,26 @@
-import type { Pausable } from '@vueuse/shared'
+import type { AnyFn, Pausable } from '@vueuse/shared'
 import type { Ref } from 'vue'
+import type { ConfigurableScheduler } from '../_configurable'
 import { useIntervalFn } from '@vueuse/shared'
 import { ref as deepRef } from 'vue'
 import { useRafFn } from '../useRafFn'
 
-export interface UseNowOptions<Controls extends boolean> {
+function getDefaultScheduler(options: UseNowOptions<boolean>) {
+  if ('interval' in options || 'immediate' in options) {
+    const {
+      interval = 'requestAnimationFrame',
+      immediate = true,
+    } = options
+
+    return interval === 'requestAnimationFrame'
+      ? (fn: AnyFn) => useRafFn(fn, { immediate })
+      : (fn: AnyFn) => useIntervalFn(fn, interval, options)
+  }
+
+  return useRafFn
+}
+
+export interface UseNowOptions<Controls extends boolean> extends ConfigurableScheduler {
   /**
    * Expose more controls
    *
@@ -15,13 +31,15 @@ export interface UseNowOptions<Controls extends boolean> {
   /**
    * Start the clock immediately
    *
+   * @deprecated Please use `scheduler` option instead
    * @default true
    */
   immediate?: boolean
 
   /**
    * Update interval in milliseconds, or use requestAnimationFrame
    *
+   * @deprecated Please use `scheduler` option instead
    * @default requestAnimationFrame
    */
   interval?: 'requestAnimationFrame' | number
@@ -49,17 +67,14 @@ export function useNow(options: UseNowOptions<true>): { now: Ref<Date> } & Pausa
 export function useNow(options: UseNowOptions<boolean> = {}) {
   const {
     controls: exposeControls = false,
-    interval = 'requestAnimationFrame',
-    immediate = true,
+    scheduler = getDefaultScheduler(options),
   } = options
 
   const now = deepRef(new Date())
 
   const update = () => now.value = new Date()
 
-  const controls: Pausable = interval === 'requestAnimationFrame'
-    ? useRafFn(update, { immediate })
-    : useIntervalFn(update, interval, { immediate })
+  const controls = scheduler(update)
 
   if (exposeControls) {
     return {