feat: new Function - onTimeout

README.md

@@ -106,6 +106,7 @@ pnpm add @utopia-utils/dom
 * parseQuery: 解析 url query。[source](https://github.com/GreatAuk/utopia-utils/blob/main/packages/core/src/parseQuery.ts)
 * groupBy: 数组根据指定的 key 分组。[source](https://github.com/GreatAuk/utopia-utils/blob/main/packages/core/src/groupBy.ts)
 * arrLast: 获取数组最后一个元素。[source](https://github.com/GreatAuk/utopia-utils/blob/main/packages/core/src/arrLast.ts)
+* onTimeout: wrap for setTimeout, return a function to remove the timeout。[source](https://github.com/GreatAuk/utopia-utils/blob/main/packages/core/src/onTimeout.ts)
 ### 类型判断
 
 ```bash

packages/core/src/index.ts

@@ -25,6 +25,7 @@ export * from './objectKeys'
 export * from './omit'
 export * from './once'
 export * from './onlyResolvesLast'
+export * from './onTimeout'
 export * from './parseQuery'
 export * from './pick'
 export * from './pipe'

packages/core/src/onTimeout.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { onTimeout } from './onTimeout'
+
+describe('onTimeout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+  it('should execute the callback', () => {
+    const callback = vi.fn()
+    onTimeout(callback, 1000)
+    vi.runAllTimers()
+    expect(callback).toHaveBeenCalledOnce()
+  })
+  it('should call the callback after the timeout', () => {
+    const start = Date.now()
+    let end = 0
+    const callback = vi.fn(() => {
+      end = Date.now()
+    })
+    const timeout = 100
+    onTimeout(callback, timeout)
+    vi.runAllTimers()
+    expect(callback).toHaveBeenCalled()
+
+    const diff = end - start
+    expect(diff).toBeGreaterThanOrEqual(timeout)
+  })
+  it('should call the callback with the given arguments', async () => {
+    const callback = vi.fn()
+    const args = [1, 2, 3]
+    onTimeout(callback, 100, ...args)
+    vi.runAllTimers()
+    expect(callback).toHaveBeenCalledWith(...args)
+  })
+  it('return value:removeTimeout should remove the timeout', async () => {
+    const callback = vi.fn()
+    const timeout = 100
+    const start = Date.now()
+    const { removeTimeout } = onTimeout(callback, timeout)
+    removeTimeout()
+    vi.runAllTimers()
+    const end = Date.now()
+    expect(callback).not.toHaveBeenCalled()
+    expect(end - start).toBeLessThan(timeout)
+  })
+})

packages/core/src/onTimeout.ts

@@ -0,0 +1,33 @@
+interface ReturnType {
+  removeTimeout: () => void
+}
+
+/**
+ * wrap for setTimeout, return a function to remove the timeout
+ * @param callback equal to setTimeout's first param
+ * @param ms equal to setTimeout's second param
+ * @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/core/src/onTimeout.ts
+ * @example
+ * ```ts
+ * const { removeTimeout } = onTimeout(() => {
+ *  console.log('timeout')
+ * }, 1000) // print 'timeout' after 1s
+ *
+ * removeTimeout() // on Destroy, cancel the timeout
+ */
+export function onTimeout(callback: (args: void) => void, ms?: number): ReturnType
+export function onTimeout<TArgs extends any[]>(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs): ReturnType
+export function onTimeout<TArgs extends any[]>(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs) {
+  const timeoutId = setTimeout(
+    () => callback(...args),
+    ms,
+  )
+
+  const removeTimeout = () => {
+    clearTimeout(timeoutId)
+  }
+
+  return {
+    removeTimeout,
+  }
+}

packages/core/src/parseQuery.ts

@@ -14,7 +14,6 @@ const PLUS_RE = /\+/g // %2B
  *
  * @param text - string to decode
  * @returns decoded string
- * @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/core/src/parseQuery.ts
  */
 export function decode(text: string | number): string {
   try {
@@ -33,6 +32,7 @@ export function decode(text: string | number): string {
  *
  * @param search - search string to parse
  * @returns a query object
+ * @linkcode https://github.com/GreatAuk/utopia-utils/blob/main/packages/core/src/parseQuery.ts
  * @example
  * ```
     const params = parseQuery<{