@tanstack/pacer 0.2.0 → 0.4.0

package/src/async-throttler.ts

@@ -3,23 +3,37 @@ import type { AnyAsyncFunction } from './types'
 /**
  * Options for configuring an async throttled function
  */
-export interface AsyncThrottlerOptions<
-  TFn extends AnyAsyncFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
    */
   enabled?: boolean
+  /**
+   * Whether to execute the function immediately when called
+   * Defaults to true
+   */
+  leading?: boolean
   /**
    * Optional error handler for when the throttled function throws
    */
-  onError?: (error: unknown) => void
+  onError?: (error: unknown, asyncThrottler: AsyncThrottler<TFn>) => void
   /**
    * Optional function to call when the throttled function is executed
    */
-  onExecute?: (throttler: AsyncThrottler<TFn, TArgs>) => void
+  onSettled?: (asyncThrottler: AsyncThrottler<TFn>) => void
+  /**
+   * Optional function to call when the throttled function is executed
+   */
+  onSuccess?: (
+    result: ReturnType<TFn>,
+    asyncThrottler: AsyncThrottler<TFn>,
+  ) => void
+  /**
+   * Whether to execute the function on the trailing edge of the wait period
+   * Defaults to true
+   */
+  trailing?: boolean
   /**
    * Time window in milliseconds during which the function can only be executed once
    * Defaults to 0ms
@@ -27,10 +41,13 @@ export interface AsyncThrottlerOptions<
   wait: number
 }
 
-const defaultOptions: Required<AsyncThrottlerOptions<any, any>> = {
+const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
   enabled: true,
+  leading: true,
   onError: () => {},
-  onExecute: () => {},
+  onSettled: () => {},
+  onSuccess: () => {},
+  trailing: true,
   wait: 0,
 }
 
@@ -41,37 +58,41 @@ const defaultOptions: Required<AsyncThrottlerOptions<any, any>> = {
  * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a
  * regular interval regardless of how often it's called.
  *
+ * Unlike the non-async Throttler, this async version supports returning values from the throttled 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 throttled function.
+ *
  * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
  * ensure a maximum execution frequency.
  *
  * @example
  * ```ts
  * const throttler = new AsyncThrottler(async (value: string) => {
- *   await saveToAPI(value);
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
  * }, { wait: 1000 });
  *
  * // Will only execute once per second no matter how often called
- * inputElement.addEventListener('input', () => {
- *   throttler.maybeExecute(inputElement.value);
- * });
+ * // Returns the API response directly
+ * const result = await throttler.maybeExecute(inputElement.value);
  * ```
  */
