@alwatr/debounce 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.1.1](https://github.com/Alwatr/nanolib/compare/@alwatr/debounce@1.1.0...@alwatr/debounce@1.1.1) (2025-09-15)
+
+### 🐛 Bug Fixes
+
+* bind flush method correctly in Debouncer and improve readability of invoke logic ([5ddb12c](https://github.com/Alwatr/nanolib/commit/5ddb12c7d5d6040edad0f37ae79b3f725481d1f7))
+
+## [1.1.0](https://github.com/Alwatr/nanolib/compare/@alwatr/debounce@1.0.1...@alwatr/debounce@1.1.0) (2025-09-14)
+
+### ✨ Features
+
+* add maxWait option to Debouncer for guaranteed execution ([a305a6e](https://github.com/Alwatr/nanolib/commit/a305a6e82f96feebe2e895cdd35676da0f8b79f6))
+
+### 🐛 Bug Fixes
+
+* bind flush method in constructor for correct context ([671315c](https://github.com/Alwatr/nanolib/commit/671315cdadab448df660ae53c973eb71d4124699))
+
+### 🔨 Code Refactoring
+
+* add missing type import for DebouncerConfig ([d0c5808](https://github.com/Alwatr/nanolib/commit/d0c5808f2b6eb6fe856f8a38f5a79d2c427cf928))
+* improve trigger logic and clean up documentation comments ([cce9162](https://github.com/Alwatr/nanolib/commit/cce9162f2ee1c1fa2978ba04cd1be2eac5302b9e))
+* simplify trailing call logic and ensure lastArgs are cleared after invocation ([e8f74da](https://github.com/Alwatr/nanolib/commit/e8f74da9660c0c44d2704eb863bb082bce9a5978))
+* streamline invoke logic and restore createDebouncer function ([9bdc412](https://github.com/Alwatr/nanolib/commit/9bdc4124cdea3b267c040ec770a002ed64a814ac))
+
 ## [1.0.1](https://github.com/Alwatr/nanolib/compare/@alwatr/debounce@1.0.0...@alwatr/debounce@1.0.1) (2025-09-14)
 
 ### 🔨 Code Refactoring

package/dist/debounce.d.ts

@@ -32,6 +32,7 @@ import type { DebouncerConfig } from './type.ts';
 export declare class Debouncer<F extends AnyFunction> {
     private readonly config__;
     private timerId__?;
+    private maxWaitTimerId__?;
     private lastArgs__?;
     constructor(config__: DebouncerConfig<F>);
     /**
@@ -102,32 +103,4 @@ export declare class Debouncer<F extends AnyFunction> {
      */
     private invoke__;
 }
-/**
- * Factory function for creating a Debouncer instance for better type inference.
- * @param config Configuration for the debouncer.
- *
- * @example
- * ```typescript
- * const debouncer = createDebouncer({
- *   func: (text: string) => console.log('Searching:', text),
- *   delay: 300,
- *   leading: false,
- *   trailing: true,
- * });
- *
- * // Debounce search input
- * debouncer.trigger('hello');
- * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms
- *
- * // With custom thisContext
- * const obj = { log: (msg: string) => console.log('Obj:', msg) };
- * const debouncerWithContext = createDebouncer({
- *   func: obj.log,
- *   thisContext: obj,
- *   delay: 200,
- * });
- * debouncerWithContext.trigger('test'); // Logs 'Obj: test'
- * ```
- */
-export declare function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F>;
 //# sourceMappingURL=debounce.d.ts.map

package/dist/debounce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../src/debounce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,WAAW;IAIvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAH5C,OAAO,CAAC,SAAS,CAAC,CAA0B;IAC5C,OAAO,CAAC,UAAU,CAAC,CAAgB;gBAEC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;IAIhE;;;OAGG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,OAAO,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAoB5C;;;;;;;;;;;;;;;OAeG;IACI,MAAM,IAAI,IAAI;IAOrB;;OAEG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;;;;;;;;;;;;OAiBG;IACI,KAAK,IAAI,IAAI;IAOpB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAMjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE/F"}
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../src/debounce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,WAAW;IAKvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ5C,OAAO,CAAC,SAAS,CAAC,CAA0B;IAC5C,OAAO,CAAC,gBAAgB,CAAC,CAA0B;IACnD,OAAO,CAAC,UAAU,CAAC,CAAgB;gBAEC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;IAIhE;;;OAGG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,OAAO,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAwB5C;;;;;;;;;;;;;;;OAeG;IACI,MAAM,IAAI,IAAI;IAUrB;;OAEG;IACH,OAAO,CAAC,SAAS;IAMjB;;;;;;;;;;;;;;;;;OAiBG;IACI,KAAK,IAAI,IAAI;IAOpB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAOjB"}

package/dist/main.cjs

@@ -1,4 +1,4 @@
-/* @alwatr/debounce v1.0.1 */
+/* @alwatr/debounce v1.1.1 */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -42,7 +42,7 @@ var Debouncer = class {
   /**
    * Triggers the debounced function with the stored `thisContext`.
    * @param args The arguments to pass to the `func`.
-   * 
+   *
    * @example
    * ```typescript
    * const debouncer = new Debouncer({
@@ -50,7 +50,7 @@ var Debouncer = class {
    *   delay: 500,
    * });
    * debouncer.trigger(42); // Logs after 500ms if not triggered again
-   * 
+   *
    * // Edge case: Rapid triggers only execute the last one
    * debouncer.trigger(1);
    * debouncer.trigger(2); // Only 2 will execute after delay
@@ -58,15 +58,19 @@ var Debouncer = class {
    */
   trigger(...args) {
     this.lastArgs__ = args;
-    const wasPending = this.isPending;
-    if (wasPending) {
+    const firstTrigger = !this.isPending;
+    if (firstTrigger) {
+      if (this.config__.maxWait) {
+        this.maxWaitTimerId__ = setTimeout(() => this.flush, this.config__.maxWait);
+      }
+      if (this.config__.leading === true) {
+        this.invoke__();
+      }
+    } else {
       clearTimeout(this.timerId__);
     }
-    if (this.config__.leading === true && !wasPending) {
-      this.invoke__();
-    }
     this.timerId__ = setTimeout(() => {
-      if (this.config__.trailing === true && wasPending) {
+      if (this.config__.trailing === true) {
         this.invoke__();
       }
       this.cleanup__();
@@ -75,7 +79,7 @@ var Debouncer = class {
   /**
    * Cancels any pending debounced execution and cleans up internal state.
    * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).
-   * 
+   *
    * @example
    * ```typescript
    * const debouncer = new Debouncer({
@@ -84,14 +88,17 @@ var Debouncer = class {
    * });
    * debouncer.trigger();
    * debouncer.cancel(); // Prevents execution
-   * 
+   *
    * // Note: After cancel, isPending becomes false
    * ```
    */
   cancel() {
-    if (this.isPending) {
+    if (this.timerId__) {
       clearTimeout(this.timerId__);
     }
+    if (this.maxWaitTimerId__) {
+      clearTimeout(this.maxWaitTimerId__);
+    }
     this.cleanup__();
   }
   /**
@@ -99,12 +106,13 @@ var Debouncer = class {
    */
   cleanup__() {
     delete this.timerId__;
+    delete this.maxWaitTimerId__;
     delete this.lastArgs__;
   }
   /**
    * Immediately executes the pending function if one exists.
    * Bypasses the delay and cleans up state. If no pending call, does nothing.
-   * 
+   *
    * @example
    * ```typescript
    * const debouncer = new Debouncer({
@@ -113,7 +121,7 @@ var Debouncer = class {
    * });
    * debouncer.trigger();
    * setTimeout(() => debouncer.flush(), 500); // Executes immediately
-   * 
+   *
    * // Edge case: Flush after cancel does nothing
    * debouncer.cancel();
    * debouncer.flush(); // No execution
@@ -121,9 +129,9 @@ var Debouncer = class {
    */
   flush() {
     if (this.isPending) {
-      this.cancel();
       this.invoke__();
     }
+    this.cancel();
   }
   /**
    * The core execution logic.
@@ -131,9 +139,12 @@ var Debouncer = class {
   invoke__() {
     if (this.lastArgs__) {
       this.config__.func.apply(this.config__.thisContext, this.lastArgs__);
+      this.lastArgs__ = void 0;
     }
   }
 };
+
+// src/main.ts
 function createDebouncer(config) {
   return new Debouncer(config);
 }

package/dist/main.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/main.ts", "../src/debounce.ts"],
-  "sourcesContent": ["export * from './debounce.js';\nexport type * from './type.js';\n", "import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n * \n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // Advanced: With leading edge\n * const leadingDebouncer = new Debouncer({\n *   func: () => console.log('Immediate and delayed'),\n *   delay: 500,\n *   leading: true,\n *   trailing: true,\n * });\n * leadingDebouncer.trigger(); // Logs immediately, then again after 500ms if not cancelled\n * ```\n */\nexport class Debouncer<F extends AnyFunction> {\n  private timerId__?: number | NodeJS.Timeout;\n  private lastArgs__?: Parameters<F>;\n\n  public constructor(private readonly config__: DebouncerConfig<F>) {\n    this.config__.trailing ??= true;\n  }\n\n  /**\n   * Checks if there is a pending execution scheduled.\n   * Returns true if a timer is active, indicating a debounced call is waiting.\n   */\n  public get isPending(): boolean {\n    return this.timerId__ !== undefined;\n  }\n\n  /**\n   * Triggers the debounced function with the stored `thisContext`.\n   * @param args The arguments to pass to the `func`.\n   * \n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: (value: number) => console.log('Value:', value),\n   *   delay: 500,\n   * });\n   * debouncer.trigger(42); // Logs after 500ms if not triggered again\n   * \n   * // Edge case: Rapid triggers only execute the last one\n   * debouncer.trigger(1);\n   * debouncer.trigger(2); // Only 2 will execute after delay\n   * ```\n   */\n  public trigger(...args: Parameters<F>): void {\n    this.lastArgs__ = args;\n    const wasPending = this.isPending;\n\n    if (wasPending) {\n      clearTimeout(this.timerId__!);\n    }\n\n    if (this.config__.leading === true && !wasPending) {\n      this.invoke__();\n    }\n\n    this.timerId__ = setTimeout(() => {\n      if (this.config__.trailing === true && wasPending) {\n        this.invoke__();\n      }\n      this.cleanup__();\n    }, this.config__.delay);\n  }\n\n  /**\n   * Cancels any pending debounced execution and cleans up internal state.\n   * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).\n   * \n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Executed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * debouncer.cancel(); // Prevents execution\n   * \n   * // Note: After cancel, isPending becomes false\n   * ```\n   */\n  public cancel(): void {\n    if (this.isPending) {\n      clearTimeout(this.timerId__!);\n    }\n    this.cleanup__();\n  }\n\n  /**\n   * Cleans up internal state by deleting timer and arguments.\n   */\n  private cleanup__(): void {\n    delete this.timerId__;\n    delete this.lastArgs__;\n  }\n\n  /**\n   * Immediately executes the pending function if one exists.\n   * Bypasses the delay and cleans up state. If no pending call, does nothing.\n   * \n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Flushed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * setTimeout(() => debouncer.flush(), 500); // Executes immediately\n   * \n   * // Edge case: Flush after cancel does nothing\n   * debouncer.cancel();\n   * debouncer.flush(); // No execution\n   * ```\n   */\n  public flush(): void {\n    if (this.isPending) {\n      this.cancel();\n      this.invoke__();\n    }\n  }\n\n  /**\n   * The core execution logic.\n   */\n  private invoke__(): void {\n    if (this.lastArgs__) {\n      // `thisContext` is now read directly from the stored config.\n      this.config__.func.apply(this.config__.thisContext, this.lastArgs__);\n    }\n  }\n}\n\n/**\n * Factory function for creating a Debouncer instance for better type inference.\n * @param config Configuration for the debouncer.\n * \n * @example\n * ```typescript\n * const debouncer = createDebouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // With custom thisContext\n * const obj = { log: (msg: string) => console.log('Obj:', msg) };\n * const debouncerWithContext = createDebouncer({\n *   func: obj.log,\n *   thisContext: obj,\n *   delay: 200,\n * });\n * debouncerWithContext.trigger('test'); // Logs 'Obj: test'\n * ```\n */\nexport function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F> {\n  return new Debouncer(config);\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgCO,IAAM,YAAN,MAAuC;AAAA,EAIrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,aAAa,KAAK;AAExB,QAAI,YAAY;AACd,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,QAAI,KAAK,SAAS,YAAY,QAAQ,CAAC,YAAY;AACjD,WAAK,SAAS;AAAA,IAChB;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,QAAQ,YAAY;AACjD,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAU;AAAA,IAC9B;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,OAAO;AACZ,WAAK,SAAS;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,KAAK,MAAM,KAAK,SAAS,aAAa,KAAK,UAAU;AAAA,IACrE;AAAA,EACF;AACF;AA6BO,SAAS,gBAAuC,QAA0C;AAC/F,SAAO,IAAI,UAAU,MAAM;AAC7B;",
+  "sourcesContent": ["import {Debouncer} from './debounce.js';\n\nimport type {DebouncerConfig} from './type.js';\n\nexport * from './debounce.js';\nexport type * from './type.js';\n\n/**\n * Factory function for creating a Debouncer instance for better type inference.\n * @param config Configuration for the debouncer.\n *\n * @example\n * ```typescript\n * const debouncer = createDebouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n *\n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n *\n * // With custom thisContext\n * const obj = { log: (msg: string) => console.log('Obj:', msg) };\n * const debouncerWithContext = createDebouncer({\n *   func: obj.log,\n *   thisContext: obj,\n *   delay: 200,\n * });\n * debouncerWithContext.trigger('test'); // Logs 'Obj: test'\n * ```\n */\nexport function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F> {\n  return new Debouncer(config);\n}\n", "import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n *\n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n *\n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n *\n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n *\n * // Advanced: With leading edge\n * const leadingDebouncer = new Debouncer({\n *   func: () => console.log('Immediate and delayed'),\n *   delay: 500,\n *   leading: true,\n *   trailing: true,\n * });\n * leadingDebouncer.trigger(); // Logs immediately, then again after 500ms if not cancelled\n * ```\n */\nexport class Debouncer<F extends AnyFunction> {\n  private timerId__?: number | NodeJS.Timeout;\n  private maxWaitTimerId__?: number | NodeJS.Timeout;\n  private lastArgs__?: Parameters<F>;\n\n  public constructor(private readonly config__: DebouncerConfig<F>) {\n    this.config__.trailing ??= true;\n  }\n\n  /**\n   * Checks if there is a pending execution scheduled.\n   * Returns true if a timer is active, indicating a debounced call is waiting.\n   */\n  public get isPending(): boolean {\n    return this.timerId__ !== undefined;\n  }\n\n  /**\n   * Triggers the debounced function with the stored `thisContext`.\n   * @param args The arguments to pass to the `func`.\n   *\n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: (value: number) => console.log('Value:', value),\n   *   delay: 500,\n   * });\n   * debouncer.trigger(42); // Logs after 500ms if not triggered again\n   *\n   * // Edge case: Rapid triggers only execute the last one\n   * debouncer.trigger(1);\n   * debouncer.trigger(2); // Only 2 will execute after delay\n   * ```\n   */\n  public trigger(...args: Parameters<F>): void {\n    this.lastArgs__ = args; // its an array even if triggered without any args\n    const firstTrigger = !this.isPending;\n\n    if (firstTrigger) {\n      if (this.config__.maxWait) {\n        this.maxWaitTimerId__ = setTimeout(() => this.flush, this.config__.maxWait);\n      }\n      if (this.config__.leading === true) {\n        this.invoke__();\n      }\n    }\n    else {\n      clearTimeout(this.timerId__!);\n    }\n\n    this.timerId__ = setTimeout(() => {\n      if (this.config__.trailing === true) {\n        this.invoke__();\n      }\n      this.cleanup__();\n    }, this.config__.delay);\n  }\n\n  /**\n   * Cancels any pending debounced execution and cleans up internal state.\n   * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).\n   *\n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Executed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * debouncer.cancel(); // Prevents execution\n   *\n   * // Note: After cancel, isPending becomes false\n   * ```\n   */\n  public cancel(): void {\n    if (this.timerId__) {\n      clearTimeout(this.timerId__);\n    }\n    if (this.maxWaitTimerId__) {\n      clearTimeout(this.maxWaitTimerId__);\n    }\n    this.cleanup__();\n  }\n\n  /**\n   * Cleans up internal state by deleting timer and arguments.\n   */\n  private cleanup__(): void {\n    delete this.timerId__;\n    delete this.maxWaitTimerId__;\n    delete this.lastArgs__;\n  }\n\n  /**\n   * Immediately executes the pending function if one exists.\n   * Bypasses the delay and cleans up state. If no pending call, does nothing.\n   *\n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Flushed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * setTimeout(() => debouncer.flush(), 500); // Executes immediately\n   *\n   * // Edge case: Flush after cancel does nothing\n   * debouncer.cancel();\n   * debouncer.flush(); // No execution\n   * ```\n   */\n  public flush(): void {\n    if (this.isPending) {\n      this.invoke__();\n    }\n    this.cancel();\n  }\n\n  /**\n   * The core execution logic.\n   */\n  private invoke__(): void {\n    if (this.lastArgs__) {\n      // only call if we have new args (skip trailing call if leading already called)\n      this.config__.func.apply(this.config__.thisContext, this.lastArgs__);\n      this.lastArgs__ = undefined;\n    }\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgCO,IAAM,YAAN,MAAuC;AAAA,EAKrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,eAAe,CAAC,KAAK;AAE3B,QAAI,cAAc;AAChB,UAAI,KAAK,SAAS,SAAS;AACzB,aAAK,mBAAmB,WAAW,MAAM,KAAK,OAAO,KAAK,SAAS,OAAO;AAAA,MAC5E;AACA,UAAI,KAAK,SAAS,YAAY,MAAM;AAClC,aAAK,SAAS;AAAA,MAChB;AAAA,IACF,OACK;AACH,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,MAAM;AACnC,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAS;AAAA,IAC7B;AACA,QAAI,KAAK,kBAAkB;AACzB,mBAAa,KAAK,gBAAgB;AAAA,IACpC;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,SAAS;AAAA,IAChB;AACA,SAAK,OAAO;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,KAAK,MAAM,KAAK,SAAS,aAAa,KAAK,UAAU;AACnE,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AACF;;;AD9HO,SAAS,gBAAuC,QAA0C;AAC/F,SAAO,IAAI,UAAU,MAAM;AAC7B;",
   "names": []
 }

package/dist/main.d.ts

@@ -1,3 +1,33 @@
+import { Debouncer } from './debounce.js';
+import type { DebouncerConfig } from './type.js';
 export * from './debounce.js';
 export type * from './type.js';
+/**
+ * Factory function for creating a Debouncer instance for better type inference.
+ * @param config Configuration for the debouncer.
+ *
+ * @example
+ * ```typescript
+ * const debouncer = createDebouncer({
+ *   func: (text: string) => console.log('Searching:', text),
+ *   delay: 300,
+ *   leading: false,
+ *   trailing: true,
+ * });
+ *
+ * // Debounce search input
+ * debouncer.trigger('hello');
+ * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms
+ *
+ * // With custom thisContext
+ * const obj = { log: (msg: string) => console.log('Obj:', msg) };
+ * const debouncerWithContext = createDebouncer({
+ *   func: obj.log,
+ *   thisContext: obj,
+ *   delay: 200,
+ * });
+ * debouncerWithContext.trigger('test'); // Logs 'Obj: test'
+ * ```
+ */
+export declare function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F>;
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,mBAAmB,WAAW,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,WAAW,CAAC;AAE/C,cAAc,eAAe,CAAC;AAC9B,mBAAmB,WAAW,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE/F"}

package/dist/main.mjs

@@ -1,4 +1,4 @@
-/* @alwatr/debounce v1.0.1 */
+/* @alwatr/debounce v1.1.1 */
 
 // src/debounce.ts
 var Debouncer = class {
@@ -16,7 +16,7 @@ var Debouncer = class {
   /**
    * Triggers the debounced function with the stored `thisContext`.
    * @param args The arguments to pass to the `func`.
-   * 
+   *
    * @example
    * ```typescript
    * const debouncer = new Debouncer({
@@ -24,7 +24,7 @@ var Debouncer = class {
    *   delay: 500,
    * });
    * debouncer.trigger(42); // Logs after 500ms if not triggered again
-   * 
+   *
    * // Edge case: Rapid triggers only execute the last one
    * debouncer.trigger(1);
    * debouncer.trigger(2); // Only 2 will execute after delay
@@ -32,15 +32,19 @@ var Debouncer = class {
    */
   trigger(...args) {
     this.lastArgs__ = args;
-    const wasPending = this.isPending;
-    if (wasPending) {
+    const firstTrigger = !this.isPending;
+    if (firstTrigger) {
+      if (this.config__.maxWait) {
+        this.maxWaitTimerId__ = setTimeout(() => this.flush, this.config__.maxWait);
+      }
+      if (this.config__.leading === true) {
+        this.invoke__();
+      }
+    } else {
       clearTimeout(this.timerId__);
     }
-    if (this.config__.leading === true && !wasPending) {
-      this.invoke__();
-    }
     this.timerId__ = setTimeout(() => {
-      if (this.config__.trailing === true && wasPending) {
+      if (this.config__.trailing === true) {
         this.invoke__();
       }
       this.cleanup__();
@@ -49,7 +53,7 @@ var Debouncer = class {
   /**
    * Cancels any pending debounced execution and cleans up internal state.
    * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).
-   * 
+   *
    * @example
    * ```typescript
    * const debouncer = new Debouncer({
@@ -58,14 +62,17 @@ var Debouncer = class {
    * });
    * debouncer.trigger();
    * debouncer.cancel(); // Prevents execution
-   * 
+   *
    * // Note: After cancel, isPending becomes false
    * ```
    */
   cancel() {
-    if (this.isPending) {
+    if (this.timerId__) {
       clearTimeout(this.timerId__);
     }
+    if (this.maxWaitTimerId__) {
+      clearTimeout(this.maxWaitTimerId__);
+    }
     this.cleanup__();
   }
   /**
@@ -73,12 +80,13 @@ var Debouncer = class {
    */
   cleanup__() {
     delete this.timerId__;
+    delete this.maxWaitTimerId__;
     delete this.lastArgs__;
   }
   /**
    * Immediately executes the pending function if one exists.
    * Bypasses the delay and cleans up state. If no pending call, does nothing.
-   * 
+   *
    * @example
    * ```typescript
    * const debouncer = new Debouncer({
@@ -87,7 +95,7 @@ var Debouncer = class {
    * });
    * debouncer.trigger();
    * setTimeout(() => debouncer.flush(), 500); // Executes immediately
-   * 
+   *
    * // Edge case: Flush after cancel does nothing
    * debouncer.cancel();
    * debouncer.flush(); // No execution
@@ -95,9 +103,9 @@ var Debouncer = class {
    */
   flush() {
     if (this.isPending) {
-      this.cancel();
       this.invoke__();
     }
+    this.cancel();
   }
   /**
    * The core execution logic.
@@ -105,9 +113,12 @@ var Debouncer = class {
   invoke__() {
     if (this.lastArgs__) {
       this.config__.func.apply(this.config__.thisContext, this.lastArgs__);
+      this.lastArgs__ = void 0;
     }
   }
 };
+
+// src/main.ts
 function createDebouncer(config) {
   return new Debouncer(config);
 }

package/dist/main.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/debounce.ts"],
-  "sourcesContent": ["import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n * \n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // Advanced: With leading edge\n * const leadingDebouncer = new Debouncer({\n *   func: () => console.log('Immediate and delayed'),\n *   delay: 500,\n *   leading: true,\n *   trailing: true,\n * });\n * leadingDebouncer.trigger(); // Logs immediately, then again after 500ms if not cancelled\n * ```\n */\nexport class Debouncer<F extends AnyFunction> {\n  private timerId__?: number | NodeJS.Timeout;\n  private lastArgs__?: Parameters<F>;\n\n  public constructor(private readonly config__: DebouncerConfig<F>) {\n    this.config__.trailing ??= true;\n  }\n\n  /**\n   * Checks if there is a pending execution scheduled.\n   * Returns true if a timer is active, indicating a debounced call is waiting.\n   */\n  public get isPending(): boolean {\n    return this.timerId__ !== undefined;\n  }\n\n  /**\n   * Triggers the debounced function with the stored `thisContext`.\n   * @param args The arguments to pass to the `func`.\n   * \n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: (value: number) => console.log('Value:', value),\n   *   delay: 500,\n   * });\n   * debouncer.trigger(42); // Logs after 500ms if not triggered again\n   * \n   * // Edge case: Rapid triggers only execute the last one\n   * debouncer.trigger(1);\n   * debouncer.trigger(2); // Only 2 will execute after delay\n   * ```\n   */\n  public trigger(...args: Parameters<F>): void {\n    this.lastArgs__ = args;\n    const wasPending = this.isPending;\n\n    if (wasPending) {\n      clearTimeout(this.timerId__!);\n    }\n\n    if (this.config__.leading === true && !wasPending) {\n      this.invoke__();\n    }\n\n    this.timerId__ = setTimeout(() => {\n      if (this.config__.trailing === true && wasPending) {\n        this.invoke__();\n      }\n      this.cleanup__();\n    }, this.config__.delay);\n  }\n\n  /**\n   * Cancels any pending debounced execution and cleans up internal state.\n   * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).\n   * \n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Executed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * debouncer.cancel(); // Prevents execution\n   * \n   * // Note: After cancel, isPending becomes false\n   * ```\n   */\n  public cancel(): void {\n    if (this.isPending) {\n      clearTimeout(this.timerId__!);\n    }\n    this.cleanup__();\n  }\n\n  /**\n   * Cleans up internal state by deleting timer and arguments.\n   */\n  private cleanup__(): void {\n    delete this.timerId__;\n    delete this.lastArgs__;\n  }\n\n  /**\n   * Immediately executes the pending function if one exists.\n   * Bypasses the delay and cleans up state. If no pending call, does nothing.\n   * \n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Flushed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * setTimeout(() => debouncer.flush(), 500); // Executes immediately\n   * \n   * // Edge case: Flush after cancel does nothing\n   * debouncer.cancel();\n   * debouncer.flush(); // No execution\n   * ```\n   */\n  public flush(): void {\n    if (this.isPending) {\n      this.cancel();\n      this.invoke__();\n    }\n  }\n\n  /**\n   * The core execution logic.\n   */\n  private invoke__(): void {\n    if (this.lastArgs__) {\n      // `thisContext` is now read directly from the stored config.\n      this.config__.func.apply(this.config__.thisContext, this.lastArgs__);\n    }\n  }\n}\n\n/**\n * Factory function for creating a Debouncer instance for better type inference.\n * @param config Configuration for the debouncer.\n * \n * @example\n * ```typescript\n * const debouncer = createDebouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // With custom thisContext\n * const obj = { log: (msg: string) => console.log('Obj:', msg) };\n * const debouncerWithContext = createDebouncer({\n *   func: obj.log,\n *   thisContext: obj,\n *   delay: 200,\n * });\n * debouncerWithContext.trigger('test'); // Logs 'Obj: test'\n * ```\n */\nexport function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F> {\n  return new Debouncer(config);\n}\n"],
-  "mappings": ";;;AAgCO,IAAM,YAAN,MAAuC;AAAA,EAIrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,aAAa,KAAK;AAExB,QAAI,YAAY;AACd,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,QAAI,KAAK,SAAS,YAAY,QAAQ,CAAC,YAAY;AACjD,WAAK,SAAS;AAAA,IAChB;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,QAAQ,YAAY;AACjD,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAU;AAAA,IAC9B;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,OAAO;AACZ,WAAK,SAAS;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,KAAK,MAAM,KAAK,SAAS,aAAa,KAAK,UAAU;AAAA,IACrE;AAAA,EACF;AACF;AA6BO,SAAS,gBAAuC,QAA0C;AAC/F,SAAO,IAAI,UAAU,MAAM;AAC7B;",
+  "sources": ["../src/debounce.ts", "../src/main.ts"],
+  "sourcesContent": ["import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n *\n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n *\n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n *\n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n *\n * // Advanced: With leading edge\n * const leadingDebouncer = new Debouncer({\n *   func: () => console.log('Immediate and delayed'),\n *   delay: 500,\n *   leading: true,\n *   trailing: true,\n * });\n * leadingDebouncer.trigger(); // Logs immediately, then again after 500ms if not cancelled\n * ```\n */\nexport class Debouncer<F extends AnyFunction> {\n  private timerId__?: number | NodeJS.Timeout;\n  private maxWaitTimerId__?: number | NodeJS.Timeout;\n  private lastArgs__?: Parameters<F>;\n\n  public constructor(private readonly config__: DebouncerConfig<F>) {\n    this.config__.trailing ??= true;\n  }\n\n  /**\n   * Checks if there is a pending execution scheduled.\n   * Returns true if a timer is active, indicating a debounced call is waiting.\n   */\n  public get isPending(): boolean {\n    return this.timerId__ !== undefined;\n  }\n\n  /**\n   * Triggers the debounced function with the stored `thisContext`.\n   * @param args The arguments to pass to the `func`.\n   *\n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: (value: number) => console.log('Value:', value),\n   *   delay: 500,\n   * });\n   * debouncer.trigger(42); // Logs after 500ms if not triggered again\n   *\n   * // Edge case: Rapid triggers only execute the last one\n   * debouncer.trigger(1);\n   * debouncer.trigger(2); // Only 2 will execute after delay\n   * ```\n   */\n  public trigger(...args: Parameters<F>): void {\n    this.lastArgs__ = args; // its an array even if triggered without any args\n    const firstTrigger = !this.isPending;\n\n    if (firstTrigger) {\n      if (this.config__.maxWait) {\n        this.maxWaitTimerId__ = setTimeout(() => this.flush, this.config__.maxWait);\n      }\n      if (this.config__.leading === true) {\n        this.invoke__();\n      }\n    }\n    else {\n      clearTimeout(this.timerId__!);\n    }\n\n    this.timerId__ = setTimeout(() => {\n      if (this.config__.trailing === true) {\n        this.invoke__();\n      }\n      this.cleanup__();\n    }, this.config__.delay);\n  }\n\n  /**\n   * Cancels any pending debounced execution and cleans up internal state.\n   * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).\n   *\n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Executed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * debouncer.cancel(); // Prevents execution\n   *\n   * // Note: After cancel, isPending becomes false\n   * ```\n   */\n  public cancel(): void {\n    if (this.timerId__) {\n      clearTimeout(this.timerId__);\n    }\n    if (this.maxWaitTimerId__) {\n      clearTimeout(this.maxWaitTimerId__);\n    }\n    this.cleanup__();\n  }\n\n  /**\n   * Cleans up internal state by deleting timer and arguments.\n   */\n  private cleanup__(): void {\n    delete this.timerId__;\n    delete this.maxWaitTimerId__;\n    delete this.lastArgs__;\n  }\n\n  /**\n   * Immediately executes the pending function if one exists.\n   * Bypasses the delay and cleans up state. If no pending call, does nothing.\n   *\n   * @example\n   * ```typescript\n   * const debouncer = new Debouncer({\n   *   func: () => console.log('Flushed'),\n   *   delay: 1000,\n   * });\n   * debouncer.trigger();\n   * setTimeout(() => debouncer.flush(), 500); // Executes immediately\n   *\n   * // Edge case: Flush after cancel does nothing\n   * debouncer.cancel();\n   * debouncer.flush(); // No execution\n   * ```\n   */\n  public flush(): void {\n    if (this.isPending) {\n      this.invoke__();\n    }\n    this.cancel();\n  }\n\n  /**\n   * The core execution logic.\n   */\n  private invoke__(): void {\n    if (this.lastArgs__) {\n      // only call if we have new args (skip trailing call if leading already called)\n      this.config__.func.apply(this.config__.thisContext, this.lastArgs__);\n      this.lastArgs__ = undefined;\n    }\n  }\n}\n", "import {Debouncer} from './debounce.js';\n\nimport type {DebouncerConfig} from './type.js';\n\nexport * from './debounce.js';\nexport type * from './type.js';\n\n/**\n * Factory function for creating a Debouncer instance for better type inference.\n * @param config Configuration for the debouncer.\n *\n * @example\n * ```typescript\n * const debouncer = createDebouncer({\n *   func: (text: string) => console.log('Searching:', text),\n *   delay: 300,\n *   leading: false,\n *   trailing: true,\n * });\n *\n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n *\n * // With custom thisContext\n * const obj = { log: (msg: string) => console.log('Obj:', msg) };\n * const debouncerWithContext = createDebouncer({\n *   func: obj.log,\n *   thisContext: obj,\n *   delay: 200,\n * });\n * debouncerWithContext.trigger('test'); // Logs 'Obj: test'\n * ```\n */\nexport function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F> {\n  return new Debouncer(config);\n}\n"],
+  "mappings": ";;;AAgCO,IAAM,YAAN,MAAuC;AAAA,EAKrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,eAAe,CAAC,KAAK;AAE3B,QAAI,cAAc;AAChB,UAAI,KAAK,SAAS,SAAS;AACzB,aAAK,mBAAmB,WAAW,MAAM,KAAK,OAAO,KAAK,SAAS,OAAO;AAAA,MAC5E;AACA,UAAI,KAAK,SAAS,YAAY,MAAM;AAClC,aAAK,SAAS;AAAA,MAChB;AAAA,IACF,OACK;AACH,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,MAAM;AACnC,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAS;AAAA,IAC7B;AACA,QAAI,KAAK,kBAAkB;AACzB,mBAAa,KAAK,gBAAgB;AAAA,IACpC;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,SAAS;AAAA,IAChB;AACA,SAAK,OAAO;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,KAAK,MAAM,KAAK,SAAS,aAAa,KAAK,UAAU;AACnE,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AACF;;;AC9HO,SAAS,gBAAuC,QAA0C;AAC/F,SAAO,IAAI,UAAU,MAAM;AAC7B;",
   "names": []
 }

package/dist/type.d.ts

@@ -25,6 +25,12 @@ export interface DebouncerConfig<F extends AnyFunction> {
      * Must be a positive integer; affects performance and responsiveness.
      */
     delay: number;
+    /**
+     * The maximum time the `func` is allowed to be delayed before it's invoked.
+     * This is useful for guaranteeing execution of a function that's continuously triggered.
+     * If set, the function will be called after `maxWait` milliseconds, even if triggers are still occurring.
+     */
+    maxWait?: number;
     /**
      * If `true`, the function is called on the leading edge of the timeout.
      * Useful for immediate feedback (e.g., button press).

package/dist/type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,WAAW;IACpD;;;OAGG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;;;OAIG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAEnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,WAAW;IACpD;;;OAGG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;;;OAIG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAEnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alwatr/debounce",
   "description": "A powerful, modern, and type-safe debouncer utility designed for high-performance applications. It's framework-agnostic, works seamlessly in both Node.js and browsers, and provides a rich API for fine-grained control over function execution.",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com>",
   "bugs": "https://github.com/Alwatr/nanolib/issues",
   "devDependencies": {
@@ -9,6 +9,7 @@
     "@alwatr/prettier-config": "5.0.3",
     "@alwatr/tsconfig-base": "6.0.1",
     "@alwatr/type-helper": "6.0.2",
+    "@jest/globals": "^30.1.2",
     "@types/node": "^22.18.3",
     "typescript": "^5.9.2"
   },
@@ -77,5 +78,5 @@
   },
   "type": "module",
   "types": "./dist/main.d.ts",
-  "gitHead": "0ee186f1ec8973608f06155e739d55ab5d4bd816"
+  "gitHead": "19fe957df929dd2a1b546d447ff65a430353e60f"
 }

package/src/debounce.test.js

@@ -0,0 +1,388 @@
+import {describe, beforeEach, afterEach, it, expect, jest} from '@jest/globals';
+import {createDebouncer} from '@alwatr/debounce';
+
+describe('Debouncer', () => {
+  /**
+   * @type {import("jest-mock").Mock<import("jest-mock").UnknownFunction>}
+   */
+  let mockFunc;
+  /**
+   * @type {import("@alwatr/debounce").Debouncer<typeof mockFunc>}
+   */
+  let debouncer;
+
+  beforeEach(() => {
+    mockFunc = jest.fn();
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  describe('Basic Trailing Debounce (default)', () => {
+    beforeEach(() => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+      });
+    });
+
+    it('should execute after delay on single trigger', () => {
+      debouncer.trigger('test');
+      expect(mockFunc).not.toHaveBeenCalled();
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledWith('test');
+    });
+
+    it('should reset delay on multiple triggers', () => {
+      debouncer.trigger('first');
+      jest.advanceTimersByTime(200);
+      debouncer.trigger('second');
+      jest.advanceTimersByTime(200);
+      expect(mockFunc).not.toHaveBeenCalled();
+      jest.advanceTimersByTime(100);
+      expect(mockFunc).toHaveBeenCalledWith('second');
+    });
+
+    it('should not execute if cancelled before delay', () => {
+      debouncer.trigger('test');
+      debouncer.cancel();
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Leading Debounce', () => {
+    beforeEach(() => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+        leading: true,
+        trailing: false,
+      });
+    });
+
+    it('should execute immediately on first trigger', () => {
+      debouncer.trigger('test');
+      expect(mockFunc).toHaveBeenCalledWith('test');
+    });
+
+    it('should not execute again within delay', () => {
+      debouncer.trigger('first');
+      expect(mockFunc).toHaveBeenCalledTimes(1);
+      debouncer.trigger('second');
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledTimes(1);
+    });
+
+    it('should execute again after delay', () => {
+      debouncer.trigger('first');
+      jest.advanceTimersByTime(300);
+      debouncer.trigger('second');
+      expect(mockFunc).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('Both Leading and Trailing', () => {
+    beforeEach(() => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+        leading: true,
+        trailing: true,
+      });
+    });
+
+    it('should execute immediately but not after delay on single trigger', () => {
+      debouncer.trigger('test');
+      expect(mockFunc).toHaveBeenCalledWith('test');
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledTimes(1);
+    });
+
+    it('should execute immediately, then trailing on last trigger', () => {
+      debouncer.trigger('first');
+      expect(mockFunc).toHaveBeenCalledTimes(1);
+      expect(mockFunc).toHaveBeenCalledWith('first');
+      jest.advanceTimersByTime(200);
+      debouncer.trigger('second');
+      jest.advanceTimersByTime(100);
+      debouncer.trigger('third');
+      jest.advanceTimersByTime(100);
+      expect(mockFunc).toHaveBeenCalledTimes(1);
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledTimes(2);
+      expect(mockFunc).toHaveBeenLastCalledWith('third');
+    });
+  });
+
+  describe('Cancel Functionality', () => {
+    beforeEach(() => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+      });
+    });
+
+    it('should cancel pending execution', () => {
+      debouncer.trigger('test');
+      expect(debouncer.isPending).toBe(true);
+      debouncer.cancel();
+      expect(debouncer.isPending).toBe(false);
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).not.toHaveBeenCalled();
+    });
+
+    it('should handle cancel on leading debounce', () => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+        leading: true,
+      });
+      debouncer.trigger('test');
+      expect(mockFunc).toHaveBeenCalledTimes(1);
+      debouncer.cancel();
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledTimes(1); // No trailing call
+    });
+  });
+
+  describe('Flush Functionality', () => {
+    beforeEach(() => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+      });
+    });
+
+    it('should execute immediately and cancel pending', () => {
+      debouncer.trigger('test');
+      expect(mockFunc).not.toHaveBeenCalled();
+      debouncer.flush();
+      expect(mockFunc).toHaveBeenCalledWith('test');
+      expect(debouncer.isPending).toBe(false);
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledTimes(1);
+    });
+
+    it('should do nothing if no pending call', () => {
+      debouncer.flush();
+      expect(mockFunc).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('MaxWait Functionality', () => {
+    beforeEach(() => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+        maxWait: 1000,
+      });
+    });
+
+    it('should execute after maxWait even with continuous triggers', () => {
+      debouncer.trigger('first');
+      jest.advanceTimersByTime(500);
+      debouncer.trigger('second');
+      jest.advanceTimersByTime(500);
+      expect(mockFunc).toHaveBeenCalledWith('first'); // After maxWait
+      debouncer.trigger('third');
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledWith('third');
+    });
+  });
+
+  describe('ThisContext Binding', () => {
+    /**
+     * @type {{ value: string; }}
+     */
+    let context;
+
+    beforeEach(() => {
+      context = {value: 'test'};
+      mockFunc = jest.fn(function () {
+        this.value = 'changed';
+      });
+      debouncer = createDebouncer({
+        func: mockFunc,
+        thisContext: context,
+        delay: 300,
+      });
+    });
+
+    it('should bind thisContext correctly', () => {
+      debouncer.trigger();
+      jest.advanceTimersByTime(300);
+      expect(context.value).toBe('changed');
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle zero delay', () => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 0,
+      });
+      debouncer.trigger('test');
+      jest.advanceTimersByTime(0);
+      expect(mockFunc).toHaveBeenCalledWith('test');
+    });
+
+    it('should handle no arguments', () => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+      });
+      debouncer.trigger();
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledWith();
+    });
+
+    it('should handle multiple arguments', () => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+      });
+      debouncer.trigger('arg1', 'arg2', 123);
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledWith('arg1', 'arg2', 123);
+    });
+
+    it('should not execute if func throws', () => {
+      mockFunc = jest.fn(() => {
+        throw new Error('test');
+      });
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+      });
+      debouncer.trigger();
+      expect(() => jest.advanceTimersByTime(300)).toThrow('test');
+    });
+
+    it('should double-invocation with leading: true, trailing: false, and maxWait on multiple trigger', () => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+        leading: true,
+        trailing: false,
+        maxWait: 500,
+      });
+      debouncer.trigger('first');
+      expect(mockFunc).toHaveBeenCalledTimes(1); // Leading call
+      jest.advanceTimersByTime(200);
+      debouncer.trigger('second');
+      jest.advanceTimersByTime(200);
+      expect(mockFunc).toHaveBeenCalledTimes(1); // Should not call again yet
+      jest.advanceTimersByTime(200); // Trigger maxWait, which may call flush
+      expect(mockFunc).toHaveBeenCalledTimes(2); // Should be called a second time due to maxWait
+    });
+
+    it('should prevent double-invocation with leading: true, trailing: false, and maxWait on single trigger', () => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+        leading: true,
+        trailing: false,
+        maxWait: 200,
+      });
+      debouncer.trigger('first');
+      expect(mockFunc).toHaveBeenCalledTimes(1); // Leading call
+      jest.advanceTimersByTime(300);
+      expect(mockFunc).toHaveBeenCalledTimes(1); // Should not call again
+    });
+
+    it('should prevent double-invocation with leading: true, trailing: false, and flush', () => {
+      debouncer = createDebouncer({
+        func: mockFunc,
+        delay: 300,
+        leading: true,
+        trailing: false,
+      });
+      debouncer.trigger('first');
+      expect(mockFunc).toHaveBeenCalledTimes(1); // Leading call
+      jest.advanceTimersByTime(100);
+      debouncer.flush();
+      debouncer.flush();
+      expect(mockFunc).toHaveBeenCalledTimes(1); // Should not call again
+    });
+  });
+  
+  it('should execute after delay for trailing debounce', () => {
+    debouncer = createDebouncer({
+      func: mockFunc,
+      delay: 300,
+      leading: false,
+      trailing: true,
+    });
+    debouncer.trigger('first');
+    expect(mockFunc).toHaveBeenCalledTimes(0); // No call yet
+    jest.advanceTimersByTime(300);
+    expect(mockFunc).toHaveBeenCalledTimes(1); // Trailing call
+  });
+  it('should execute leading but skip trailing on single trigger', () => {
+    debouncer = createDebouncer({
+      func: mockFunc,
+      delay: 300,
+      leading: true,
+      trailing: true,
+    });
+    debouncer.trigger('first');
+    expect(mockFunc).toHaveBeenCalledTimes(1); // leading call
+    jest.advanceTimersByTime(300);
+    expect(mockFunc).toHaveBeenCalledTimes(1); // no trailing call on same argument
+  });
+
+  it('should execute leading and skip trailing after flush', () => {
+    debouncer = createDebouncer({
+      func: mockFunc,
+      delay: 300,
+      leading: true,
+      trailing: true,
+    });
+    debouncer.trigger('first');
+    expect(mockFunc).toHaveBeenCalledTimes(1); // leading call
+    jest.advanceTimersByTime(100);
+    debouncer.flush();
+    jest.advanceTimersByTime(100);
+    expect(mockFunc).toHaveBeenCalledTimes(1); // no trailing call on same argument
+  });
+
+  it('should execute leading and trailing on multiple triggers', () => {
+    debouncer = createDebouncer({
+      func: mockFunc,
+      delay: 300,
+      leading: true,
+      trailing: true,
+    });
+    debouncer.trigger('first');
+    expect(mockFunc).toHaveBeenCalledTimes(1); // leading call
+    debouncer.trigger('second');
+    expect(mockFunc).toHaveBeenCalledTimes(1); // No call again yet
+    jest.advanceTimersByTime(300);
+    expect(mockFunc).toHaveBeenCalledTimes(2); // Trailing call
+    expect(mockFunc).toHaveBeenLastCalledWith('second');
+  });
+
+  it('should execute leading and flush, skip trailing', () => {
+    debouncer = createDebouncer({
+      func: mockFunc,
+      delay: 300,
+      leading: true,
+      trailing: false,
+    });
+    debouncer.trigger('first');
+    expect(mockFunc).toHaveBeenCalledTimes(1); // leading call
+    debouncer.trigger('second');
+    expect(mockFunc).toHaveBeenCalledTimes(1); // No call again yet
+    debouncer.flush();
+    debouncer.flush();
+    expect(mockFunc).toHaveBeenCalledTimes(2);
+    expect(mockFunc).toHaveBeenLastCalledWith('second');
+    jest.advanceTimersByTime(300);
+    debouncer.flush();
+    expect(mockFunc).toHaveBeenCalledTimes(2); // no trailing call
+  });
+});