feat(useTimtoutFn,useTimeoutPoll): align behavior (#4543)

Author: ilyaliao

packages/core/useTimeoutPoll/index.test.ts

@@ -1,61 +1,52 @@
-import { describe, expect, it, vi } from 'vitest'
-import { effectScope, nextTick, ref } from 'vue'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { effectScope, ref } from 'vue'
 import { useTimeoutPoll } from '.'
 
 describe('useTimeoutPoll', () => {
-  vi.useFakeTimers()
-  function createTests(immediate: boolean) {
-    it(`supports reactive intervals when immediate is ${immediate}`, async () => {
-      const callback = vi.fn()
-      const interval = ref(0)
-      const { pause, resume } = useTimeoutPoll(callback, interval, { immediate })
-
-      if (!immediate)
-        resume()
-      expect(callback).toBeCalled()
-      pause()
-
-      interval.value = 10
-
-      resume()
-      callback.mockReset()
-      expect(callback).not.toBeCalled()
-      await vi.advanceTimersByTimeAsync(11)
-      expect(callback).toBeCalled()
-
-      callback.mockReset()
-      pause()
-      await vi.advanceTimersByTimeAsync(11)
-      expect(callback).not.toBeCalled()
-
-      resume()
-      expect(callback).toBeCalled()
-
-      callback.mockReset()
-      await vi.advanceTimersByTimeAsync(11)
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  it('basic pause/resume', async () => {
+    const callback = vi.fn()
+    const interval = ref(0)
+    const { pause, resume } = useTimeoutPoll(callback, interval)
+
+    await vi.advanceTimersByTimeAsync(1)
+    expect(callback).toBeCalled()
+    pause()
+    interval.value = 10
+
+    resume()
+    callback.mockReset()
+    vi.advanceTimersByTime(1)
+    expect(callback).not.toBeCalled()
+    vi.advanceTimersByTime(10)
+    expect(callback).toBeCalled()
+  })
+
+  it('pause/resume with immediateCallback', async () => {
+    const callback = vi.fn()
+    useTimeoutPoll(callback, 50, { immediateCallback: true })
+
+    expect(callback).toHaveBeenCalledTimes(1)
+
+    vi.advanceTimersByTime(100)
+    expect(callback).toHaveBeenCalledTimes(2)
+  })
+
+  it('pause/resume in scope', async () => {
+    const callback = vi.fn()
+    const interval = ref(0)
+    const scope = effectScope()
+    await scope.run(async () => {
+      useTimeoutPoll(callback, interval)
+      vi.advanceTimersByTime(1)
       expect(callback).toBeCalled()
     })
-
-    it(`should pause when scope dispose and immediate is ${immediate}`, async () => {
-      const callback = vi.fn()
-      const interval = ref(0)
-      const scope = effectScope()
-      await scope.run(async () => {
-        const { resume } = useTimeoutPoll(callback, interval, { immediate })
-
-        if (!immediate)
-          resume()
-        await nextTick()
-        expect(callback).toBeCalled()
-      })
-      callback.mockReset()
-      scope.stop()
-      interval.value = 10
-      await vi.advanceTimersByTimeAsync(11)
-      expect(callback).not.toBeCalled()
-    })
-  }
-
-  createTests(true)
-  createTests(false)
+    callback.mockClear()
+    await scope.stop()
+    vi.advanceTimersByTime(60)
+    expect(callback).toHaveBeenCalledTimes(0)
+  })
 })

packages/core/useTimeoutPoll/index.ts

@@ -2,16 +2,33 @@ import type { Awaitable, MaybeRefOrGetter, Pausable, UseTimeoutFnOptions } from
 import { isClient, tryOnScopeDispose, useTimeoutFn } from '@vueuse/shared'
 import { ref } from 'vue'
 
+export interface UseTimeoutPollOptions {
+  /**
+   * Start the timer immediately
+   *
+   * @default true
+   */
+  immediate?: boolean
+
+  /**
+   * Execute the callback immediately after calling `resume`
+   *
+   * @default false
+   */
+  immediateCallback?: boolean
+}
+
 export function useTimeoutPoll(
   fn: () => Awaitable<void>,
   interval: MaybeRefOrGetter<number>,
   options: UseTimeoutFnOptions = {},
 ): Pausable {
   const {
     immediate = true,
+    immediateCallback = false,
   } = options
 
-  const { start } = useTimeoutFn(loop, interval, { immediate: false })
+  const { start } = useTimeoutFn(loop, interval, { immediate })
 
   const isActive = ref(false)
 
@@ -26,7 +43,9 @@ export function useTimeoutPoll(
   function resume() {
     if (!isActive.value) {
       isActive.value = true
-      loop()
+      if (immediateCallback)
+        fn()
+      start()
     }
   }
 

packages/shared/useTimeoutFn/index.test.ts

@@ -6,12 +6,12 @@ describe('useTimeoutFn', () => {
   beforeEach(() => {
     vi.useFakeTimers()
   })
-  it('supports reactive intervals', async () => {
+
+  it('basic start/stop', async () => {
     const callback = vi.fn()
     const interval = ref(0)
     const { start } = useTimeoutFn(callback, interval)
 
-    start()
     vi.advanceTimersByTime(1)
     expect(callback).toBeCalled()
 
@@ -25,6 +25,16 @@ describe('useTimeoutFn', () => {
     expect(callback).toBeCalled()
   })
 
+  it('stop/start with immediateCallback', async () => {
+    const callback = vi.fn()
+    useTimeoutFn(callback, 50, { immediateCallback: true })
+
+    expect(callback).toHaveBeenCalledTimes(1)
+
+    vi.advanceTimersByTime(100)
+    expect(callback).toHaveBeenCalledTimes(2)
+  })
+
   it('supports getting pending status', async () => {
     const callback = vi.fn()
     const { start, isPending } = useTimeoutFn(callback, 0, { immediate: false })

packages/shared/useTimeoutFn/index.ts

@@ -5,11 +5,18 @@ import { isClient } from '../utils'
 
 export interface UseTimeoutFnOptions {
   /**
-   * Start the timer immediate after calling this function
+   * Start the timer immediately
    *
    * @default true
    */
   immediate?: boolean
+
+  /**
+   * Execute the callback immediately after calling `start`
+   *
+   * @default false
+   */
+  immediateCallback?: boolean
 }
 
 /**
@@ -26,6 +33,7 @@ export function useTimeoutFn<CallbackFn extends AnyFn>(
 ): Stoppable<Parameters<CallbackFn> | []> {
   const {
     immediate = true,
+    immediateCallback = false,
   } = options
 
   const isPending = ref(false)
@@ -45,6 +53,8 @@ export function useTimeoutFn<CallbackFn extends AnyFn>(
   }
 
   function start(...args: Parameters<CallbackFn> | []) {
+    if (immediateCallback)
+      cb()
     clear()
     isPending.value = true
     timer = setTimeout(() => {