@tanstack/pacer 0.5.0 → 0.6.0

package/src/async-debouncer.ts

@@ -1,5 +1,5 @@
 import { parseFunctionOrValue } from './utils'
-import type { AnyAsyncFunction } from './types'
+import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 /**
  * Options for configuring an async debounced function
@@ -17,7 +17,9 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
    */
   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
   /**
@@ -28,6 +30,12 @@ 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.
@@ -41,12 +49,14 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
   wait: number | ((debouncer: AsyncDebouncer<TFn>) => number)
 }
 
-const defaultOptions: Required<AsyncDebouncerOptions<any>> = {
+type AsyncDebouncerOptionsWithOptionalCallbacks = OptionalKeys<
+  AsyncDebouncerOptions<any>,
+  'onError' | 'onSettled' | 'onSuccess'
+>
+
+const defaultOptions: AsyncDebouncerOptionsWithOptionalCallbacks = {
   enabled: true,
   leading: false,
-  onError: () => {},
-  onSettled: () => {},
-  onSuccess: () => {},
   trailing: true,
   wait: 0,
 }
@@ -65,12 +75,23 @@ const defaultOptions: Required<AsyncDebouncerOptions<any>> = {
  * 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
@@ -78,6 +99,7 @@ const defaultOptions: Required<AsyncDebouncerOptions<any>> = {
  * ```
  */
 export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
+  private _options: AsyncDebouncerOptionsWithOptionalCallbacks
   private _abortController: AbortController | null = null
   private _canLeadingExecute = true
   private _errorCount = 0
@@ -85,7 +107,6 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   private _isPending = false
   private _lastArgs: Parameters<TFn> | undefined
   private _lastResult: ReturnType<TFn> | undefined
-  private _options: Required<AsyncDebouncerOptions<TFn>>
   private _settleCount = 0
   private _successCount = 0
   private _timeoutId: NodeJS.Timeout | null = null
@@ -97,6 +118,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     this._options = {
       ...defaultOptions,
       ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
   }
 
@@ -116,7 +138,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   /**
    * Returns the current debouncer options
    */
-  getOptions(): Required<AsyncDebouncerOptions<TFn>> {
+  getOptions(): AsyncDebouncerOptions<TFn> {
     return this._options
   }
 
@@ -124,7 +146,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
    * Returns the current debouncer enabled state
    */
   getEnabled(): boolean {
-    return parseFunctionOrValue(this._options.enabled, this)
+    return !!parseFunctionOrValue(this._options.enabled, this)
   }
 
   /**
@@ -135,8 +157,18 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   }
 
   /**
-   * Attempts to execute the debounced function
-   * If a call is already in progress, it will be queued
+   * 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: Parameters<TFn>
@@ -179,16 +211,21 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
       this._isExecuting = true
       this._lastResult = await this.fn(...args) // EXECUTE!
       this._successCount++
-      this._options.onSuccess(this._lastResult!, this)
+      this._options.onSuccess?.(this._lastResult!, this)
     } catch (error) {
       this._errorCount++
-      this._options.onError(error, this)
+      this._options.onError?.(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)
+      this._options.onSettled?.(this)
     }
     return this._lastResult
   }
@@ -270,12 +307,25 @@ export 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