fix(throttle, debounce): Fix throttle with edges: ['trailing'] behaving like debounce

Author: Seol-JY

src/function/debounce.ts

@@ -12,6 +12,13 @@ export interface DebounceOptions {
    * @default ["trailing"]
    */
   edges?: Array<'leading' | 'trailing'>;
+
+  /**
+   * The maximum time the function is allowed to be delayed before it is invoked.
+   * If provided, the function will be invoked at most once per `maxWait` milliseconds,
+   * even if the debounced function is called more frequently.
+   */
+  maxWait?: number;
 }
 
 export interface DebouncedFunction<F extends (...args: any[]) => void> {
@@ -49,7 +56,9 @@ export interface DebouncedFunction<F extends (...args: any[]) => void> {
  * @param {F} func - The function to debounce.
  * @param {number} debounceMs - The number of milliseconds to delay.
  * @param {DebounceOptions} options - The options object
- * @param {AbortSignal} options.signal - An optional AbortSignal to cancel the debounced function.
+ * @param {AbortSignal} [options.signal] - An optional AbortSignal to cancel the debounced function.
+ * @param {Array<'leading' | 'trailing'>} [options.edges] - An array specifying when the function should be invoked (leading edge, trailing edge, or both).
+ * @param {number} [options.maxWait] - The maximum time the function is allowed to be delayed before it is invoked.
  * @returns A new debounced function with a `cancel` method.
  *
  * @example
@@ -78,10 +87,11 @@ export interface DebouncedFunction<F extends (...args: any[]) => void> {
 export function debounce<F extends (...args: any[]) => void>(
   func: F,
   debounceMs: number,
-  { signal, edges }: DebounceOptions = {}
+  { signal, edges, maxWait }: DebounceOptions = {}
 ): DebouncedFunction<F> {
   let pendingThis: any = undefined;
   let pendingArgs: Parameters<F> | null = null;
+  let pendingAt: number | null = null;
 
   const leading = edges != null && edges.includes('leading');
   const trailing = edges == null || edges.includes('trailing');
@@ -95,6 +105,8 @@ export function debounce<F extends (...args: any[]) => void>(
   };
 
   const onTimerEnd = () => {
+    pendingAt = null;
+
     if (trailing) {
       invoke();
     }
@@ -127,6 +139,7 @@ export function debounce<F extends (...args: any[]) => void>(
     cancelTimer();
     pendingThis = undefined;
     pendingArgs = null;
+    pendingAt = null;
   };
 
   const flush = () => {
@@ -144,6 +157,20 @@ export function debounce<F extends (...args: any[]) => void>(
 
     const isFirstCall = timeoutId == null;
 
+    if (maxWait != null) {
+      if (pendingAt === null) {
+        pendingAt = Date.now();
+      }
+
+      if (Date.now() - pendingAt >= maxWait) {
+        pendingAt = Date.now();
+        func.apply(pendingThis, pendingArgs);
+        cancelTimer();
+        schedule();
+        return;
+      }
+    }
+
     schedule();
 
     if (leading && isFirstCall) {

src/function/throttle.spec.ts

@@ -166,4 +166,54 @@ describe('throttle', () => {
     await delay(throttleMs + 1);
     expect(capturedMsg).toBe('hello world');
   });
+
+  it('should invoke function periodically with trailing edge only', async () => {
+    const callback = vi.fn();
+    const throttleMs = 50;
+    const throttled = throttle(callback, throttleMs, { edges: ['trailing'] });
+
+    throttled();
+    expect(callback).toHaveBeenCalledTimes(0);
+
+    await delay(throttleMs + 1);
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    throttled();
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    await delay(throttleMs + 1);
+    expect(callback).toHaveBeenCalledTimes(2);
+  });
+
+  it('should invoke function periodically during continuous calls with trailing edge only', async () => {
+    const callback = vi.fn();
+    const throttleMs = 50;
+    const throttled = throttle(callback, throttleMs, { edges: ['trailing'] });
+
+    const intervalId = setInterval(() => {
+      throttled();
+    }, 10);
+
+    await delay(throttleMs * 3 + 10);
+    clearInterval(intervalId);
+
+    expect(callback.mock.calls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('should invoke function periodically with leading edge only', async () => {
+    const callback = vi.fn();
+    const throttleMs = 50;
+    const throttled = throttle(callback, throttleMs, { edges: ['leading'] });
+
+    throttled();
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    await delay(throttleMs / 2);
+    throttled();
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    await delay(throttleMs / 2 + 1);
+    throttled();
+    expect(callback).toHaveBeenCalledTimes(2);
+  });
 });

src/function/throttle.ts

@@ -53,25 +53,9 @@ export function throttle<F extends (...args: any[]) => void>(
   throttleMs: number,
   { signal, edges = ['leading', 'trailing'] }: ThrottleOptions = {}
 ): ThrottledFunction<F> {
-  let pendingAt: number | null = null;
-
-  const debounced = debounce(func, throttleMs, { signal, edges });
-
-  const throttled = function (this: any, ...args: Parameters<F>) {
-    if (pendingAt == null) {
-      pendingAt = Date.now();
-    } else {
-      if (Date.now() - pendingAt >= throttleMs) {
-        pendingAt = Date.now();
-        debounced.cancel();
-      }
-    }
-
-    debounced.apply(this, args);
-  };
-
-  throttled.cancel = debounced.cancel;
-  throttled.flush = debounced.flush;
-
-  return throttled;
+  return debounce(func, throttleMs, {
+    signal,
+    edges,
+    maxWait: throttleMs,
+  });
 }