@tanstack/pacer 0.4.0 → 0.6.0

package/dist/esm/utils.js

@@ -1,13 +1,24 @@
+function isFunction(value) {
+  return typeof value === "function";
+}
+function parseFunctionOrValue(value, ...args) {
+  return isFunction(value) ? value(...args) : value;
+}
 function bindInstanceMethods(instance) {
-  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).filter((key) => typeof instance[key] === "function").reduce((acc, key) => {
-    const method = instance[key];
-    if (typeof method === "function") {
-      acc[key] = method.bind(instance);
-    }
-    return acc;
-  }, {});
+  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).reduce(
+    (acc, key) => {
+      const method = instance[key];
+      if (isFunction(method)) {
+        acc[key] = method.bind(instance);
+      }
+      return acc;
+    },
+    instance
+  );
 }
 export {
-  bindInstanceMethods
+  bindInstanceMethods,
+  isFunction,
+  parseFunctionOrValue
 };
 //# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","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;"}
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["import type { AnyFunction } from './types'\n\nexport function isFunction<T extends AnyFunction>(value: any): value is T {\n  return typeof value === 'function'\n}\n\nexport function parseFunctionOrValue<T, TArgs extends Array<any>>(\n  value: T | ((...args: TArgs) => T),\n  ...args: TArgs\n): T {\n  return isFunction(value) ? value(...args) : value\n}\n\nexport function bindInstanceMethods<T extends Record<string, any>>(\n  instance: T,\n): T {\n  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).reduce(\n    (acc: any, key) => {\n      const method = instance[key as keyof T]\n      if (isFunction(method)) {\n        acc[key] = method.bind(instance)\n      }\n      return acc\n    },\n    instance,\n  )\n}\n"],"names":[],"mappings":"AAEO,SAAS,WAAkC,OAAwB;AACxE,SAAO,OAAO,UAAU;AAC1B;AAEgB,SAAA,qBACd,UACG,MACA;AACH,SAAO,WAAW,KAAK,IAAI,MAAM,GAAG,IAAI,IAAI;AAC9C;AAEO,SAAS,oBACd,UACG;AACH,SAAO,OAAO,oBAAoB,OAAO,eAAe,QAAQ,CAAC,EAAE;AAAA,IACjE,CAAC,KAAU,QAAQ;AACX,YAAA,SAAS,SAAS,GAAc;AAClC,UAAA,WAAW,MAAM,GAAG;AACtB,YAAI,GAAG,IAAI,OAAO,KAAK,QAAQ;AAAA,MAAA;AAE1B,aAAA;AAAA,IACT;AAAA,IACA;AAAA,EACF;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/pacer",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Utilities for debouncing, throttling, rate-limiting, queuing, and more.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -131,8 +131,14 @@
       "types": "./dist/esm/types.d.ts"
     },
     "./utils": {
-      "types": "./dist/esm/utils.d.ts",
-      "default": "./dist/esm/utils.js"
+      "import": {
+        "types": "./dist/esm/utils.d.ts",
+        "default": "./dist/esm/utils.js"
+      },
+      "require": {
+        "types": "./dist/cjs/utils.d.cts",
+        "default": "./dist/cjs/utils.cjs"
+      }
     },
     "./package.json": "./package.json"
   },

package/src/async-debouncer.ts

@@ -1,4 +1,5 @@
-import type { AnyAsyncFunction } from './types'
+import { parseFunctionOrValue } from './utils'
+import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 /**
  * Options for configuring an async debounced function
@@ -6,16 +7,19 @@ import type { AnyAsyncFunction } from './types'
 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
   /**
@@ -26,24 +30,33 @@ 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)
 }
 
-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,
 }
@@ -62,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
@@ -75,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
@@ -82,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
@@ -94,6 +118,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     this._options = {
       ...defaultOptions,
       ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
   }
 
@@ -113,13 +138,37 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   /**
    * Returns the current debouncer options
    */
-  getOptions(): Required<AsyncDebouncerOptions<TFn>> {
+  getOptions(): AsyncDebouncerOptions<TFn> {
     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(): boolean {
+    return !!parseFunctionOrValue(this._options.enabled, this)
+  }
+
+  /**
+   * Returns the current debouncer wait state
+   */
+  getWait(): number {
+    return 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: Parameters<TFn>
@@ -149,29 +198,34 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
         // Reset state and resolve
         this._canLeadingExecute = true
         resolve(this._lastResult)
-      }, this._options.wait)
+      }, this.getWait())
     })
   }
 
   private async executeFunction(
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> {
-    if (!this._options.enabled) return undefined
+    if (!this.getEnabled()) return undefined
     this._abortController = new AbortController()
     try {
       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
   }
@@ -233,7 +287,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
    * Returns `true` if there is a pending execution queued up for trailing execution
    */
   getIsPending(): boolean {
-    return this._options.enabled && this._isPending
+    return this.getEnabled() && this._isPending
   }
 
   /**
@@ -253,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
@@ -267,7 +334,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
  */
 export function asyncDebounce<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  initialOptions: Omit<AsyncDebouncerOptions<TFn>, 'enabled'>,
+  initialOptions: AsyncDebouncerOptions<TFn>,
 ) {
   const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)
   return asyncDebouncer.maybeExecute.bind(asyncDebouncer)