@tanstack/pacer 0.1.0 → 0.3.0

package/src/debouncer.ts

@@ -1,7 +1,9 @@
+import type { AnyFunction } from './types'
+
 /**
  * Options for configuring a debounced function
  */
-export interface DebouncerOptions {
+export interface DebouncerOptions<TFn extends AnyFunction> {
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -9,9 +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>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -24,9 +31,10 @@ export interface DebouncerOptions {
   wait: number
 }
 
-const defaultOptions: Required<DebouncerOptions> = {
+const defaultOptions: Required<DebouncerOptions<any>> = {
   enabled: true,
   leading: false,
+  onExecute: () => {},
   trailing: true,
   wait: 0,
 }
@@ -54,20 +62,18 @@ const defaultOptions: Required<DebouncerOptions> = {
  * });
  * ```
  */
-export class Debouncer<
-  TFn extends (...args: Array<any>) => any,
-  TArgs extends Parameters<TFn>,
-> {
-  private canLeadingExecute = true
-  private executionCount = 0
-  private options: Required<DebouncerOptions>
-  private timeoutId: NodeJS.Timeout | undefined
+export class Debouncer<TFn extends AnyFunction> {
+  private _canLeadingExecute = true
+  private _executionCount = 0
+  private _isPending = false
+  private _options: Required<DebouncerOptions<TFn>>
+  private _timeoutId: NodeJS.Timeout | undefined
 
   constructor(
     private fn: TFn,
-    initialOptions: DebouncerOptions,
+    initialOptions: DebouncerOptions<TFn>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -77,62 +83,85 @@ export class Debouncer<
    * Updates the debouncer options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<DebouncerOptions>,
-  ): Required<DebouncerOptions> {
-    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 number of times the function has been executed
+   * Returns the current debouncer options
    */
-  getExecutionCount(): number {
-    return this.executionCount
+  getOptions(): Required<DebouncerOptions<TFn>> {
+    return this._options
   }
 
   /**
    * 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) {
+    if (this._options.leading && this._canLeadingExecute) {
+      this._canLeadingExecute = false
+      _didLeadingExecute = true
       this.executeFunction(...args)
-      this.canLeadingExecute = false
+    }
+
+    // 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)
+    if (this._timeoutId) clearTimeout(this._timeoutId)
 
-    // Set new timeout that will reset canLeadingExecute
-    this.timeoutId = setTimeout(() => {
-      this.canLeadingExecute = true
-      // Execute trailing only if enabled
-      if (this.options.trailing) {
+    // Set new timeout that will reset canLeadingExecute and execute trailing only if enabled and did not execute leading
+    this._timeoutId = setTimeout(() => {
+      this._canLeadingExecute = true
+      if (this._options.trailing && !_didLeadingExecute) {
         this.executeFunction(...args)
       }
-    }, this.options.wait)
+    }, this._options.wait)
   }
 
-  private executeFunction(...args: TArgs): void {
-    if (!this.options.enabled) return
-    this.executionCount++
-    this.fn(...args)
+  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)
   }
 
   /**
    * Cancels any pending execution
    */
   cancel(): void {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-      this.canLeadingExecute = true
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId)
+      this._canLeadingExecute = true
+      this._isPending = false
     }
   }
+
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount(): number {
+    return this._executionCount
+  }
+
+  /**
+   * Returns `true` if debouncing
+   */
+  getIsPending(): boolean {
+    return this._options.enabled && this._isPending
+  }
 }
 
 /**
@@ -155,10 +184,10 @@ export class Debouncer<
  * inputElement.addEventListener('input', debounced);
  * ```
  */
-export function debounce<TFn extends (...args: Array<any>) => any>(
+export function debounce<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<DebouncerOptions, 'enabled'>,
-) {
+  initialOptions: Omit<DebouncerOptions<TFn>, 'enabled'>,
+): (...args: Parameters<TFn>) => void {
   const debouncer = new Debouncer(fn, initialOptions)
   return debouncer.maybeExecute.bind(debouncer)
 }

package/src/index.ts

@@ -7,3 +7,5 @@ export * from './debouncer'
 export * from './queuer'
 export * from './rate-limiter'
 export * from './throttler'
+export * from './types'
+export * from './utils'