@tanstack/pacer 0.1.0 → 0.3.0

package/dist/esm/utils.js

@@ -0,0 +1,13 @@
+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;
+  }, {});
+}
+export {
+  bindInstanceMethods
+};
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +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;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/pacer",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Utilities for debouncing, throttling, rate-limiting, queuing, and more.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -127,6 +127,13 @@
         "default": "./dist/cjs/throttler.cjs"
       }
     },
+    "./types": {
+      "types": "./dist/esm/types.d.ts"
+    },
+    "./utils": {
+      "types": "./dist/esm/utils.d.ts",
+      "default": "./dist/esm/utils.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,

package/src/async-debouncer.ts

@@ -1,7 +1,9 @@
+import type { AnyAsyncFunction } from './types'
+
 /**
  * Options for configuring an async debounced function
  */
-export interface AsyncDebouncerOptions {
+export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -12,6 +14,18 @@ export interface AsyncDebouncerOptions {
    * Defaults to false.
    */
   leading?: boolean
+  /**
+   * Optional error handler for when the debounced function throws
+   */
+  onError?: (error: unknown, debouncer: AsyncDebouncer<TFn>) => void
+  /**
+   * Optional callback to call when the debounced function is executed
+   */
+  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.
@@ -22,17 +36,15 @@ export interface AsyncDebouncerOptions {
    * Defaults to 0ms
    */
   wait: number
-  /**
-   * Optional error handler for when the debounced function throws
-   */
-  onError?: (error: unknown) => void
 }
 
-const defaultOptions: Required<AsyncDebouncerOptions> = {
+const defaultOptions: Required<AsyncDebouncerOptions<any>> = {
   enabled: true,
   leading: false,
-  trailing: true,
   onError: () => {},
+  onSettled: () => {},
+  onSuccess: () => {},
+  trailing: true,
   wait: 0,
 }
 
@@ -48,33 +60,34 @@ const defaultOptions: Required<AsyncDebouncerOptions> = {
  *
  * @example
  * ```ts
- * const debouncer = new AsyncDebouncer(async (value: string) => {
+ * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {
  *   await searchAPI(value);
  * }, { wait: 500 });
  *
  * // Called on each keystroke but only executes after 500ms of no typing
  * inputElement.addEventListener('input', () => {
- *   debouncer.maybeExecute(inputElement.value);
+ *   asyncDebouncer.maybeExecute(inputElement.value);
  * });
  * ```
  */
-export class AsyncDebouncer<
-  TFn extends (...args: Array<any>) => Promise<any>,
-  TArgs extends Parameters<TFn>,
-> {
-  private abortController: AbortController | null = null
-  private executionCount = 0
-  private isExecuting = false
-  private lastArgs: TArgs | undefined
-  private options: Required<AsyncDebouncerOptions>
-  private timeoutId: ReturnType<typeof setTimeout> | null = null
-  private canLeadingExecute = true
+export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
+  private _abortController: AbortController | null = null
+  private _canLeadingExecute = true
+  private _errorCount = 0
+  private _isExecuting = false
+  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
 
   constructor(
     private fn: TFn,
-    initialOptions: AsyncDebouncerOptions,
+    initialOptions: AsyncDebouncerOptions<TFn>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -84,91 +97,146 @@ export class AsyncDebouncer<
    * Updates the debouncer options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<AsyncDebouncerOptions>,
-  ): Required<AsyncDebouncerOptions> {
-    this.options = {
-      ...this.options,
-      ...newOptions,
-    }
-    return this.options
-  }
+  setOptions(newOptions: Partial<AsyncDebouncerOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
 
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount(): number {
-    return this.executionCount
+    // End the pending state if the debouncer is disabled
+    if (!this._options.enabled) {
+      this._isPending = false
+    }
   }
 
   /**
-   * Cancels any pending execution
+   * Returns the current debouncer options
    */
-  cancel(): void {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-      this.timeoutId = null
-    }
-    if (this.abortController) {
-      this.abortController.abort()
-      this.abortController = null
-    }
-    this.lastArgs = undefined
-    this.canLeadingExecute = true
+  getOptions(): Required<AsyncDebouncerOptions<TFn>> {
+    return this._options
   }
 
   /**
    * Attempts to execute the debounced function
    * If a call is already in progress, it will be queued
    */
-  async maybeExecute(...args: TArgs): Promise<void> {
-    this.cancel()
-    this.lastArgs = args
+  async maybeExecute(
+    ...args: Parameters<TFn>
+  ): Promise<ReturnType<TFn> | undefined> {
+    this._cancel()
+    this._lastArgs = args
 
     // Handle leading execution
-    if (this.options.leading && this.canLeadingExecute) {
-      this.canLeadingExecute = false
+    if (this._options.leading && this._canLeadingExecute) {
+      this._canLeadingExecute = false
       await this.executeFunction(...args)
+      return this._lastResult
+    }
+
+    // Handle trailing execution
+    if (this._options.trailing) {
+      this._isPending = true
     }
 
     return new Promise((resolve) => {
-      this.timeoutId = setTimeout(async () => {
-        if (this.isExecuting) {
-          resolve()
-          return
+      this._timeoutId = setTimeout(async () => {
+        // Execute trailing if enabled
+        if (this._options.trailing && this._lastArgs) {
+          await this.executeFunction(...this._lastArgs)
         }
 
-        this.canLeadingExecute = true
-        // Execute trailing only if enabled
-        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 {
-              // Ignore errors from error handler
-            }
-          } finally {
-            this.isExecuting = false
-            this.abortController = null
-            resolve()
-          }
-        } else {
-          resolve()
-        }
-      }, this.options.wait)
+        // Reset state and resolve
+        this._canLeadingExecute = true
+        resolve(this._lastResult)
+      }, this._options.wait)
     })
   }
 
-  private async executeFunction(...args: TArgs): Promise<void> {
-    if (!this.options.enabled) return
-    this.executionCount++
-    await this.fn(...args)
+  private async executeFunction(
+    ...args: Parameters<TFn>
+  ): Promise<ReturnType<TFn> | undefined> {
+    if (!this._options.enabled) 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)
+    } 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
+  }
+
+  /**
+   * Cancel without resetting _canLeadingExecute
+   */
+  private _cancel(): void {
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId)
+      this._timeoutId = null
+    }
+    if (this._abortController) {
+      this._abortController.abort()
+      this._abortController = null
+    }
+    this._lastArgs = undefined
+    this._isPending = false
+    this._isExecuting = false
+  }
+
+  /**
+   * Cancels any pending execution or aborts any execution in progress
+   */
+  cancel(): void {
+    this._canLeadingExecute = true
+    this._cancel()
+  }
+
+  /**
+   * Returns the last result of the debounced function
+   */
+  getLastResult(): ReturnType<TFn> | undefined {
+    return this._lastResult
+  }
+
+  /**
+   * Returns the number of times the function has been executed successfully
+   */
+  getSuccessCount(): number {
+    return this._successCount
+  }
+
+  /**
+   * Returns the number of times the function has settled (completed or errored)
+   */
+  getSettleCount(): number {
+    return this._settleCount
+  }
+
+  /**
+   * Returns the number of times the function has errored
+   */
+  getErrorCount(): number {
+    return this._errorCount
+  }
+
+  /**
+   * Returns `true` if there is a pending execution queued up for trailing execution
+   */
+  getIsPending(): boolean {
+    return this._options.enabled && this._isPending
+  }
+
+  /**
+   * Returns `true` if there is currently an execution in progress
+   */
+  getIsExecuting(): boolean {
+    return this._isExecuting
   }
 }
 
@@ -189,9 +257,10 @@ export class AsyncDebouncer<
  * await debounced("third");  // Executes after 1s
  * ```
  */
-export function asyncDebounce<
-  TFn extends (...args: Array<any>) => Promise<any>,
->(fn: TFn, initialOptions: Omit<AsyncDebouncerOptions, 'enabled'>) {
+export function asyncDebounce<TFn extends AnyAsyncFunction>(
+  fn: TFn,
+  initialOptions: Omit<AsyncDebouncerOptions<TFn>, 'enabled'>,
+) {
   const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)
   return asyncDebouncer.maybeExecute.bind(asyncDebouncer)
 }