@tanstack/pacer 0.4.0 → 0.6.0

package/dist/cjs/async-debouncer.cjs

@@ -1,14 +1,9 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("./utils.cjs");
 const defaultOptions = {
   enabled: true,
   leading: false,
-  onError: () => {
-  },
-  onSettled: () => {
-  },
-  onSuccess: () => {
-  },
   trailing: true,
   wait: 0
 };
@@ -25,7 +20,8 @@ class AsyncDebouncer {
     this._timeoutId = null;
     this._options = {
       ...defaultOptions,
-      ...initialOptions
+      ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError
     };
   }
   /**
@@ -45,8 +41,30 @@ class AsyncDebouncer {
     return this._options;
   }
   /**
-   * Attempts to execute the debounced function
-   * If a call is already in progress, it will be queued
+   * Returns the current debouncer enabled state
+   */
+  getEnabled() {
+    return !!utils.parseFunctionOrValue(this._options.enabled, this);
+  }
+  /**
+   * Returns the current debouncer wait state
+   */
+  getWait() {
+    return utils.parseFunctionOrValue(this._options.wait, this);
+  }
+  /**
+   * Attempts to execute the debounced function.
+   * If a call is already in progress, it will be queued.
+   *
+   * Error Handling:
+   * - If the debounced function throws and no `onError` handler is configured,
+   *   the error will be thrown from this method.
+   * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+   *   and this method will return undefined.
+   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+   *
+   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+   * @throws The error from the debounced function if no onError handler is configured
    */
   async maybeExecute(...args) {
     this._cancel();
@@ -66,26 +84,32 @@ class AsyncDebouncer {
         }
         this._canLeadingExecute = true;
         resolve(this._lastResult);
-      }, this._options.wait);
+      }, this.getWait());
     });
   }
   async executeFunction(...args) {
-    if (!this._options.enabled) return void 0;
+    var _a, _b, _c, _d, _e, _f;
+    if (!this.getEnabled()) 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);
+      (_b = (_a = this._options).onSuccess) == null ? void 0 : _b.call(_a, this._lastResult, this);
     } catch (error) {
       this._errorCount++;
-      this._options.onError(error, this);
+      (_d = (_c = this._options).onError) == null ? void 0 : _d.call(_c, error, this);
+      if (this._options.throwOnError) {
+        throw error;
+      } else {
+        console.error(error);
+      }
     } finally {
       this._isExecuting = false;
       this._isPending = false;
       this._settleCount++;
       this._abortController = null;
-      this._options.onSettled(this);
+      (_f = (_e = this._options).onSettled) == null ? void 0 : _f.call(_e, this);
     }
     return this._lastResult;
   }
@@ -140,7 +164,7 @@ class AsyncDebouncer {
    * Returns `true` if there is a pending execution queued up for trailing execution
    */
   getIsPending() {
-    return this._options.enabled && this._isPending;
+    return this.getEnabled() && this._isPending;
   }
   /**
    * Returns `true` if there is currently an execution in progress

package/dist/cjs/async-debouncer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"async-debouncer.cjs","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":"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"}
+{"version":3,"file":"async-debouncer.cjs","sources":["../../src/async-debouncer.ts"],"sourcesContent":["import { parseFunctionOrValue } from './utils'\nimport type { AnyAsyncFunction, OptionalKeys } 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   * Can be a boolean or a function that returns a boolean.\n   * Defaults to true.\n   */\n  enabled?: boolean | ((debouncer: AsyncDebouncer<TFn>) => 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   * If provided, the handler will be called with the error and debouncer instance.\n   * This can be used alongside throwOnError - the handler will be called before any error is thrown.\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 throw errors when they occur.\n   * Defaults to true if no onError handler is provided, false if an onError handler is provided.\n   * Can be explicitly set to override these defaults.\n   */\n  throwOnError?: boolean\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   * Can be a number or a function that returns a number.\n   * Defaults to 0ms\n   */\n  wait: number | ((debouncer: AsyncDebouncer<TFn>) => number)\n}\n\ntype AsyncDebouncerOptionsWithOptionalCallbacks = OptionalKeys<\n  AsyncDebouncerOptions<any>,\n  'onError' | 'onSettled' | 'onSuccess'\n>\n\nconst defaultOptions: AsyncDebouncerOptionsWithOptionalCallbacks = {\n  enabled: true,\n  leading: false,\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 * Error Handling:\n * - If an error occurs during execution and no `onError` handler is provided, the error will be thrown and propagate up to the caller.\n * - If an `onError` handler is provided, errors will be caught and passed to the handler instead of being thrown.\n * - The error count can be tracked using `getErrorCount()`.\n * - The debouncer maintains its state and can continue to be used after an error occurs.\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 * }, {\n *   wait: 500,\n *   onError: (error) => {\n *     console.error('Search failed:', error);\n *   }\n * });\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 _options: AsyncDebouncerOptionsWithOptionalCallbacks\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 _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      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,\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(): AsyncDebouncerOptions<TFn> {\n    return this._options\n  }\n\n  /**\n   * Returns the current debouncer enabled state\n   */\n  getEnabled(): boolean {\n    return !!parseFunctionOrValue(this._options.enabled, this)\n  }\n\n  /**\n   * Returns the current debouncer wait state\n   */\n  getWait(): number {\n    return parseFunctionOrValue(this._options.wait, this)\n  }\n\n  /**\n   * Attempts to execute the debounced function.\n   * If a call is already in progress, it will be queued.\n   *\n   * Error Handling:\n   * - If the debounced function throws and no `onError` handler is configured,\n   *   the error will be thrown from this method.\n   * - If an `onError` handler is configured, errors will be caught and passed to the handler,\n   *   and this method will return undefined.\n   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.\n   *\n   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError\n   * @throws The error from the debounced function if no onError handler is configured\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.getWait())\n    })\n  }\n\n  private async executeFunction(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    if (!this.getEnabled()) 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      if (this._options.throwOnError) {\n        throw error\n      } else {\n        console.error(error)\n      }\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.getEnabled() && 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 * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and debouncer instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - The error state can be checked using the underlying AsyncDebouncer instance\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\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 * }, {\n *   wait: 1000,\n *   onError: (error) => {\n *     console.error('API call failed:', error);\n *   },\n *   throwOnError: true // Will both log the error and throw it\n * });\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: AsyncDebouncerOptions<TFn>,\n) {\n  const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)\n  return asyncDebouncer.maybeExecute.bind(asyncDebouncer)\n}\n"],"names":["parseFunctionOrValue"],"mappings":"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"}

package/dist/cjs/async-debouncer.d.cts

@@ -5,16 +5,19 @@ import { AnyAsyncFunction } from './types.cjs';
 export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
     /**
      * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
+     * Can be a boolean or a function that returns a boolean.
      * Defaults to true.
      */