-export class AsyncThrottler<
-  TFn extends AnyAsyncFunction,
-  TArgs extends Parameters<TFn>,
-> {
-  private _options: Required<AsyncThrottlerOptions<TFn, TArgs>>
+export class AsyncThrottler<TFn extends AnyAsyncFunction> {
+  private _options: Required<AsyncThrottlerOptions<TFn>>
   private _abortController: AbortController | null = null
-  private _executionCount = 0
+  private _errorCount = 0
   private _isExecuting = false
-  private _isPending = false
-  private _lastArgs: TArgs | undefined
+  private _lastArgs: Parameters<TFn> | undefined
   private _lastExecutionTime = 0
+  private _lastResult: ReturnType<TFn> | undefined
   private _nextExecutionTime = 0
+  private _settleCount = 0
+  private _successCount = 0
+  private _timeoutId: NodeJS.Timeout | null = null
 
   constructor(
     private fn: TFn,
-    initialOptions: AsyncThrottlerOptions<TFn, TArgs>,
+    initialOptions: AsyncThrottlerOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -83,20 +104,19 @@ export class AsyncThrottler<
    * Updates the throttler options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<AsyncThrottlerOptions<TFn, TArgs>>,
-  ): Required<AsyncThrottlerOptions<TFn, TArgs>> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
+  setOptions(newOptions: Partial<AsyncThrottlerOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
+
+    // End the pending state if the debouncer is disabled
+    if (!this._options.enabled) {
+      this.cancel()
     }
-    return this._options
   }
 
   /**
    * Returns the current options
    */
-  getOptions(): Required<AsyncThrottlerOptions<TFn, TArgs>> {
+  getOptions(): Required<AsyncThrottlerOptions<TFn>> {
     return this._options
   }
 
@@ -104,84 +124,82 @@ export class AsyncThrottler<
    * Attempts to execute the throttled function
    * If a call is already in progress, it may be blocked or queued depending on the `wait` option
    */
-  async maybeExecute(...args: TArgs): Promise<void> {
-    this._lastArgs = args
-    if (this._isPending) return
-    this._isPending = true
+  async maybeExecute(
+    ...args: Parameters<TFn>
+  ): Promise<ReturnType<TFn> | undefined> {
+    const now = Date.now()
+    const timeSinceLastExecution = now - this._lastExecutionTime
 
-    this._abortController = new AbortController()
-    const signal = this._abortController.signal
+    // Handle leading execution
+    if (this._options.leading && timeSinceLastExecution >= this._options.wait) {
+      await this.executeFunction(...args)
+      return this._lastResult
+    } else {
+      // Store the most recent arguments for potential trailing execution
+      this._lastArgs = args
 
-    try {
-      while (this._isExecuting) {
-        await this.delay(this._options.wait, signal)
-      }
+      return new Promise((resolve) => {
+        // Clear any existing timeout to ensure we use the latest arguments
+        if (this._timeoutId) {
+          clearTimeout(this._timeoutId)
+        }
 
-      while (Date.now() < this._nextExecutionTime) {
-        await this.delay(this._nextExecutionTime - Date.now(), signal)
-      }
+        // Set up trailing execution if enabled
+        if (this._options.trailing) {
+          const _timeSinceLastExecution = this._lastExecutionTime
+            ? now - this._lastExecutionTime
+            : 0
+          const timeoutDuration = this._options.wait - _timeSinceLastExecution
+          this._timeoutId = setTimeout(async () => {
+            if (this._lastArgs !== undefined) {
+              await this.executeFunction(...this._lastArgs)
+            }
+            resolve(this._lastResult)
+          }, timeoutDuration)
+        }
+      })
+    }
+  }
 
-      this._isPending = false
+  private async executeFunction(
+    ...args: Parameters<TFn>
+  ): Promise<ReturnType<TFn> | undefined> {
+    if (!this._options.enabled || this._isExecuting) return undefined
+    this._abortController = new AbortController()
+    try {
       this._isExecuting = true
-
-      await this.executeFunction(...this._lastArgs)
+      this._lastResult = await this.fn(...args) // EXECUTE!
+      this._successCount++
+      this._options.onSuccess(this._lastResult!, this)
     } catch (error) {
-      if (error instanceof Error && error.name === 'AbortError') {
-        return // Silent return on cancellation
-      }
-      try {
-        this._options.onError(error)
-      } catch {
-        // Ignore errors from error handler
-      }
+      this._errorCount++
+      this._options.onError(error, this)
     } finally {
-      this._lastExecutionTime = Date.now()
-      this._nextExecutionTime = this._lastExecutionTime + this._options.wait
       this._isExecuting = false
+      this._settleCount++
       this._abortController = null
+      this._lastExecutionTime = Date.now()
+      this._nextExecutionTime = this._lastExecutionTime + this._options.wait
+      this._options.onSettled(this)
     }
-  }
-
-  private delay(ms: number, signal: AbortSignal): Promise<void> {
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(resolve, ms)
-      signal.addEventListener(
-        'abort',
-        () => {
-          clearTimeout(timeout)
-          reject(new Error('AbortError'))
-        },
-        { once: true },
-      )
-    })
-  }
-
-  private async executeFunction(...args: TArgs): Promise<void> {
-    if (!this._options.enabled) return
-    this._executionCount++
-    await this.fn(...args)
-    this._options.onExecute(this)
+    return this._lastResult
   }
 
   /**
-   * Cancels any pending execution
+   * Cancels any pending execution or aborts any execution in progress
    */
   cancel(): void {
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId)
+      this._timeoutId = null
+    }
     if (this._abortController) {
       this._abortController.abort()
       this._abortController = null
     }
-    this._isPending = false
     this._lastArgs = undefined
   }
 
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount(): number {
-    return this._executionCount
-  }
-
   /**
    * Returns the last execution time
    */
@@ -196,11 +214,46 @@ export class AsyncThrottler<
     return this._nextExecutionTime
   }
 
+  /**
+   * 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 the current pending state
    */
   getIsPending(): boolean {
-    return this._isPending
+    return this._options.enabled && !!this._timeoutId
+  }
+
+  /**
+   * Returns the current executing state
+   */
+  getIsExecuting(): boolean {
+    return this._isExecuting
   }
 }
 
@@ -209,21 +262,26 @@ export class AsyncThrottler<
  * The throttled function will execute at most once per wait period, even if called multiple times.
  * If called while executing, it will wait until execution completes before scheduling the next call.
  *
+ * Unlike the non-async Throttler, this async version supports returning values from the throttled 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 throttled function.
+ *
  * @example
  * ```ts
- * const throttled = asyncThrottle(async () => {
- *   await someAsyncOperation();
+ * const throttled = asyncThrottle(async (value: string) => {
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
  * }, { wait: 1000 });
  *
  * // This will execute at most once per second
- * await throttled();
- * await throttled(); // Waits 1 second before executing
+ * // Returns the API response directly
+ * const result = await throttled(inputElement.value);
  * ```
  */
