@tanstack/pacer 0.2.0 → 0.4.0

package/dist/cjs/throttler.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"throttler.cjs","sources":["../../src/throttler.ts"],"sourcesContent":["import type { AnyFunction } from './types'\n\n/**\n * Options for configuring a throttled function\n */\nexport interface ThrottlerOptions<\n  TFn extends AnyFunction,\n  TArgs extends Parameters<TFn>,\n> {\n  /**\n   * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to true.\n   */\n  leading?: boolean\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (throttler: Throttler<TFn, TArgs>) => void\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once\n   */\n  wait: number\n}\n\nconst defaultOptions: Required<ThrottlerOptions<any, any>> = {\n  enabled: true,\n  leading: true,\n  trailing: true,\n  wait: 0,\n  onExecute: () => {},\n}\n\n/**\n * A class that creates a throttled function.\n *\n * Throttling ensures a function is called at most once within a specified time window.\n * Unlike debouncing which waits for a pause in calls, throttling guarantees consistent\n * execution timing regardless of call frequency.\n *\n * Supports both leading and trailing edge execution:\n * - Leading: Execute immediately on first call (default: true)\n * - Trailing: Execute after wait period if called during throttle (default: true)\n *\n * For collapsing rapid-fire events where you only care about the last call, consider using Debouncer.\n *\n * @example\n * ```ts\n * const throttler = new Throttler(\n *   (id: string) => api.getData(id),\n *   { wait: 1000 } // Execute at most once per second\n * );\n *\n * // First call executes immediately\n * throttler.maybeExecute('123');\n *\n * // Subsequent calls within 1000ms are throttled\n * throttler.maybeExecute('123'); // Throttled\n * ```\n */\nexport class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {\n  private _executionCount = 0\n  private _lastArgs: TArgs | undefined\n  private _lastExecutionTime = 0\n  private _options: Required<ThrottlerOptions<TFn, TArgs>>\n  private _timeoutId: NodeJS.Timeout | undefined\n  private _isPending = false\n\n  constructor(\n    private fn: TFn,\n    initialOptions: ThrottlerOptions<TFn, TArgs>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the throttler options\n   * Returns the new options state\n   */\n  setOptions(\n    newOptions: Partial<ThrottlerOptions<TFn, TArgs>>,\n  ): Required<ThrottlerOptions<TFn, TArgs>> {\n    this._options = {\n      ...this._options,\n      ...newOptions,\n    }\n    return this._options\n  }\n\n  /**\n   * Returns the current throttler options\n   */\n  getOptions(): Required<ThrottlerOptions<TFn, TArgs>> {\n    return this._options\n  }\n\n  /**\n   * Attempts to execute the throttled function. The execution behavior depends on the throttler options:\n   *\n   * - If enough time has passed since the last execution (>= wait period):\n   *   - With leading=true: Executes immediately\n   *   - With leading=false: Waits for the next trailing execution\n   *\n   * - If within the wait period:\n   *   - With trailing=true: Schedules execution for end of wait period\n   *   - With trailing=false: Drops the execution\n   *\n   * @example\n   * ```ts\n   * const throttled = new Throttler(fn, { wait: 1000 });\n   *\n   * // First call executes immediately\n   * throttled.maybeExecute('a', 'b');\n   *\n   * // Call during wait period - gets throttled\n   * throttled.maybeExecute('c', 'd');\n   * ```\n   */\n  maybeExecute(...args: TArgs): void {\n    const now = Date.now()\n    const timeSinceLastExecution = now - this._lastExecutionTime\n\n    // Handle leading execution\n    if (timeSinceLastExecution >= this._options.wait) {\n      if (this._options.leading) {\n        this.executeFunction(...args)\n      }\n      this._lastExecutionTime = now\n      this._isPending = false\n    } else {\n      // Store the most recent arguments for potential trailing execution\n      this._lastArgs = args\n\n      // Set up trailing execution if not already scheduled\n      if (!this._timeoutId && this._options.trailing) {\n        this._isPending = true\n        this._timeoutId = setTimeout(() => {\n          if (this._lastArgs) {\n            this.executeFunction(...this._lastArgs)\n            this._lastArgs = undefined\n          }\n          this._lastExecutionTime = Date.now()\n          this._timeoutId = undefined\n          this._isPending = false\n          this._options.onExecute(this)\n        }, this._options.wait - timeSinceLastExecution)\n      }\n    }\n  }\n\n  private executeFunction(...args: TArgs): void {\n    if (!this._options.enabled) return\n    this.fn(...args) // EXECUTE!\n    this._executionCount++\n  }\n\n  /**\n   * Cancels any pending trailing execution and clears internal state.\n   *\n   * If a trailing execution is scheduled (due to throttling with trailing=true),\n   * this will prevent that execution from occurring. The internal timeout and\n   * stored arguments will be cleared.\n   *\n   * Has no effect if there is no pending execution.\n   */\n  cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = undefined\n      this._lastArgs = undefined\n      this._isPending = false\n    }\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this._executionCount\n  }\n\n  /**\n   * Returns `true` if there is a pending execution\n   */\n  getIsPending(): boolean {\n    return this._options.enabled && this._isPending\n  }\n\n  /**\n   * Returns the last execution time\n   */\n  getLastExecutionTime(): number {\n    return this._lastExecutionTime\n  }\n\n  /**\n   * Returns the next execution time\n   */\n  getNextExecutionTime(): number {\n    return this._lastExecutionTime + this._options.wait\n  }\n}\n\n/**\n * Creates a throttled function that limits how often the provided function can execute.\n *\n * Throttling ensures a function executes at most once within a specified time window,\n * regardless of how many times it is called. This is useful for rate-limiting\n * expensive operations or UI updates.\n *\n * The throttled function can be configured to execute on the leading and/or trailing\n * edge of the throttle window via options.\n *\n * For handling bursts of events, consider using debounce() instead. For hard execution\n * limits, consider using rateLimit().\n *\n * @example\n * ```ts\n * // Basic throttling - max once per second\n * const throttled = throttle(updateUI, { wait: 1000 });\n *\n * // Configure leading/trailing execution\n * const throttled = throttle(saveData, {\n *   wait: 2000,\n *   leading: true,  // Execute immediately on first call\n *   trailing: true  // Execute again after delay if called during wait\n * });\n * ```\n */\nexport function throttle<\n  TFn extends AnyFunction,\n  TArgs extends Parameters<TFn>,\n>(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn, TArgs>, 'enabled'>) {\n  const throttler = new Throttler(fn, initialOptions)\n  return throttler.maybeExecute.bind(throttler)\n}\n"],"names":[],"mappings":";;AAkCA,MAAM,iBAAuD;AAAA,EAC3D,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,MAAM;AAAA,EACN,WAAW,MAAM;AAAA,EAAA;AACnB;AA6BO,MAAM,UAAkE;AAAA,EAQ7E,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AARV,SAAQ,kBAAkB;AAE1B,SAAQ,qBAAqB;AAG7B,SAAQ,aAAa;AAMnB,SAAK,WAAW;AAAA,MACd,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YACwC;AACxC,SAAK,WAAW;AAAA,MACd,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,aAAqD;AACnD,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAyBd,gBAAgB,MAAmB;AAC3B,UAAA,MAAM,KAAK,IAAI;AACf,UAAA,yBAAyB,MAAM,KAAK;AAGtC,QAAA,0BAA0B,KAAK,SAAS,MAAM;AAC5C,UAAA,KAAK,SAAS,SAAS;AACpB,aAAA,gBAAgB,GAAG,IAAI;AAAA,MAAA;AAE9B,WAAK,qBAAqB;AAC1B,WAAK,aAAa;AAAA,IAAA,OACb;AAEL,WAAK,YAAY;AAGjB,UAAI,CAAC,KAAK,cAAc,KAAK,SAAS,UAAU;AAC9C,aAAK,aAAa;AACb,aAAA,aAAa,WAAW,MAAM;AACjC,cAAI,KAAK,WAAW;AACb,iBAAA,gBAAgB,GAAG,KAAK,SAAS;AACtC,iBAAK,YAAY;AAAA,UAAA;AAEd,eAAA,qBAAqB,KAAK,IAAI;AACnC,eAAK,aAAa;AAClB,eAAK,aAAa;AACb,eAAA,SAAS,UAAU,IAAI;AAAA,QAC3B,GAAA,KAAK,SAAS,OAAO,sBAAsB;AAAA,MAAA;AAAA,IAChD;AAAA,EACF;AAAA,EAGM,mBAAmB,MAAmB;AACxC,QAAA,CAAC,KAAK,SAAS,QAAS;AACvB,SAAA,GAAG,GAAG,IAAI;AACV,SAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYP,SAAe;AACb,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAClB,WAAK,YAAY;AACjB,WAAK,aAAa;AAAA,IAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAMF,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,eAAwB;AACf,WAAA,KAAK,SAAS,WAAW,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMvC,uBAA+B;AAC7B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AACtB,WAAA,KAAK,qBAAqB,KAAK,SAAS;AAAA,EAAA;AAEnD;AA4BgB,SAAA,SAGd,IAAS,gBAA+D;AACxE,QAAM,YAAY,IAAI,UAAU,IAAI,cAAc;AAC3C,SAAA,UAAU,aAAa,KAAK,SAAS;AAC9C;;;"}
+{"version":3,"file":"throttler.cjs","sources":["../../src/throttler.ts"],"sourcesContent":["import type { AnyFunction } from './types'\n\n/**\n * Options for configuring a throttled function\n */\nexport interface ThrottlerOptions<TFn extends AnyFunction> {\n  /**\n   * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to true.\n   */\n  leading?: boolean\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (throttler: Throttler<TFn>) => void\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once\n   */\n  wait: number\n}\n\nconst defaultOptions: Required<ThrottlerOptions<any>> = {\n  enabled: true,\n  leading: true,\n  onExecute: () => {},\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates a throttled function.\n *\n * Throttling ensures a function is called at most once within a specified time window.\n * Unlike debouncing which waits for a pause in calls, throttling guarantees consistent\n * execution timing regardless of call frequency.\n *\n * Supports both leading and trailing edge execution:\n * - Leading: Execute immediately on first call (default: true)\n * - Trailing: Execute after wait period if called during throttle (default: true)\n *\n * For collapsing rapid-fire events where you only care about the last call, consider using Debouncer.\n *\n * @example\n * ```ts\n * const throttler = new Throttler(\n *   (id: string) => api.getData(id),\n *   { wait: 1000 } // Execute at most once per second\n * );\n *\n * // First call executes immediately\n * throttler.maybeExecute('123');\n *\n * // Subsequent calls within 1000ms are throttled\n * throttler.maybeExecute('123'); // Throttled\n * ```\n */\nexport class Throttler<TFn extends AnyFunction> {\n  private _executionCount = 0\n  private _lastArgs: Parameters<TFn> | undefined\n  private _lastExecutionTime = 0\n  private _options: Required<ThrottlerOptions<TFn>>\n  private _timeoutId: NodeJS.Timeout | undefined\n\n  constructor(\n    private fn: TFn,\n    initialOptions: ThrottlerOptions<TFn>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the throttler options\n   * Returns the new options state\n   */\n  setOptions(newOptions: Partial<ThrottlerOptions<TFn>>): void {\n    this._options = { ...this._options, ...newOptions }\n\n    // End the pending state if the debouncer is disabled\n    if (!this._options.enabled) {\n      this.cancel()\n    }\n  }\n\n  /**\n   * Returns the current throttler options\n   */\n  getOptions(): Required<ThrottlerOptions<TFn>> {\n    return this._options\n  }\n\n  /**\n   * Attempts to execute the throttled function. The execution behavior depends on the throttler options:\n   *\n   * - If enough time has passed since the last execution (>= wait period):\n   *   - With leading=true: Executes immediately\n   *   - With leading=false: Waits for the next trailing execution\n   *\n   * - If within the wait period:\n   *   - With trailing=true: Schedules execution for end of wait period\n   *   - With trailing=false: Drops the execution\n   *\n   * @example\n   * ```ts\n   * const throttled = new Throttler(fn, { wait: 1000 });\n   *\n   * // First call executes immediately\n   * throttled.maybeExecute('a', 'b');\n   *\n   * // Call during wait period - gets throttled\n   * throttled.maybeExecute('c', 'd');\n   * ```\n   */\n  maybeExecute(...args: Parameters<TFn>): void {\n    const now = Date.now()\n    const timeSinceLastExecution = now - this._lastExecutionTime\n\n    // Handle leading execution\n    if (this._options.leading && timeSinceLastExecution >= this._options.wait) {\n      this.executeFunction(...args)\n    } else {\n      // Store the most recent arguments for potential trailing execution\n      this._lastArgs = args\n\n      // Set up trailing execution if not already scheduled\n      if (!this._timeoutId && this._options.trailing) {\n        const _timeSinceLastExecution = this._lastExecutionTime\n          ? now - this._lastExecutionTime\n          : 0\n        const timeoutDuration = this._options.wait - _timeSinceLastExecution\n        this._timeoutId = setTimeout(() => {\n          if (this._lastArgs !== undefined) {\n            this.executeFunction(...this._lastArgs)\n          }\n        }, timeoutDuration)\n      }\n    }\n  }\n\n  private executeFunction(...args: Parameters<TFn>): void {\n    if (!this._options.enabled) return\n    this.fn(...args) // EXECUTE!\n    this._executionCount++\n    this._lastExecutionTime = Date.now()\n    this._timeoutId = undefined\n    this._lastArgs = undefined\n    this._options.onExecute(this)\n  }\n\n  /**\n   * Cancels any pending trailing execution and clears internal state.\n   *\n   * If a trailing execution is scheduled (due to throttling with trailing=true),\n   * this will prevent that execution from occurring. The internal timeout and\n   * stored arguments will be cleared.\n   *\n   * Has no effect if there is no pending execution.\n   */\n  cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = undefined\n      this._lastArgs = undefined\n    }\n  }\n\n  /**\n   * Returns the last execution time\n   */\n  getLastExecutionTime(): number {\n    return this._lastExecutionTime\n  }\n\n  /**\n   * Returns the next execution time\n   */\n  getNextExecutionTime(): number {\n    return this._lastExecutionTime + this._options.wait\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this._executionCount\n  }\n\n  /**\n   * Returns `true` if there is a pending execution\n   */\n  getIsPending(): boolean {\n    return this._options.enabled && !!this._timeoutId\n  }\n}\n\n/**\n * Creates a throttled function that limits how often the provided function can execute.\n *\n * Throttling ensures a function executes at most once within a specified time window,\n * regardless of how many times it is called. This is useful for rate-limiting\n * expensive operations or UI updates.\n *\n * The throttled function can be configured to execute on the leading and/or trailing\n * edge of the throttle window via options.\n *\n * For handling bursts of events, consider using debounce() instead. For hard execution\n * limits, consider using rateLimit().\n *\n * @example\n * ```ts\n * // Basic throttling - max once per second\n * const throttled = throttle(updateUI, { wait: 1000 });\n *\n * // Configure leading/trailing execution\n * const throttled = throttle(saveData, {\n *   wait: 2000,\n *   leading: true,  // Execute immediately on first call\n *   trailing: true  // Execute again after delay if called during wait\n * });\n * ```\n */\nexport function throttle<TFn extends AnyFunction>(\n  fn: TFn,\n  initialOptions: Omit<ThrottlerOptions<TFn>, 'enabled'>,\n) {\n  const throttler = new Throttler(fn, initialOptions)\n  return throttler.maybeExecute.bind(throttler)\n}\n"],"names":[],"mappings":";;AA+BA,MAAM,iBAAkD;AAAA,EACtD,SAAS;AAAA,EACT,SAAS;AAAA,EACT,WAAW,MAAM;AAAA,EAAC;AAAA,EAClB,UAAU;AAAA,EACV,MAAM;AACR;AA6BO,MAAM,UAAmC;AAAA,EAO9C,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AAPV,SAAQ,kBAAkB;AAE1B,SAAQ,qBAAqB;AAQ3B,SAAK,WAAW;AAAA,MACd,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WAAW,YAAkD;AAC3D,SAAK,WAAW,EAAE,GAAG,KAAK,UAAU,GAAG,WAAW;AAG9C,QAAA,CAAC,KAAK,SAAS,SAAS;AAC1B,WAAK,OAAO;AAAA,IAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAMF,aAA8C;AAC5C,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAyBd,gBAAgB,MAA6B;AACrC,UAAA,MAAM,KAAK,IAAI;AACf,UAAA,yBAAyB,MAAM,KAAK;AAG1C,QAAI,KAAK,SAAS,WAAW,0BAA0B,KAAK,SAAS,MAAM;AACpE,WAAA,gBAAgB,GAAG,IAAI;AAAA,IAAA,OACvB;AAEL,WAAK,YAAY;AAGjB,UAAI,CAAC,KAAK,cAAc,KAAK,SAAS,UAAU;AAC9C,cAAM,0BAA0B,KAAK,qBACjC,MAAM,KAAK,qBACX;AACE,cAAA,kBAAkB,KAAK,SAAS,OAAO;AACxC,aAAA,aAAa,WAAW,MAAM;AAC7B,cAAA,KAAK,cAAc,QAAW;AAC3B,iBAAA,gBAAgB,GAAG,KAAK,SAAS;AAAA,UAAA;AAAA,WAEvC,eAAe;AAAA,MAAA;AAAA,IACpB;AAAA,EACF;AAAA,EAGM,mBAAmB,MAA6B;AAClD,QAAA,CAAC,KAAK,SAAS,QAAS;AACvB,SAAA,GAAG,GAAG,IAAI;AACV,SAAA;AACA,SAAA,qBAAqB,KAAK,IAAI;AACnC,SAAK,aAAa;AAClB,SAAK,YAAY;AACZ,SAAA,SAAS,UAAU,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAY9B,SAAe;AACb,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAClB,WAAK,YAAY;AAAA,IAAA;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA,EAMF,uBAA+B;AAC7B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AACtB,WAAA,KAAK,qBAAqB,KAAK,SAAS;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMjD,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,eAAwB;AACtB,WAAO,KAAK,SAAS,WAAW,CAAC,CAAC,KAAK;AAAA,EAAA;AAE3C;AA4BgB,SAAA,SACd,IACA,gBACA;AACA,QAAM,YAAY,IAAI,UAAU,IAAI,cAAc;AAC3C,SAAA,UAAU,aAAa,KAAK,SAAS;AAC9C;;;"}