-    enabled?: boolean;
+    enabled?: boolean | ((debouncer: AsyncDebouncer<TFn>) => boolean);
     /**
      * Whether to execute on the leading edge of the timeout.
      * Defaults to false.
      */
     leading?: boolean;
     /**
-     * Optional error handler for when the debounced function throws
+     * Optional error handler for when the debounced function throws.
+     * If provided, the handler will be called with the error and debouncer instance.
+     * This can be used alongside throwOnError - the handler will be called before any error is thrown.
      */
     onError?: (error: unknown, debouncer: AsyncDebouncer<TFn>) => void;
     /**
@@ -25,16 +28,23 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
      * Optional callback to call when the debounced function is executed
      */
     onSuccess?: (result: ReturnType<TFn>, debouncer: AsyncDebouncer<TFn>) => void;
+    /**
+     * Whether to throw errors when they occur.
+     * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+     * Can be explicitly set to override these defaults.
+     */
+    throwOnError?: boolean;
     /**
      * Whether to execute on the trailing edge of the timeout.
      * Defaults to true.
      */
     trailing?: boolean;
     /**
-     * Delay in milliseconds to wait after the last call before executing
+     * Delay in milliseconds to wait after the last call before executing.
+     * Can be a number or a function that returns a number.
      * Defaults to 0ms
      */
-    wait: number;
+    wait: number | ((debouncer: AsyncDebouncer<TFn>) => number);
 }
 /**
  * A class that creates an async debounced function.
@@ -50,12 +60,23 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
  * 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.
  *
+ * Error Handling:
+ * - If an error occurs during execution and no `onError` handler is provided, the error will be thrown and propagate up to the caller.
+ * - If an `onError` handler is provided, errors will be caught and passed to the handler instead of being thrown.
+ * - The error count can be tracked using `getErrorCount()`.
+ * - The debouncer maintains its state and can continue to be used after an error occurs.
+ *
  * @example
  * ```ts
  * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {
  *   const results = await searchAPI(value);
  *   return results; // Return value is preserved
- * }, { wait: 500 });
+ * }, {
+ *   wait: 500,
+ *   onError: (error) => {
+ *     console.error('Search failed:', error);
+ *   }
+ * });
  *
  * // Called on each keystroke but only executes after 500ms of no typing
  * // Returns the API response directly
@@ -64,6 +85,7 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
  */
 export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     private fn;
+    private _options;
     private _abortController;
     private _canLeadingExecute;
     private _errorCount;
@@ -71,7 +93,6 @@ export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     private _isPending;
     private _lastArgs;
     private _lastResult;
-    private _options;
     private _settleCount;
     private _successCount;
     private _timeoutId;
@@ -84,10 +105,28 @@ export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     /**
      * Returns the current debouncer options
      */
-    getOptions(): Required<AsyncDebouncerOptions<TFn>>;
+    getOptions(): AsyncDebouncerOptions<TFn>;
     /**
-     * Attempts to execute the debounced function
-     * If a call is already in progress, it will be queued
+     * Returns the current debouncer enabled state
+     */
+    getEnabled(): boolean;
+    /**
+     * Returns the current debouncer wait state
+     */
+    getWait(): number;
+    /**
+     * Attempts to execute the debounced function.
+     * If a call is already in progress, it will be queued.
+     *
+     * Error Handling:
+     * - If the debounced function throws and no `onError` handler is configured,
+     *   the error will be thrown from this method.
+     * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+     *   and this method will return undefined.
+     * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+     *
+     * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+     * @throws The error from the debounced function if no onError handler is configured
      */
     maybeExecute(...args: Parameters<TFn>): Promise<ReturnType<TFn> | undefined>;
     private executeFunction;
@@ -133,16 +172,29 @@ export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
  * 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.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and debouncer instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - The error state can be checked using the underlying AsyncDebouncer instance
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ *
  * @example
  * ```ts
  * const debounced = asyncDebounce(async (value: string) => {
  *   const result = await saveToAPI(value);
  *   return result; // Return value is preserved
- * }, { wait: 1000 });
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   },
+ *   throwOnError: true // Will both log the error and throw it
+ * });
  *
  * // Will only execute once, 1 second after the last call
  * // Returns the API response directly
  * const result = await debounced("third");
  * ```
  */
-export declare function asyncDebounce<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: Omit<AsyncDebouncerOptions<TFn>, 'enabled'>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+export declare function asyncDebounce<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncDebouncerOptions<TFn>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;