-export function asyncThrottle<
-  TFn extends AnyAsyncFunction,
-  TArgs extends Parameters<TFn>,
->(fn: TFn, initialOptions: Omit<AsyncThrottlerOptions<TFn, TArgs>, 'enabled'>) {
+export function asyncThrottle<TFn extends AnyAsyncFunction>(
+  fn: TFn,
+  initialOptions: Omit<AsyncThrottlerOptions<TFn>, 'enabled'>,
+) {
   const asyncThrottler = new AsyncThrottler(fn, initialOptions)
   return asyncThrottler.maybeExecute.bind(asyncThrottler)
 }

package/src/debouncer.ts

@@ -3,10 +3,7 @@ import type { AnyFunction } from './types'
 /**
  * Options for configuring a debounced function
  */
-export interface DebouncerOptions<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface DebouncerOptions<TFn extends AnyFunction> {
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -14,13 +11,14 @@ export interface DebouncerOptions<
   enabled?: boolean
   /**
    * Whether to execute on the leading edge of the timeout.
+   * The first call will execute immediately and the rest will wait the delay.
    * Defaults to false.
    */
   leading?: boolean
   /**
    * Callback function that is called after the function is executed
    */
-  onExecute?: (debouncer: Debouncer<TFn, TArgs>) => void
+  onExecute?: (debouncer: Debouncer<TFn>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -33,12 +31,12 @@ export interface DebouncerOptions<
   wait: number
 }
 
-const defaultOptions: Required<DebouncerOptions<any, any>> = {
+const defaultOptions: Required<DebouncerOptions<any>> = {
   enabled: true,
   leading: false,
+  onExecute: () => {},
   trailing: true,
   wait: 0,
-  onExecute: () => {},
 }
 
 /**
@@ -64,16 +62,16 @@ const defaultOptions: Required<DebouncerOptions<any, any>> = {
  * });
  * ```
  */
-export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
+export class Debouncer<TFn extends AnyFunction> {
   private _canLeadingExecute = true
-  private _isPending = false
   private _executionCount = 0
-  private _options: Required<DebouncerOptions<TFn, TArgs>>
+  private _isPending = false
+  private _options: Required<DebouncerOptions<TFn>>
   private _timeoutId: NodeJS.Timeout | undefined
 
   constructor(
     private fn: TFn,
-    initialOptions: DebouncerOptions<TFn, TArgs>,
+    initialOptions: DebouncerOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -85,26 +83,19 @@ export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * Updates the debouncer options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<DebouncerOptions<TFn, TArgs>>,
-  ): Required<DebouncerOptions<TFn, TArgs>> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
-    }
+  setOptions(newOptions: Partial<DebouncerOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
 
     // End the pending state if the debouncer is disabled
     if (!this._options.enabled) {
       this._isPending = false
     }
-
-    return this._options
   }
 
   /**
    * Returns the current debouncer options
    */
-  getOptions(): Required<DebouncerOptions<TFn, TArgs>> {
+  getOptions(): Required<DebouncerOptions<TFn>> {
     return this._options
   }
 
@@ -112,35 +103,37 @@ export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * Attempts to execute the debounced function
    * If a call is already in progress, it will be queued
    */
-  maybeExecute(...args: TArgs): void {
+  maybeExecute(...args: Parameters<TFn>): void {
+    let _didLeadingExecute = false
+
     // Handle leading execution
     if (this._options.leading && this._canLeadingExecute) {
-      this.executeFunction(...args)
       this._canLeadingExecute = false
+      _didLeadingExecute = true
+      this.executeFunction(...args)
     }
 
-    // Start pending state
-    if (this._options.leading || this._options.trailing) {
+    // Start pending state to indicate that the debouncer is waiting for the trailing edge
+    if (this._options.trailing) {
       this._isPending = true
     }
 
     // Clear any existing timeout
     if (this._timeoutId) clearTimeout(this._timeoutId)
 
-    // Set new timeout that will reset canLeadingExecute
+    // Set new timeout that will reset canLeadingExecute and execute trailing only if enabled and did not execute leading
     this._timeoutId = setTimeout(() => {
       this._canLeadingExecute = true
-      this._isPending = false
-      // Execute trailing only if enabled
-      if (this._options.trailing) {
+      if (this._options.trailing && !_didLeadingExecute) {
         this.executeFunction(...args)
       }
     }, this._options.wait)
   }
 
-  private executeFunction(...args: TArgs): void {
-    if (!this._options.enabled) return
+  private executeFunction(...args: Parameters<TFn>): void {
+    if (!this._options.enabled) return undefined
     this.fn(...args) // EXECUTE!
+    this._isPending = false
     this._executionCount++
     this._options.onExecute(this)
   }
@@ -193,8 +186,8 @@ export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
  */
 export function debounce<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<DebouncerOptions<TFn, Parameters<TFn>>, 'enabled'>,
-) {
+  initialOptions: Omit<DebouncerOptions<TFn>, 'enabled'>,
+): (...args: Parameters<TFn>) => void {
   const debouncer = new Debouncer(fn, initialOptions)
   return debouncer.maybeExecute.bind(debouncer)
 }