package/dist/cjs/throttler.d.cts

@@ -2,7 +2,7 @@ import { AnyFunction } from './types.cjs';
 /**
  * Options for configuring a throttled function
  */
-export interface ThrottlerOptions<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
+export interface ThrottlerOptions<TFn extends AnyFunction> {
     /**
      * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
      * Defaults to true.
@@ -16,7 +16,7 @@ export interface ThrottlerOptions<TFn extends AnyFunction, TArgs extends Paramet
     /**
      * Callback function that is called after the function is executed
      */
-    onExecute?: (throttler: Throttler<TFn, TArgs>) => void;
+    onExecute?: (throttler: Throttler<TFn>) => void;
     /**
      * Whether to execute on the trailing edge of the timeout.
      * Defaults to true.
@@ -54,24 +54,23 @@ export interface ThrottlerOptions<TFn extends AnyFunction, TArgs extends Paramet
  * throttler.maybeExecute('123'); // Throttled
  * ```
  */
-export declare class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
+export declare class Throttler<TFn extends AnyFunction> {
     private fn;
     private _executionCount;
     private _lastArgs;
     private _lastExecutionTime;
     private _options;
     private _timeoutId;
-    private _isPending;
-    constructor(fn: TFn, initialOptions: ThrottlerOptions<TFn, TArgs>);
+    constructor(fn: TFn, initialOptions: ThrottlerOptions<TFn>);
     /**
      * Updates the throttler options
      * Returns the new options state
      */
-    setOptions(newOptions: Partial<ThrottlerOptions<TFn, TArgs>>): Required<ThrottlerOptions<TFn, TArgs>>;
+    setOptions(newOptions: Partial<ThrottlerOptions<TFn>>): void;
     /**
      * Returns the current throttler options
      */
-    getOptions(): Required<ThrottlerOptions<TFn, TArgs>>;
+    getOptions(): Required<ThrottlerOptions<TFn>>;
     /**
      * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
      *
@@ -94,7 +93,7 @@ export declare class Throttler<TFn extends AnyFunction, TArgs extends Parameters
      * throttled.maybeExecute('c', 'd');
      * ```
      */
-    maybeExecute(...args: TArgs): void;
+    maybeExecute(...args: Parameters<TFn>): void;
     private executeFunction;
     /**
      * Cancels any pending trailing execution and clears internal state.
@@ -106,14 +105,6 @@ export declare class Throttler<TFn extends AnyFunction, TArgs extends Parameters
      * Has no effect if there is no pending execution.
      */
     cancel(): void;
-    /**
-     * Returns the number of times the function has been executed
-     */
-    getExecutionCount(): number;
-    /**
-     * Returns `true` if there is a pending execution
-     */
-    getIsPending(): boolean;
     /**
      * Returns the last execution time
      */
@@ -122,6 +113,14 @@ export declare class Throttler<TFn extends AnyFunction, TArgs extends Parameters
      * Returns the next execution time
      */
     getNextExecutionTime(): number;
+    /**
+     * Returns the number of times the function has been executed
+     */
+    getExecutionCount(): number;
+    /**
+     * Returns `true` if there is a pending execution
+     */
+    getIsPending(): boolean;
 }
 /**
  * Creates a throttled function that limits how often the provided function can execute.
@@ -149,4 +148,4 @@ export declare class Throttler<TFn extends AnyFunction, TArgs extends Parameters
  * });
  * ```
  */
-export declare function throttle<TFn extends AnyFunction, TArgs extends Parameters<TFn>>(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn, TArgs>, 'enabled'>): (...args: TArgs) => void;
+export declare function throttle<TFn extends AnyFunction>(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn>, 'enabled'>): (...args: Parameters<TFn>) => void;

package/dist/cjs/types.d.cts

@@ -1,12 +1,8 @@
 /**
  * Represents a function that can be called with any arguments and returns any value.
- * @template TArgs - The type of the arguments the function can be called with.
- * @returns The return value of the function.
  */
-export type AnyFunction<TArgs extends Array<any> = Array<any>> = (...args: TArgs) => any;
+export type AnyFunction = (...args: Array<any>) => any;
 /**
  * Represents an asynchronous function that can be called with any arguments and returns a promise.
- * @template TArgs - The type of the arguments the function can be called with.
- * @returns A promise that resolves to the return value of the function.
  */
-export type AnyAsyncFunction<TArgs extends Array<any> = Array<any>> = (...args: TArgs) => Promise<any>;
+export type AnyAsyncFunction = (...args: Array<any>) => Promise<any>;

package/dist/cjs/utils.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"utils.cjs","sources":["../../src/utils.ts"],"sourcesContent":["export function bindInstanceMethods<T extends Record<string, any>>(\n  instance: T,\n) {\n  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance))\n    .filter((key) => typeof instance[key as keyof T] === 'function')\n    .reduce((acc: any, key) => {\n      const method = instance[key as keyof T]\n      if (typeof method === 'function') {\n        acc[key] = method.bind(instance)\n      }\n      return acc\n    }, {} as T)\n}\n"],"names":[],"mappings":";;AAAO,SAAS,oBACd,UACA;AACA,SAAO,OAAO,oBAAoB,OAAO,eAAe,QAAQ,CAAC,EAC9D,OAAO,CAAC,QAAQ,OAAO,SAAS,GAAc,MAAM,UAAU,EAC9D,OAAO,CAAC,KAAU,QAAQ;AACnB,UAAA,SAAS,SAAS,GAAc;AAClC,QAAA,OAAO,WAAW,YAAY;AAChC,UAAI,GAAG,IAAI,OAAO,KAAK,QAAQ;AAAA,IAAA;AAE1B,WAAA;AAAA,EACT,GAAG,EAAO;AACd;;"}
+{"version":3,"file":"utils.cjs","sources":["../../src/utils.ts"],"sourcesContent":["export function bindInstanceMethods<T extends Record<string, any>>(\n  instance: T,\n): T {\n  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance))\n    .filter((key) => typeof instance[key as keyof T] === 'function')\n    .reduce((acc: any, key) => {\n      const method = instance[key as keyof T]\n      if (typeof method === 'function') {\n        acc[key] = method.bind(instance)\n      }\n      return acc\n    }, {} as T)\n}\n"],"names":[],"mappings":";;AAAO,SAAS,oBACd,UACG;AACH,SAAO,OAAO,oBAAoB,OAAO,eAAe,QAAQ,CAAC,EAC9D,OAAO,CAAC,QAAQ,OAAO,SAAS,GAAc,MAAM,UAAU,EAC9D,OAAO,CAAC,KAAU,QAAQ;AACnB,UAAA,SAAS,SAAS,GAAc;AAClC,QAAA,OAAO,WAAW,YAAY;AAChC,UAAI,GAAG,IAAI,OAAO,KAAK,QAAQ;AAAA,IAAA;AAE1B,WAAA;AAAA,EACT,GAAG,EAAO;AACd;;"}

