feat(utils): add cancel support to debounce and debounceSync

ahmadnasriya · ahmadnasriya · commit 3e1c6c60a41b · 2025-07-15T14:06:27.000+03:00
- Added `.cancel()` method to both `debounce` and `debounceSync` to allow cancelling scheduled executions
- Updated README examples and API table to reflect the new behavior and document usage
- Exposed a `dispose()` method on the EventEmitter to clean up internal timers (e.g. debounced warnings)
diff --git a/examples/utils.md b/examples/utils.md
@@ -11,14 +11,16 @@ const utils = atomix.utils;
 
 ---
 ## The APIs
-| API                                | Description                                                       |
-| ---------------------------------- | ----------------------------------------------------------------- |
-| [generateRandom](#-generaterandom) | Generate customizable random strings with optional character sets |
-| [sleep](#-sleep)                   | Pause execution for a specified time using a Promise              |
-| [debounce](#-debounce)             | Delay function execution until no calls occur for a set time      |
-| [throttle](#-throttle)             | Limit function calls to at most once per specified delay          |
-| [once](#-once)                     | Ensure a function can only be executed a single time              |
-| [noop](#-noop)                     | A function that performs no operation (no-op)                     |
+| API                                | Description                                                          |
+| ---------------------------------- | -------------------------------------------------------------------- |
+| [generateRandom](#-generaterandom) | Generate customizable random strings with optional character sets    |
+| [sleep](#-sleep)                   | Pause execution for a specified time using a Promise                 |
+| [debounce](#-debounce)             | Delay async function execution until no calls occur for a set time   |
+| [debounceSync](#-debouncesync)     | Delay synchronous function calls until no calls occur for a set time |
+| [throttle](#-throttle)             | Limit function calls to at most once per specified delay             |
+| [once](#-once)                     | Ensure a function can only be executed a single time                 |
+| [noop](#-noop)                     | A function that performs no operation (no-op)                        |
+
 
 
 ---
@@ -54,18 +56,63 @@ await utils.sleep(1500);
 ### 🌀 `debounce`
 Signature: `debounce(fn, delay)`
 
-Delay execution until no calls have occurred within the specified delay.
+Delays execution of `fn` until no calls have occurred within the specified delay. Returns a debounced function that returns a Promise resolving to the result of `fn`.
+
+**Usage Example:**
+```ts
+const debouncedLog = utils.debounce((msg: string) => {
+    console.log('Debounced:', msg);
+    return msg.length;
+}, 1000);
+
+debouncedLog('Hello');
+debouncedLog('World').then(length => {
+    console.log(`Last message length: ${length}`);
+});
+```
+
+**Canceling a Pending Call:**
 
+Delays execution of a synchronous function `fn` until no calls have occurred within the specified delay. Returns a debounced function with a `.cancel()` method.
+
+**Usage Example:**
 ```ts
 const debouncedLog = utils.debounce((msg) => {
   console.log('Debounced:', msg);
 }, 1000);
 
 debouncedLog('Hello');
-debouncedLog('World');
+debouncedLog.cancel(); // Cancel the pending call; promise from last call rejects
+```
+
+### 🌀 `debounceSync`
+Signature: `debounceSync(fn, delay)`
+
+Delays execution of `fn` until no calls have occurred within the specified delay. Returns a debounced function that returns a Promise resolving to the result of `fn`.
+
+```ts
+const debouncedLog = utils.debounceSync((msg: string) => {
+  console.log('Debounced:', msg);
+}, 1000);
+
+debouncedLog('Hello');
+debouncedLog('World'); 
 // Only logs "Debounced: World" after 1 second
 ```
 
+**Canceling a Pending Call:**
+
+The returned debounced function includes a `.cancel()` method to cancel any pending invocation before it happens.
+
+```ts
+const debouncedLog = utils.debounceSync((msg) => {
+  console.log('Debounced:', msg);
+}, 1000);
+
+debouncedLog('Hello');
+debouncedLog.cancel(); // Cancel the pending call silently, no log will happen
+```
+
 ### 🚦 `throttle`
 Signature: `throttle(fn, delay)`
 
diff --git a/src/domains/utils/utils.ts b/src/domains/utils/utils.ts
@@ -70,24 +70,29 @@ class CommonUtils {
     }
 
     /**
-     * Returns a debounced version of the given function.
+     * Debounces a function, delaying its invocation until the specified delay
+     * period has passed since the last call.
      *
-     * When the given function is called, it will wait the specified delay before
-     * actually calling the function. If the function is called multiple times
-     * within that delay, it will only call the function once after the delay
-     * has passed.
+     * The debounced function returns a promise that resolves with the result
+     * of the original function. If the debounced function is called again
+     * before the delay period has passed, the previous promise is rejected
+     * with an error and a new promise is returned.
+     *
+     * The debounced function also has a `cancel` method that can be called to
+     * cancel the current pending invocation. If called, the promise is rejected
+     * with an error and the timer is cleared.
      *
      * @param fn - The function to debounce.
-     * @param delay - The number of milliseconds to delay calling the function.
-     * @returns A debounced version of the given function that returns a promise.
+     * @param delay - The number of milliseconds to delay the invocation of the function.
+     * @returns A debounced version of the given function.
      * @since v1.0.0
      */
     debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => Promise<ReturnType<T>> {
         let timeout: NodeJS.Timeout | null = null;
         let resolveFn: ((value: any) => void) | null = null;
         let rejectFn: ((reason?: any) => void) | null = null;
 
-        return (...args: Parameters<T>) => {
+        const debounced = (...args: Parameters<T>) => {
             if (timeout) clearTimeout(timeout);
 
             return new Promise<ReturnType<T>>((resolve, reject) => {
@@ -103,6 +108,19 @@ class CommonUtils {
                 }, delay);
             });
         };
+
+        debounced.cancel = () => {
+            if (timeout) {
+                clearTimeout(timeout);
+                timeout = null;
+                // Reject the pending Promise if any
+                rejectFn?.(new Error('Debounced function cancelled'));
+                resolveFn = null;
+                rejectFn = null;
+            }
+        };
+
+        return debounced;
     }
 
     /**
@@ -128,7 +146,7 @@ class CommonUtils {
     ): (...args: Parameters<T>) => void {
         let timeout: ReturnType<typeof setTimeout> | null = null;
 
-        return (...args: Parameters<T>) => {
+        const debounced = (...args: Parameters<T>) => {
             if (timeout) clearTimeout(timeout);
 
             timeout = setTimeout(() => {
@@ -139,7 +157,16 @@ class CommonUtils {
                     options?.onError?.(error);
                 }
             }, delay);
-        };
+        }
+
+        debounced.cancel = () => {
+            if (timeout) {
+                clearTimeout(timeout);
+                timeout = null;
+            }
+        }
+
+        return debounced;
     }
 
     /**
diff --git a/src/tools/events/EventEmitter.ts b/src/tools/events/EventEmitter.ts
@@ -298,6 +298,25 @@ export class EventEmitter {
         return this
     }
 
+    /**
+     * Cleans up any internal resources used by this instance.
+     * 
+     * Specifically, cancels any pending debounced handlers (such as
+     * warnings about maximum handlers) to prevent timers from
+     * keeping the process alive or causing side effects after disposal.
+     * 
+     * This method should be called when the instance is no longer needed,
+     * such as during test teardown or object cleanup.
+     * 
+     * @since v1.0.15
+     */
+    dispose() {
+        const { builtInHandler, customHandler } = this.#_helpers.onMaxHandlers;
+        (builtInHandler as any)?.cancel();
+        if (typeof customHandler !== 'function') { return }
+        (customHandler as any)?.cancel();
+    }
+
     /**
      * Retrieves the maximum number of event handlers allowed for this EventEmitter instance.
      * 
