feat: async debounce

Author: frodi-karlsson

packages/js-lib/src/decorators/asyncMemo.decorator.ts

@@ -2,8 +2,9 @@ import { _assert, _assertTypeOf } from '../error/assert.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import type { AnyAsyncFunction, AnyFunction, AnyObject, MaybeParameters } from '../types.js'
 import { _objectAssign, MISS } from '../types.js'
+import type { MethodDecorator } from './decorator.util.js'
 import { _getTargetMethodSignature } from './decorator.util.js'
-import type { AsyncMemoCache, MethodDecorator } from './memo.util.js'
+import type { AsyncMemoCache } from './memo.util.js'
 import { jsonMemoSerializer } from './memo.util.js'
 
 export interface AsyncMemoOptions<FN> {

packages/js-lib/src/decorators/debounce.decorator.test.ts

@@ -1,8 +1,8 @@
-import { test } from 'vitest'
+import { describe, expect, test } from 'vitest'
 import { _since } from '../datetime/index.js'
 import { pDelay } from '../promise/index.js'
 import type { AnyFunction, UnixTimestampMillis } from '../types.js'
-import { _Debounce } from './debounce.decorator.js'
+import { _AsyncDebounce, _AsyncThrottle, _Debounce } from './debounce.decorator.js'
 
 class C {
   // @debounce(200, {leading: true, trailing: true})
@@ -30,3 +30,41 @@ async function startTimer(fn: AnyFunction, interval: number, count: number): Pro
 test('@debounce', async () => {
   await startTimer(fn, 10, 10)
 })
+
+describe('@_AsyncDebounce', () => {
+  test('should coalesce calls and resolve every caller with a real result (never undefined)', async () => {
+    class C {
+      calls = 0
+
+      @_AsyncDebounce(20)
+      async save(n: number): Promise<number> {
+        this.calls++
+        return n
+      }
+    }
+
+    const inst = new C()
+    const results = await Promise.all([inst.save(1), inst.save(2), inst.save(3)])
+
+    expect(results).toEqual([3, 3, 3])
+    expect(inst.calls).toBe(1)
+  })
+})
+
+describe('@_AsyncThrottle', () => {
+  test('should invoke on the leading edge immediately', async () => {
+    class C {
+      calls = 0
+
+      @_AsyncThrottle(50)
+      async ping(n: number): Promise<number> {
+        this.calls++
+        return n
+      }
+    }
+
+    const inst = new C()
+    expect(await inst.ping(7)).toBe(7)
+    expect(inst.calls).toBe(1)
+  })
+})

packages/js-lib/src/decorators/debounce.decorator.ts

@@ -1,18 +1,61 @@
+import type { AnyAsyncFunction, AnyFunction } from '../types.js'
 import type { DebounceOptions, ThrottleOptions } from './debounce.js'
-import { _debounce, _throttle } from './debounce.js'
+import { _asyncDebounce, _asyncThrottle, _debounce, _throttle } from './debounce.js'
+import type { MethodDecorator } from './decorator.util.js'
 
-export function _Debounce(wait: number, opt: DebounceOptions = {}): MethodDecorator {
+export function _Debounce<T extends AnyFunction>(
+  wait: number,
+  opt: DebounceOptions = {},
+): MethodDecorator<T> {
   return (_target, _key, descriptor) => {
-    const originalFn = descriptor.value
-    descriptor.value = _debounce(originalFn as any, wait, opt)
+    const originalFn = descriptor.value!
+    descriptor.value = _debounce<T>(originalFn, wait, opt)
     return descriptor
   }
 }
 
-export function _Throttle(wait: number, opt: ThrottleOptions = {}): MethodDecorator {
+export function _Throttle<T extends AnyFunction>(
+  wait: number,
+  opt: ThrottleOptions = {},
+): MethodDecorator<T> {
   return (_target, _key, descriptor) => {
-    const originalFn = descriptor.value
-    descriptor.value = _throttle(originalFn as any, wait, opt)
+    const originalFn = descriptor.value!
+    descriptor.value = _throttle<T>(originalFn, wait, opt)
+    return descriptor
+  }
+}
+
+/**
+ * Like `@_Debounce`, but for async methods. Guarantees every call returns a real Promise that
+ * resolves (or rejects) with the coalesced invocation's result, so the declared `Promise<T>` return
+ * type stays accurate. Unlike `@_Debounce`, await`-ing a decorated method never silently yields
+ * `undefined`.
+ *
+ * @experimental
+ */
+export function _AsyncDebounce<T extends AnyAsyncFunction>(
+  wait: number,
+  opt: DebounceOptions = {},
+): MethodDecorator<T> {
+  return (_target, _key, descriptor) => {
+    const originalFn = descriptor.value!
+    descriptor.value = _asyncDebounce<T>(originalFn, wait, opt)
+    return descriptor
+  }
+}
+
+/**
+ * Like `@_Throttle`, but for async methods. See `@_AsyncDebounce` for the Promise semantics.
+ *
+ * @experimental
+ */
+export function _AsyncThrottle<T extends AnyAsyncFunction>(
+  wait: number,
+  opt: ThrottleOptions = {},
+): MethodDecorator<T> {
+  return (_target, _key, descriptor) => {
+    const originalFn = descriptor.value!
+    descriptor.value = _asyncThrottle<T>(originalFn, wait, opt)
     return descriptor
   }
 }

packages/js-lib/src/decorators/debounce.test.ts

@@ -1,8 +1,8 @@
-import { afterEach, test, vi } from 'vitest'
+import { afterEach, describe, expect, test, vi } from 'vitest'
 import { _since } from '../datetime/index.js'
 import { pDelay } from '../promise/index.js'
 import type { AnyFunction, UnixTimestampMillis } from '../types.js'
-import { _debounce } from './debounce.js'
+import { _asyncDebounce, _asyncThrottle, _debounce } from './debounce.js'
 
 afterEach(() => {
   vi.useRealTimers()
@@ -41,3 +41,64 @@ test('_debounce', async () => {
 // _throttle leading=1 trailing=0
 // _throttle leading=0 trailing=1
 // _throttle leading=0 trailing=0
+
+describe('_asyncDebounce', () => {
+  test('should return a real promise (never undefined) resolving with the invocation result', async () => {
+    let calls = 0
+    const fn = _asyncDebounce(async (n: number) => {
+      calls++
+      return n * 2
+    }, 20)
+
+    const p = fn(5)
+    expect(p).toBeInstanceOf(Promise)
+    expect(await p).toBe(10)
+    expect(calls).toBe(1)
+  })
+
+  test('should coalesce rapid calls into one invocation and resolve all callers with that result', async () => {
+    let calls = 0
+    const fn = _asyncDebounce(async (n: number) => {
+      calls++
+      return n
+    }, 20)
+
+    const results = await Promise.all([fn(1), fn(2), fn(3)])
+    expect(results).toEqual([3, 3, 3]) // trailing edge invokes with the last args
+    expect(calls).toBe(1)
+  })
+
+  test('should reject all coalesced callers when the invocation throws', async () => {
+    const fn = _asyncDebounce(async () => {
+      throw new Error('boom')
+    }, 20)
+
+    const p1 = fn()
+    const p2 = fn()
+
+    await expect(p1).rejects.toThrow('boom')
+    await expect(p2).rejects.toThrow('boom')
+  })
+
+  test('should reject pending promises on cancel()', async () => {
+    const fn = _asyncDebounce(async (n: number) => n, 50)
+
+    const p = fn(1)
+    fn.cancel()
+
+    await expect(p).rejects.toThrow('asyncDebounce cancelled')
+  })
+})
+
+describe('_asyncThrottle', () => {
+  test('should invoke on the leading edge immediately', async () => {
+    let calls = 0
+    const fn = _asyncThrottle(async (n: number) => {
+      calls++
+      return n
+    }, 50)
+
+    expect(await fn(7)).toBe(7)
+    expect(calls).toBe(1)
+  })
+})