package/dist/cjs/utils.d.cts

@@ -1 +1 @@
-export declare function bindInstanceMethods<T extends Record<string, any>>(instance: T): any;
+export declare function bindInstanceMethods<T extends Record<string, any>>(instance: T): T;

package/dist/esm/async-debouncer.d.ts

@@ -2,7 +2,7 @@ import { AnyAsyncFunction } from './types.js';
 /**
  * Options for configuring an async debounced function
  */
-export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction, TArgs extends Parameters<TFn>> {
+export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
     /**
      * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
      * Defaults to true.
@@ -16,11 +16,15 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction, TArgs exten
     /**
      * Optional error handler for when the debounced function throws
      */
-    onError?: (error: unknown) => void;
+    onError?: (error: unknown, debouncer: AsyncDebouncer<TFn>) => void;
     /**
-     * Optional function to call when the debounced function is executed
+     * Optional callback to call when the debounced function is executed
      */
-    onExecute?: (debouncer: AsyncDebouncer<TFn, TArgs>) => void;
+    onSettled?: (debouncer: AsyncDebouncer<TFn>) => void;
+    /**
+     * Optional callback to call when the debounced function is executed
+     */
+    onSuccess?: (result: ReturnType<TFn>, debouncer: AsyncDebouncer<TFn>) => void;
     /**
      * Whether to execute on the trailing edge of the timeout.
      * Defaults to true.
@@ -42,71 +46,103 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction, TArgs exten
  * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until
  * the function stops being called for the specified delay period.
  *
+ * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
+ * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+ * instead of setting the result on a state variable from within the debounced function.
+ *
  * @example
  * ```ts
  * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {
- *   await searchAPI(value);
+ *   const results = await searchAPI(value);
+ *   return results; // Return value is preserved
  * }, { wait: 500 });
  *
  * // Called on each keystroke but only executes after 500ms of no typing
- * inputElement.addEventListener('input', () => {
- *   asyncDebouncer.maybeExecute(inputElement.value);
- * });
+ * // Returns the API response directly
+ * const results = await asyncDebouncer.maybeExecute(inputElement.value);
  * ```
  */
-export declare class AsyncDebouncer<TFn extends AnyAsyncFunction, TArgs extends Parameters<TFn>> {
+export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     private fn;
     private _abortController;
-    private _executionCount;
+    private _canLeadingExecute;
+    private _errorCount;
     private _isExecuting;
+    private _isPending;
     private _lastArgs;
+    private _lastResult;
     private _options;
+    private _settleCount;
+    private _successCount;
     private _timeoutId;
-    private _canLeadingExecute;
-    constructor(fn: TFn, initialOptions: AsyncDebouncerOptions<TFn, TArgs>);
+    constructor(fn: TFn, initialOptions: AsyncDebouncerOptions<TFn>);
     /**
      * Updates the debouncer options
      * Returns the new options state
      */
-    setOptions(newOptions: Partial<AsyncDebouncerOptions<TFn, TArgs>>): Required<AsyncDebouncerOptions<TFn, TArgs>>;
+    setOptions(newOptions: Partial<AsyncDebouncerOptions<TFn>>): void;
     /**
      * Returns the current debouncer options
      */
-    getOptions(): Required<AsyncDebouncerOptions<TFn, TArgs>>;
+    getOptions(): Required<AsyncDebouncerOptions<TFn>>;
     /**
      * Attempts to execute the debounced function
      * If a call is already in progress, it will be queued
      */
-    maybeExecute(...args: TArgs): Promise<void>;
+    maybeExecute(...args: Parameters<TFn>): Promise<ReturnType<TFn> | undefined>;
     private executeFunction;
     /**
-     * Cancels any pending execution
+     * Cancel without resetting _canLeadingExecute
+     */
+    private _cancel;
+    /**
+     * Cancels any pending execution or aborts any execution in progress
      */
     cancel(): void;
     /**
-     * Returns the number of times the function has been executed
+     * Returns the last result of the debounced function
+     */
+    getLastResult(): ReturnType<TFn> | undefined;
+    /**
+     * Returns the number of times the function has been executed successfully
+     */
+    getSuccessCount(): number;
+    /**
+     * Returns the number of times the function has settled (completed or errored)
+     */
+    getSettleCount(): number;
+    /**
+     * Returns the number of times the function has errored
      */
-    getExecutionCount(): number;
+    getErrorCount(): number;
     /**
-     * Returns `true` if there is a pending execution
+     * Returns `true` if there is a pending execution queued up for trailing execution
      */
     getIsPending(): boolean;
+    /**
+     * Returns `true` if there is currently an execution in progress
+     */
+    getIsExecuting(): boolean;
 }
 /**
  * Creates an async debounced function that delays execution until after a specified wait time.
  * The debounced function will only execute once the wait period has elapsed without any new calls.
  * If called again during the wait period, the timer resets and a new wait period begins.
  *
+ * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
+ * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+ * instead of setting the result on a state variable from within the debounced function.
+ *
  * @example
  * ```ts
  * const debounced = asyncDebounce(async (value: string) => {
- *   await saveToAPI(value);
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
  * }, { wait: 1000 });
  *
  * // Will only execute once, 1 second after the last call
- * await debounced("first");  // Cancelled
- * await debounced("second"); // Cancelled
- * await debounced("third");  // Executes after 1s
+ * // Returns the API response directly
+ * const result = await debounced("third");
  * ```
  */
-export declare function asyncDebounce<TFn extends AnyAsyncFunction, TArgs extends Parameters<TFn>>(fn: TFn, initialOptions: Omit<AsyncDebouncerOptions<TFn, TArgs>, 'enabled'>): (...args: TArgs) => Promise<void>;
+export declare function asyncDebounce<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: Omit<AsyncDebouncerOptions<TFn>, 'enabled'>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;

package/dist/esm/async-debouncer.js

@@ -1,21 +1,26 @@
 const defaultOptions = {
   enabled: true,
   leading: false,
-  trailing: true,
   onError: () => {
   },
-  onExecute: () => {
+  onSettled: () => {
+  },
+  onSuccess: () => {
   },
+  trailing: true,
   wait: 0
 };
 class AsyncDebouncer {
   constructor(fn, initialOptions) {
     this.fn = fn;
     this._abortController = null;
-    this._executionCount = 0;
+    this._canLeadingExecute = true;
+    this._errorCount = 0;
     this._isExecuting = false;
+    this._isPending = false;
+    this._settleCount = 0;
+    this._successCount = 0;
     this._timeoutId = null;
-    this._canLeadingExecute = true;
     this._options = {
       ...defaultOptions,
       ...initialOptions
@@ -26,11 +31,10 @@ class AsyncDebouncer {
    * Returns the new options state
    */
   setOptions(newOptions) {
-    this._options = {
-      ...this._options,
-      ...newOptions
-    };
-    return this._options;
+    this._options = { ...this._options, ...newOptions };
+    if (!this._options.enabled) {
+      this._isPending = false;
+    }
   }
   /**
    * Returns the current debouncer options
@@ -43,53 +47,50 @@ class AsyncDebouncer {
    * If a call is already in progress, it will be queued
    */
   async maybeExecute(...args) {
-    this.cancel();
+    this._cancel();
     this._lastArgs = args;
     if (this._options.leading && this._canLeadingExecute) {
       this._canLeadingExecute = false;
       await this.executeFunction(...args);
+      return this._lastResult;
+    }
+    if (this._options.trailing) {
+      this._isPending = true;
     }
     return new Promise((resolve) => {
       this._timeoutId = setTimeout(async () => {
-        if (this._isExecuting) {
-          resolve();
-          return;
+        if (this._options.trailing && this._lastArgs) {
+          await this.executeFunction(...this._lastArgs);
         }
         this._canLeadingExecute = true;
-        if (this._options.trailing) {
-          this._abortController = new AbortController();
-          try {
-            this._isExecuting = true;
-            if (this._lastArgs) {
-              await this.executeFunction(...this._lastArgs);
-            }
-          } catch (error) {
-            try {
-              this._options.onError(error);
-            } catch {
-              console.error("Error in error handler", error);
-            }
-          } finally {
-            this._isExecuting = false;
-            this._abortController = null;
-            resolve();
-          }
-        } else {
-          resolve();
-        }
+        resolve(this._lastResult);
       }, this._options.wait);
     });
   }
   async executeFunction(...args) {
-    if (!this._options.enabled) return;
-    this._executionCount++;
-    await this.fn(...args);
-    this._options.onExecute(this);
+    if (!this._options.enabled) return void 0;
+    this._abortController = new AbortController();
+    try {
+      this._isExecuting = true;
+      this._lastResult = await this.fn(...args);
+      this._successCount++;
+      this._options.onSuccess(this._lastResult, this);
+    } catch (error) {
+      this._errorCount++;
+      this._options.onError(error, this);
+    } finally {
+      this._isExecuting = false;
+      this._isPending = false;
+      this._settleCount++;
+      this._abortController = null;
+      this._options.onSettled(this);
+    }
+    return this._lastResult;
   }
   /**
-   * Cancels any pending execution
+   * Cancel without resetting _canLeadingExecute
    */
-  cancel() {
+  _cancel() {
     if (this._timeoutId) {
       clearTimeout(this._timeoutId);
       this._timeoutId = null;
@@ -99,19 +100,51 @@ class AsyncDebouncer {
       this._abortController = null;
     }
     this._lastArgs = void 0;
+    this._isPending = false;
+    this._isExecuting = false;
+  }
+  /**
+   * Cancels any pending execution or aborts any execution in progress
+   */
+  cancel() {
     this._canLeadingExecute = true;
+    this._cancel();
+  }
+  /**
+   * Returns the last result of the debounced function
+   */
+  getLastResult() {
+    return this._lastResult;
   }
   /**
-   * Returns the number of times the function has been executed
+   * Returns the number of times the function has been executed successfully
    */
-  getExecutionCount() {
-    return this._executionCount;
+  getSuccessCount() {
+    return this._successCount;
   }
   /**
-   * Returns `true` if there is a pending execution
+   * Returns the number of times the function has settled (completed or errored)
+   */
+  getSettleCount() {
+    return this._settleCount;
+  }
+  /**
+   * Returns the number of times the function has errored
+   */
+  getErrorCount() {
+    return this._errorCount;
+  }
+  /**
+   * Returns `true` if there is a pending execution queued up for trailing execution
    */
   getIsPending() {
-    return this._options.enabled && (this._timeoutId !== null || this._isExecuting);
+    return this._options.enabled && this._isPending;
+  }
+  /**
+   * Returns `true` if there is currently an execution in progress
+   */
+  getIsExecuting() {
+    return this._isExecuting;
   }
 }
 function asyncDebounce(fn, initialOptions) {

package/dist/esm/async-debouncer.js.map

@@ -1 +1 @@
-{"version":3,"file":"async-debouncer.js","sources":["../../src/async-debouncer.ts"],"sourcesContent":["import type { AnyAsyncFunction } from './types'\n\n/**\n * Options for configuring an async debounced function\n */\nexport interface AsyncDebouncerOptions<\n  TFn extends AnyAsyncFunction,\n  TArgs extends Parameters<TFn>,\n> {\n  /**\n   * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Optional error handler for when the debounced function throws\n   */\n  onError?: (error: unknown) => void\n  /**\n   * Optional function to call when the debounced function is executed\n   */\n  onExecute?: (debouncer: AsyncDebouncer<TFn, TArgs>) => void\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Delay in milliseconds to wait after the last call before executing\n   * Defaults to 0ms\n   */\n  wait: number\n}\n\nconst defaultOptions: Required<AsyncDebouncerOptions<any, any>> = {\n  enabled: true,\n  leading: false,\n  trailing: true,\n  onError: () => {},\n  onExecute: () => {},\n  wait: 0,\n}\n\n/**\n * A class that creates an async debounced function.\n *\n * Debouncing ensures that a function is only executed after a specified delay has passed since its last invocation.\n * Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing\n * or input changes where you only want to execute the handler after the events have stopped occurring.\n *\n * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until\n * the function stops being called for the specified delay period.\n *\n * @example\n * ```ts\n * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {\n *   await searchAPI(value);\n * }, { wait: 500 });\n *\n * // Called on each keystroke but only executes after 500ms of no typing\n * inputElement.addEventListener('input', () => {\n *   asyncDebouncer.maybeExecute(inputElement.value);\n * });\n * ```\n */\nexport class AsyncDebouncer<\n  TFn extends AnyAsyncFunction,\n  TArgs extends Parameters<TFn>,\n> {\n  private _abortController: AbortController | null = null\n  private _executionCount = 0\n  private _isExecuting = false\n  private _lastArgs: TArgs | undefined\n  private _options: Required<AsyncDebouncerOptions<TFn, TArgs>>\n  private _timeoutId: ReturnType<typeof setTimeout> | null = null\n  private _canLeadingExecute = true\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncDebouncerOptions<TFn, TArgs>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the debouncer options\n   * Returns the new options state\n   */\n  setOptions(\n    newOptions: Partial<AsyncDebouncerOptions<TFn, TArgs>>,\n  ): Required<AsyncDebouncerOptions<TFn, TArgs>> {\n    this._options = {\n      ...this._options,\n      ...newOptions,\n    }\n    return this._options\n  }\n\n  /**\n   * Returns the current debouncer options\n   */\n  getOptions(): Required<AsyncDebouncerOptions<TFn, TArgs>> {\n    return this._options\n  }\n\n  /**\n   * Attempts to execute the debounced function\n   * If a call is already in progress, it will be queued\n   */\n  async maybeExecute(...args: TArgs): Promise<void> {\n    this.cancel()\n    this._lastArgs = args\n\n    // Handle leading execution\n    if (this._options.leading && this._canLeadingExecute) {\n      this._canLeadingExecute = false\n      await this.executeFunction(...args)\n    }\n\n    return new Promise((resolve) => {\n      this._timeoutId = setTimeout(async () => {\n        if (this._isExecuting) {\n          resolve()\n          return\n        }\n\n        this._canLeadingExecute = true\n        // Execute trailing only if enabled\n        if (this._options.trailing) {\n          this._abortController = new AbortController()\n          try {\n            this._isExecuting = true\n            if (this._lastArgs) {\n              await this.executeFunction(...this._lastArgs)\n            }\n          } catch (error) {\n            try {\n              this._options.onError(error)\n            } catch {\n              console.error('Error in error handler', error)\n            }\n          } finally {\n            this._isExecuting = false\n            this._abortController = null\n            resolve()\n          }\n        } else {\n          resolve()\n        }\n      }, this._options.wait)\n    })\n  }\n\n  private async executeFunction(...args: TArgs): Promise<void> {\n    if (!this._options.enabled) return\n    this._executionCount++\n    await this.fn(...args)\n    this._options.onExecute(this)\n  }\n\n  /**\n   * Cancels any pending execution\n   */\n  cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n    if (this._abortController) {\n      this._abortController.abort()\n      this._abortController = null\n    }\n    this._lastArgs = undefined\n    this._canLeadingExecute = true\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this._executionCount\n  }\n\n  /**\n   * Returns `true` if there is a pending execution\n   */\n  getIsPending(): boolean {\n    return (\n      this._options.enabled && (this._timeoutId !== null || this._isExecuting)\n    )\n  }\n}\n\n/**\n * Creates an async debounced function that delays execution until after a specified wait time.\n * The debounced function will only execute once the wait period has elapsed without any new calls.\n * If called again during the wait period, the timer resets and a new wait period begins.\n *\n * @example\n * ```ts\n * const debounced = asyncDebounce(async (value: string) => {\n *   await saveToAPI(value);\n * }, { wait: 1000 });\n *\n * // Will only execute once, 1 second after the last call\n * await debounced(\"first\");  // Cancelled\n * await debounced(\"second\"); // Cancelled\n * await debounced(\"third\");  // Executes after 1s\n * ```\n */\nexport function asyncDebounce<\n  TFn extends AnyAsyncFunction,\n  TArgs extends Parameters<TFn>,\n>(fn: TFn, initialOptions: Omit<AsyncDebouncerOptions<TFn, TArgs>, 'enabled'>) {\n  const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)\n  return asyncDebouncer.maybeExecute.bind(asyncDebouncer)\n}\n"],"names":[],"mappings":"AAuCA,MAAM,iBAA4D;AAAA,EAChE,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,SAAS,MAAM;AAAA,EAAC;AAAA,EAChB,WAAW,MAAM;AAAA,EAAC;AAAA,EAClB,MAAM;AACR;AAwBO,MAAM,eAGX;AAAA,EASA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AATV,SAAQ,mBAA2C;AACnD,SAAQ,kBAAkB;AAC1B,SAAQ,eAAe;AAGvB,SAAQ,aAAmD;AAC3D,SAAQ,qBAAqB;AAM3B,SAAK,WAAW;AAAA,MACd,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YAC6C;AAC7C,SAAK,WAAW;AAAA,MACd,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,aAA0D;AACxD,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,MAAM,gBAAgB,MAA4B;AAChD,SAAK,OAAO;AACZ,SAAK,YAAY;AAGjB,QAAI,KAAK,SAAS,WAAW,KAAK,oBAAoB;AACpD,WAAK,qBAAqB;AACpB,YAAA,KAAK,gBAAgB,GAAG,IAAI;AAAA,IAAA;AAG7B,WAAA,IAAI,QAAQ,CAAC,YAAY;AACzB,WAAA,aAAa,WAAW,YAAY;AACvC,YAAI,KAAK,cAAc;AACb,kBAAA;AACR;AAAA,QAAA;AAGF,aAAK,qBAAqB;AAEtB,YAAA,KAAK,SAAS,UAAU;AACrB,eAAA,mBAAmB,IAAI,gBAAgB;AACxC,cAAA;AACF,iBAAK,eAAe;AACpB,gBAAI,KAAK,WAAW;AAClB,oBAAM,KAAK,gBAAgB,GAAG,KAAK,SAAS;AAAA,YAAA;AAAA,mBAEvC,OAAO;AACV,gBAAA;AACG,mBAAA,SAAS,QAAQ,KAAK;AAAA,YAAA,QACrB;AACE,sBAAA,MAAM,0BAA0B,KAAK;AAAA,YAAA;AAAA,UAC/C,UACA;AACA,iBAAK,eAAe;AACpB,iBAAK,mBAAmB;AAChB,oBAAA;AAAA,UAAA;AAAA,QACV,OACK;AACG,kBAAA;AAAA,QAAA;AAAA,MACV,GACC,KAAK,SAAS,IAAI;AAAA,IAAA,CACtB;AAAA,EAAA;AAAA,EAGH,MAAc,mBAAmB,MAA4B;AACvD,QAAA,CAAC,KAAK,SAAS,QAAS;AACvB,SAAA;AACC,UAAA,KAAK,GAAG,GAAG,IAAI;AAChB,SAAA,SAAS,UAAU,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAM9B,SAAe;AACb,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAAA,IAAA;AAEpB,QAAI,KAAK,kBAAkB;AACzB,WAAK,iBAAiB,MAAM;AAC5B,WAAK,mBAAmB;AAAA,IAAA;AAE1B,SAAK,YAAY;AACjB,SAAK,qBAAqB;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAM5B,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,eAAwB;AACtB,WACE,KAAK,SAAS,YAAY,KAAK,eAAe,QAAQ,KAAK;AAAA,EAAA;AAGjE;AAmBgB,SAAA,cAGd,IAAS,gBAAoE;AAC7E,QAAM,iBAAiB,IAAI,eAAe,IAAI,cAAc;AACrD,SAAA,eAAe,aAAa,KAAK,cAAc;AACxD;"}
+{"version":3,"file":"async-debouncer.js","sources":["../../src/async-debouncer.ts"],"sourcesContent":["import type { AnyAsyncFunction } from './types'\n\n/**\n * Options for configuring an async debounced function\n */\nexport interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {\n  /**\n   * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Optional error handler for when the debounced function throws\n   */\n  onError?: (error: unknown, debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Optional callback to call when the debounced function is executed\n   */\n  onSettled?: (debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Optional callback to call when the debounced function is executed\n   */\n  onSuccess?: (result: ReturnType<TFn>, debouncer: AsyncDebouncer<TFn>) => void\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Delay in milliseconds to wait after the last call before executing\n   * Defaults to 0ms\n   */\n  wait: number\n}\n\nconst defaultOptions: Required<AsyncDebouncerOptions<any>> = {\n  enabled: true,\n  leading: false,\n  onError: () => {},\n  onSettled: () => {},\n  onSuccess: () => {},\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates an async debounced function.\n *\n * Debouncing ensures that a function is only executed after a specified delay has passed since its last invocation.\n * Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing\n * or input changes where you only want to execute the handler after the events have stopped occurring.\n *\n * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until\n * the function stops being called for the specified delay period.\n *\n * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the debounced function.\n *\n * @example\n * ```ts\n * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {\n *   const results = await searchAPI(value);\n *   return results; // Return value is preserved\n * }, { wait: 500 });\n *\n * // Called on each keystroke but only executes after 500ms of no typing\n * // Returns the API response directly\n * const results = await asyncDebouncer.maybeExecute(inputElement.value);\n * ```\n */\nexport class AsyncDebouncer<TFn extends AnyAsyncFunction> {\n  private _abortController: AbortController | null = null\n  private _canLeadingExecute = true\n  private _errorCount = 0\n  private _isExecuting = false\n  private _isPending = false\n  private _lastArgs: Parameters<TFn> | undefined\n  private _lastResult: ReturnType<TFn> | undefined\n  private _options: Required<AsyncDebouncerOptions<TFn>>\n  private _settleCount = 0\n  private _successCount = 0\n  private _timeoutId: NodeJS.Timeout | null = null\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncDebouncerOptions<TFn>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the debouncer options\n   * Returns the new options state\n   */\n  setOptions(newOptions: Partial<AsyncDebouncerOptions<TFn>>): void {\n    this._options = { ...this._options, ...newOptions }\n\n    // End the pending state if the debouncer is disabled\n    if (!this._options.enabled) {\n      this._isPending = false\n    }\n  }\n\n  /**\n   * Returns the current debouncer options\n   */\n  getOptions(): Required<AsyncDebouncerOptions<TFn>> {\n    return this._options\n  }\n\n  /**\n   * Attempts to execute the debounced function\n   * If a call is already in progress, it will be queued\n   */\n  async maybeExecute(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    this._cancel()\n    this._lastArgs = args\n\n    // Handle leading execution\n    if (this._options.leading && this._canLeadingExecute) {\n      this._canLeadingExecute = false\n      await this.executeFunction(...args)\n      return this._lastResult\n    }\n\n    // Handle trailing execution\n    if (this._options.trailing) {\n      this._isPending = true\n    }\n\n    return new Promise((resolve) => {\n      this._timeoutId = setTimeout(async () => {\n        // Execute trailing if enabled\n        if (this._options.trailing && this._lastArgs) {\n          await this.executeFunction(...this._lastArgs)\n        }\n\n        // Reset state and resolve\n        this._canLeadingExecute = true\n        resolve(this._lastResult)\n      }, this._options.wait)\n    })\n  }\n\n  private async executeFunction(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    if (!this._options.enabled) return undefined\n    this._abortController = new AbortController()\n    try {\n      this._isExecuting = true\n      this._lastResult = await this.fn(...args) // EXECUTE!\n      this._successCount++\n      this._options.onSuccess(this._lastResult!, this)\n    } catch (error) {\n      this._errorCount++\n      this._options.onError(error, this)\n    } finally {\n      this._isExecuting = false\n      this._isPending = false\n      this._settleCount++\n      this._abortController = null\n      this._options.onSettled(this)\n    }\n    return this._lastResult\n  }\n\n  /**\n   * Cancel without resetting _canLeadingExecute\n   */\n  private _cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n    if (this._abortController) {\n      this._abortController.abort()\n      this._abortController = null\n    }\n    this._lastArgs = undefined\n    this._isPending = false\n    this._isExecuting = false\n  }\n\n  /**\n   * Cancels any pending execution or aborts any execution in progress\n   */\n  cancel(): void {\n    this._canLeadingExecute = true\n    this._cancel()\n  }\n\n  /**\n   * Returns the last result of the debounced function\n   */\n  getLastResult(): ReturnType<TFn> | undefined {\n    return this._lastResult\n  }\n\n  /**\n   * Returns the number of times the function has been executed successfully\n   */\n  getSuccessCount(): number {\n    return this._successCount\n  }\n\n  /**\n   * Returns the number of times the function has settled (completed or errored)\n   */\n  getSettleCount(): number {\n    return this._settleCount\n  }\n\n  /**\n   * Returns the number of times the function has errored\n   */\n  getErrorCount(): number {\n    return this._errorCount\n  }\n\n  /**\n   * Returns `true` if there is a pending execution queued up for trailing execution\n   */\n  getIsPending(): boolean {\n    return this._options.enabled && this._isPending\n  }\n\n  /**\n   * Returns `true` if there is currently an execution in progress\n   */\n  getIsExecuting(): boolean {\n    return this._isExecuting\n  }\n}\n\n/**\n * Creates an async debounced function that delays execution until after a specified wait time.\n * The debounced function will only execute once the wait period has elapsed without any new calls.\n * If called again during the wait period, the timer resets and a new wait period begins.\n *\n * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the debounced function.\n *\n * @example\n * ```ts\n * const debounced = asyncDebounce(async (value: string) => {\n *   const result = await saveToAPI(value);\n *   return result; // Return value is preserved\n * }, { wait: 1000 });\n *\n * // Will only execute once, 1 second after the last call\n * // Returns the API response directly\n * const result = await debounced(\"third\");\n * ```\n */\nexport function asyncDebounce<TFn extends AnyAsyncFunction>(\n  fn: TFn,\n  initialOptions: Omit<AsyncDebouncerOptions<TFn>, 'enabled'>,\n) {\n  const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)\n  return asyncDebouncer.maybeExecute.bind(asyncDebouncer)\n}\n"],"names":[],"mappings":"AAwCA,MAAM,iBAAuD;AAAA,EAC3D,SAAS;AAAA,EACT,SAAS;AAAA,EACT,SAAS,MAAM;AAAA,EAAC;AAAA,EAChB,WAAW,MAAM;AAAA,EAAC;AAAA,EAClB,WAAW,MAAM;AAAA,EAAC;AAAA,EAClB,UAAU;AAAA,EACV,MAAM;AACR;AA4BO,MAAM,eAA6C;AAAA,EAaxD,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AAbV,SAAQ,mBAA2C;AACnD,SAAQ,qBAAqB;AAC7B,SAAQ,cAAc;AACtB,SAAQ,eAAe;AACvB,SAAQ,aAAa;AAIrB,SAAQ,eAAe;AACvB,SAAQ,gBAAgB;AACxB,SAAQ,aAAoC;AAM1C,SAAK,WAAW;AAAA,MACd,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WAAW,YAAuD;AAChE,SAAK,WAAW,EAAE,GAAG,KAAK,UAAU,GAAG,WAAW;AAG9C,QAAA,CAAC,KAAK,SAAS,SAAS;AAC1B,WAAK,aAAa;AAAA,IAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAMF,aAAmD;AACjD,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,MAAM,gBACD,MACmC;AACtC,SAAK,QAAQ;AACb,SAAK,YAAY;AAGjB,QAAI,KAAK,SAAS,WAAW,KAAK,oBAAoB;AACpD,WAAK,qBAAqB;AACpB,YAAA,KAAK,gBAAgB,GAAG,IAAI;AAClC,aAAO,KAAK;AAAA,IAAA;AAIV,QAAA,KAAK,SAAS,UAAU;AAC1B,WAAK,aAAa;AAAA,IAAA;AAGb,WAAA,IAAI,QAAQ,CAAC,YAAY;AACzB,WAAA,aAAa,WAAW,YAAY;AAEvC,YAAI,KAAK,SAAS,YAAY,KAAK,WAAW;AAC5C,gBAAM,KAAK,gBAAgB,GAAG,KAAK,SAAS;AAAA,QAAA;AAI9C,aAAK,qBAAqB;AAC1B,gBAAQ,KAAK,WAAW;AAAA,MAAA,GACvB,KAAK,SAAS,IAAI;AAAA,IAAA,CACtB;AAAA,EAAA;AAAA,EAGH,MAAc,mBACT,MACmC;AACtC,QAAI,CAAC,KAAK,SAAS,QAAgB,QAAA;AAC9B,SAAA,mBAAmB,IAAI,gBAAgB;AACxC,QAAA;AACF,WAAK,eAAe;AACpB,WAAK,cAAc,MAAM,KAAK,GAAG,GAAG,IAAI;AACnC,WAAA;AACL,WAAK,SAAS,UAAU,KAAK,aAAc,IAAI;AAAA,aACxC,OAAO;AACT,WAAA;AACA,WAAA,SAAS,QAAQ,OAAO,IAAI;AAAA,IAAA,UACjC;AACA,WAAK,eAAe;AACpB,WAAK,aAAa;AACb,WAAA;AACL,WAAK,mBAAmB;AACnB,WAAA,SAAS,UAAU,IAAI;AAAA,IAAA;AAE9B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMN,UAAgB;AACtB,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAAA,IAAA;AAEpB,QAAI,KAAK,kBAAkB;AACzB,WAAK,iBAAiB,MAAM;AAC5B,WAAK,mBAAmB;AAAA,IAAA;AAE1B,SAAK,YAAY;AACjB,SAAK,aAAa;AAClB,SAAK,eAAe;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMtB,SAAe;AACb,SAAK,qBAAqB;AAC1B,SAAK,QAAQ;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMf,gBAA6C;AAC3C,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,kBAA0B;AACxB,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,iBAAyB;AACvB,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,gBAAwB;AACtB,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,eAAwB;AACf,WAAA,KAAK,SAAS,WAAW,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMvC,iBAA0B;AACxB,WAAO,KAAK;AAAA,EAAA;AAEhB;AAuBgB,SAAA,cACd,IACA,gBACA;AACA,QAAM,iBAAiB,IAAI,eAAe,IAAI,cAAc;AACrD,SAAA,eAAe,aAAa,KAAK,cAAc;AACxD;"}

package/dist/esm/async-queuer.d.ts

@@ -9,6 +9,16 @@ export interface AsyncQueuerOptions<TValue> {
      * Maximum number of concurrent tasks to process
      */
     concurrency?: number;
+    /**
+     * Maximum time in milliseconds that an item can stay in the queue
+     * If not provided, items will never expire
+     */
+    expirationDuration?: number;
+    /**
+     * Function to determine if an item has expired
+     * If provided, this overrides the expirationDuration behavior
+     */
+    getIsExpired?: (item: () => Promise<TValue>, addedAt: number) => boolean;
     /**
      * Default position to get items from during processing
      * @default 'front'
@@ -47,7 +57,11 @@ export interface AsyncQueuerOptions<TValue> {
      */
     onReject?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void;
     /**
-     * Whether the queuer should start processing tasks immediately
+     * Callback fired whenever an item expires in the queuer
+     */
+    onExpire?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void;
+    /**
+     * Whether the queuer should start processing tasks immediately or not.
      */
     started?: boolean;
     /**
@@ -65,6 +79,7 @@ export interface AsyncQueuerOptions<TValue> {
  * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
  * - Pause/resume task processing
  * - Task cancellation
+ * - Item expiration to clear stale items from the queue
  *
  * Tasks are processed concurrently up to the configured concurrency limit. When a task completes,
  * the next pending task is processed if below the concurrency limit.
@@ -89,7 +104,9 @@ export declare class AsyncQueuer<TValue> {
     private _activeItems;
     private _executionCount;
     private _rejectionCount;
+    private _expirationCount;
     private _items;
+    private _itemTimestamps;
     private _onErrorCallbacks;
     private _onSettledCallbacks;
     private _onSuccessCallbacks;
@@ -100,7 +117,7 @@ export declare class AsyncQueuer<TValue> {
      * Updates the queuer options
      * Returns the new options state
      */
-    setOptions(newOptions: Partial<AsyncQueuerOptions<TValue>>): AsyncQueuerOptions<TValue>;
+    setOptions(newOptions: Partial<AsyncQueuerOptions<TValue>>): void;
     /**
      * Returns the current queuer options
      */
@@ -109,6 +126,10 @@ export declare class AsyncQueuer<TValue> {
      * Processes items in the queuer
      */
     private tick;
+    /**
+     * Checks for and removes expired items from the queuer
+     */
+    private checkExpiredItems;
     /**
      * Starts the queuer and processes items
      */
@@ -191,6 +212,10 @@ export declare class AsyncQueuer<TValue> {
      * Adds a callback to be called when a task is settled
      */
     onSettled(cb: (result: TValue | Error) => void): () => void;
+    /**
+     * Returns the number of items that have expired from the queuer
+     */
+    getExpirationCount(): number;
 }
 /**
  * Creates a new AsyncQueuer instance with the given options and returns a bound addItem function.
@@ -209,6 +234,6 @@ export declare class AsyncQueuer<TValue> {
  * @param options - Configuration options for the AsyncQueuer
  * @returns A bound addItem function that can be used to add tasks to the queuer
  */
-export declare function asyncQueue<TValue>(options?: AsyncQueuerOptions<TValue>): (fn: (() => Promise<TValue>) & {
+export declare function asyncQueue<TValue>(options?: Omit<AsyncQueuerOptions<TValue>, 'started'>): (fn: (() => Promise<TValue>) & {
     priority?: number;
 }, position?: QueuePosition, runOnUpdate?: boolean) => Promise<TValue>;