@tanstack/pacer 0.1.0 → 0.2.0

package/src/throttler.ts

@@ -1,7 +1,12 @@
+import type { AnyFunction } from './types'
+
 /**
  * Options for configuring a throttled function
  */
-export interface ThrottlerOptions {
+export interface ThrottlerOptions<
+  TFn extends AnyFunction,
+  TArgs extends Parameters<TFn>,
+> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -12,6 +17,10 @@ export interface ThrottlerOptions {
    * Defaults to true.
    */
   leading?: boolean
+  /**
+   * Callback function that is called after the function is executed
+   */
+  onExecute?: (throttler: Throttler<TFn, TArgs>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -23,11 +32,12 @@ export interface ThrottlerOptions {
   wait: number
 }
 
-const defaultOptions: Required<ThrottlerOptions> = {
+const defaultOptions: Required<ThrottlerOptions<any, any>> = {
   enabled: true,
   leading: true,
   trailing: true,
   wait: 0,
+  onExecute: () => {},
 }
 
 /**
@@ -41,8 +51,7 @@ const defaultOptions: Required<ThrottlerOptions> = {
  * - Leading: Execute immediately on first call (default: true)
  * - Trailing: Execute after wait period if called during throttle (default: true)
  *
- * For rate limiting or hard API limits, consider using RateLimiter instead.
- * For collapsing rapid-fire events, consider using Debouncer.
+ * For collapsing rapid-fire events where you only care about the last call, consider using Debouncer.
  *
  * @example
  * ```ts
@@ -58,21 +67,19 @@ const defaultOptions: Required<ThrottlerOptions> = {
  * throttler.maybeExecute('123'); // Throttled
  * ```
  */
-export class Throttler<
-  TFn extends (...args: Array<any>) => any,
-  TArgs extends Parameters<TFn>,
-> {
-  private executionCount = 0
-  private lastArgs: TArgs | undefined
-  private lastExecutionTime = 0
-  private options: Required<ThrottlerOptions>
-  private timeoutId: NodeJS.Timeout | undefined
+export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
+  private _executionCount = 0
+  private _lastArgs: TArgs | undefined
+  private _lastExecutionTime = 0
+  private _options: Required<ThrottlerOptions<TFn, TArgs>>
+  private _timeoutId: NodeJS.Timeout | undefined
+  private _isPending = false
 
   constructor(
     private fn: TFn,
-    initialOptions: ThrottlerOptions,
+    initialOptions: ThrottlerOptions<TFn, TArgs>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -83,34 +90,20 @@ export class Throttler<
    * Returns the new options state
    */
   setOptions(
-    newOptions: Partial<ThrottlerOptions>,
-  ): Required<ThrottlerOptions> {
-    this.options = {
-      ...this.options,
+    newOptions: Partial<ThrottlerOptions<TFn, TArgs>>,
+  ): Required<ThrottlerOptions<TFn, TArgs>> {
+    this._options = {
+      ...this._options,
       ...newOptions,
     }
-    return this.options
-  }
-
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount(): number {
-    return this.executionCount
+    return this._options
   }
 
   /**
-   * Returns the last execution time
+   * Returns the current throttler options
    */
-  getLastExecutionTime(): number {
-    return this.lastExecutionTime
-  }
-
-  /**
-   * Returns the next execution time
-   */
-  getNextExecutionTime(): number {
-    return this.lastExecutionTime + this.options.wait
+  getOptions(): Required<ThrottlerOptions<TFn, TArgs>> {
+    return this._options
   }
 
   /**
@@ -137,36 +130,40 @@ export class Throttler<
    */
   maybeExecute(...args: TArgs): void {
     const now = Date.now()
-    const timeSinceLastExecution = now - this.lastExecutionTime
+    const timeSinceLastExecution = now - this._lastExecutionTime
 
     // Handle leading execution
-    if (timeSinceLastExecution >= this.options.wait) {
-      if (this.options.leading) {
+    if (timeSinceLastExecution >= this._options.wait) {
+      if (this._options.leading) {
         this.executeFunction(...args)
       }
-      this.lastExecutionTime = now
+      this._lastExecutionTime = now
+      this._isPending = false
     } else {
       // Store the most recent arguments for potential trailing execution
-      this.lastArgs = args
+      this._lastArgs = args
 
       // Set up trailing execution if not already scheduled
-      if (!this.timeoutId && this.options.trailing) {
-        this.timeoutId = setTimeout(() => {
-          if (this.lastArgs) {
-            this.executeFunction(...this.lastArgs)
-            this.lastArgs = undefined
+      if (!this._timeoutId && this._options.trailing) {
+        this._isPending = true
+        this._timeoutId = setTimeout(() => {
+          if (this._lastArgs) {
+            this.executeFunction(...this._lastArgs)
+            this._lastArgs = undefined
           }
-          this.lastExecutionTime = Date.now()
-          this.timeoutId = undefined
-        }, this.options.wait - timeSinceLastExecution)
+          this._lastExecutionTime = Date.now()
+          this._timeoutId = undefined
+          this._isPending = false
+          this._options.onExecute(this)
+        }, this._options.wait - timeSinceLastExecution)
       }
     }
   }
 
   private executeFunction(...args: TArgs): void {
-    if (!this.options.enabled) return
-    this.executionCount++
-    this.fn(...args)
+    if (!this._options.enabled) return
+    this.fn(...args) // EXECUTE!
+    this._executionCount++
   }
 
   /**
@@ -179,12 +176,41 @@ export class Throttler<
    * Has no effect if there is no pending execution.
    */
   cancel(): void {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-      this.timeoutId = undefined
-      this.lastArgs = undefined
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId)
+      this._timeoutId = undefined
+      this._lastArgs = undefined
+      this._isPending = false
     }
   }
+
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount(): number {
+    return this._executionCount
+  }
+
+  /**
+   * Returns `true` if there is a pending execution
+   */
+  getIsPending(): boolean {
+    return this._options.enabled && this._isPending
+  }
+
+  /**
+   * Returns the last execution time
+   */
+  getLastExecutionTime(): number {
+    return this._lastExecutionTime
+  }
+
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime(): number {
+    return this._lastExecutionTime + this._options.wait
+  }
 }
 
 /**
@@ -213,10 +239,10 @@ export class Throttler<
  * });
  * ```
  */
-export function throttle<TFn extends (...args: Array<any>) => any>(
-  fn: TFn,
-  initialOptions: Omit<ThrottlerOptions, 'enabled'>,
-) {
+export function throttle<
+  TFn extends AnyFunction,
+  TArgs extends Parameters<TFn>,
+>(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn, TArgs>, 'enabled'>) {
   const throttler = new Throttler(fn, initialOptions)
   return throttler.maybeExecute.bind(throttler)
 }

package/src/types.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents a function that can be called with any arguments and returns any value.
+ * @template TArgs - The type of the arguments the function can be called with.
+ * @returns The return value of the function.
+ */
+export type AnyFunction<TArgs extends Array<any> = Array<any>> = (
+  ...args: TArgs
+) => any
+
+/**
+ * Represents an asynchronous function that can be called with any arguments and returns a promise.
+ * @template TArgs - The type of the arguments the function can be called with.
+ * @returns A promise that resolves to the return value of the function.
+ */
+export type AnyAsyncFunction<TArgs extends Array<any> = Array<any>> = (
+  ...args: TArgs
+) => Promise<any>

package/src/utils.ts

@@ -0,0 +1,13 @@
+export function bindInstanceMethods<T extends Record<string, any>>(
+  instance: T,
+) {
+  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance))
+    .filter((key) => typeof instance[key as keyof T] === 'function')
+    .reduce((acc: any, key) => {
+      const method = instance[key as keyof T]
+      if (typeof method === 'function') {
+        acc[key] = method.bind(instance)
+      }
+      return acc
+    }, {} as T)
+}