@tanstack/pacer 0.1.0 → 0.2.0

package/src/async-rate-limiter.ts

@@ -1,9 +1,12 @@
-import type { RateLimitRejectionInfo } from './rate-limiter'
+import type { AnyAsyncFunction } from './types'
 
 /**
  * Options for configuring an async rate-limited function
  */
-export interface AsyncRateLimiterOptions {
+export interface AsyncRateLimiterOptions<
+  TFn extends AnyAsyncFunction,
+  TArgs extends Parameters<TFn>,
+> {
   /**
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -14,17 +17,30 @@ export interface AsyncRateLimiterOptions {
    */
   limit: number
   /**
-   * Time window in milliseconds within which the limit applies
+   * Optional error handler for when the rate-limited function throws
    */
-  window: number
+  onError?: (error: unknown) => void
+  /**
+   * Optional function to call when the rate-limited function is executed
+   */
+  onExecute?: (rateLimiter: AsyncRateLimiter<TFn, TArgs>) => void
   /**
    * Optional callback function that is called when an execution is rejected due to rate limiting
    */
-  onReject?: (info: RateLimitRejectionInfo) => void
+  onReject?: (rateLimiter: AsyncRateLimiter<TFn, TArgs>) => void
   /**
-   * Optional error handler for when the rate-limited function throws
+   * Time window in milliseconds within which the limit applies
    */
-  onError?: (error: unknown) => void
+  window: number
+}
+
+const defaultOptions: Required<
+  Omit<AsyncRateLimiterOptions<any, any>, 'limit' | 'window'>
+> = {
+  enabled: true,
+  onReject: () => {},
+  onError: () => {},
+  onExecute: () => {},
 }
 
 /**
@@ -53,20 +69,20 @@ export interface AsyncRateLimiterOptions {
  * ```
  */
 export class AsyncRateLimiter<
-  TFn extends (...args: Array<any>) => Promise<any>,
+  TFn extends AnyAsyncFunction,
   TArgs extends Parameters<TFn>,
 > {
-  private executionCount = 0
-  private rejectionCount = 0
-  private executionTimes: Array<number> = []
-  private options: AsyncRateLimiterOptions
+  private _executionCount = 0
+  private _executionTimes: Array<number> = []
+  private _options: AsyncRateLimiterOptions<TFn, TArgs>
+  private _rejectionCount = 0
 
   constructor(
     private fn: TFn,
-    initialOptions: AsyncRateLimiterOptions,
+    initialOptions: AsyncRateLimiterOptions<TFn, TArgs>,
   ) {
-    this.options = {
-      enabled: true,
+    this._options = {
+      ...defaultOptions,
       ...initialOptions,
     }
   }
@@ -76,35 +92,20 @@ export class AsyncRateLimiter<
    * Returns the new options state
    */
   setOptions(
-    newOptions: Partial<AsyncRateLimiterOptions>,
-  ): AsyncRateLimiterOptions {
-    this.options = {
-      ...this.options,
+    newOptions: Partial<AsyncRateLimiterOptions<TFn, TArgs>>,
+  ): AsyncRateLimiterOptions<TFn, TArgs> {
+    this._options = {
+      ...this._options,
       ...newOptions,
     }
-    return this.options
+    return this._options
   }
 
   /**
-   * Returns the number of times the function has been executed
+   * Returns the current rate limiter options
    */
-  getExecutionCount(): number {
-    return this.executionCount
-  }
-
-  /**
-   * Returns the number of times the function has been rejected
-   */
-  getRejectionCount(): number {
-    return this.rejectionCount
-  }
-
-  /**
-   * Returns the number of remaining executions allowed in the current window
-   */
-  getRemainingInWindow(): number {
-    this.cleanupOldExecutions()
-    return Math.max(0, this.options.limit - this.executionTimes.length)
+  getOptions(): Required<AsyncRateLimiterOptions<TFn, TArgs>> {
+    return this._options as Required<AsyncRateLimiterOptions<TFn, TArgs>>
   }
 
   /**
@@ -126,7 +127,7 @@ export class AsyncRateLimiter<
   async maybeExecute(...args: TArgs): Promise<boolean> {
     this.cleanupOldExecutions()
 
-    if (this.executionTimes.length < this.options.limit) {
+    if (this._executionTimes.length < this._options.limit) {
       await this.executeFunction(...args)
       return true
     }
@@ -136,57 +137,78 @@ export class AsyncRateLimiter<
   }
 
   private async executeFunction(...args: TArgs): Promise<void> {
-    if (!this.options.enabled) return
+    if (!this._options.enabled) return
     const now = Date.now()
-    this.executionCount++
-    this.executionTimes.push(now)
+    this._executionCount++
+    this._executionTimes.push(now)
 
     try {
       await this.fn(...args)
     } catch (error) {
-      if (this.options.onError) {
+      if (this._options.onError) {
         try {
-          this.options.onError(error)
-        } catch {
-          // Ignore errors from error handler
+          this._options.onError(error)
+        } catch (error) {
+          console.error('Error in onError handler', error)
         }
       }
       throw error
     } finally {
+      this._options.onExecute?.(this)
     }
   }
 
   private rejectFunction(): void {
-    this.rejectionCount++
-    if (this.options.onReject) {
-      const oldestExecution = Math.min(...this.executionTimes)
-      const msUntilNextWindow =
-        oldestExecution + this.options.window - Date.now()
-
-      this.options.onReject({
-        msUntilNextWindow,
-        currentExecutions: this.executionTimes.length,
-        limit: this.options.limit,
-        rejectionCount: this.rejectionCount,
-      })
+    this._rejectionCount++
+    if (this._options.onReject) {
+      this._options.onReject(this)
     }
   }
 
   private cleanupOldExecutions(): void {
     const now = Date.now()
-    const windowStart = now - this.options.window
-    this.executionTimes = this.executionTimes.filter(
+    const windowStart = now - this._options.window
+    this._executionTimes = this._executionTimes.filter(
       (time) => time > windowStart,
     )
   }
 
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount(): number {
+    return this._executionCount
+  }
+
+  /**
+   * Returns the number of times the function has been rejected
+   */
+  getRejectionCount(): number {
+    return this._rejectionCount
+  }
+
+  /**
+   * Returns the number of remaining executions allowed in the current window
+   */
+  getRemainingInWindow(): number {
+    this.cleanupOldExecutions()
+    return Math.max(0, this._options.limit - this._executionTimes.length)
+  }
+
+  /**
+   * Returns the number of milliseconds until the next execution will be possible
+   */
+  getMsUntilNextWindow(): number {
+    return this.getRemainingInWindow() * this._options.window
+  }
+
   /**
    * Resets the rate limiter state
    */
   reset(): void {
-    this.executionTimes = []
-    this.executionCount = 0
-    this.rejectionCount = 0
+    this._executionTimes = []
+    this._executionCount = 0
+    this._rejectionCount = 0
   }
 }
 
@@ -207,8 +229,8 @@ export class AsyncRateLimiter<
  * const rateLimited = asyncRateLimit(makeApiCall, {
  *   limit: 5,
  *   window: 60000,
- *   onReject: ({ msUntilNextWindow }) => {
- *     console.log(`Rate limit exceeded. Try again in ${msUntilNextWindow}ms`);
+ *   onReject: (rateLimiter) => {
+ *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }
  * });
  *
@@ -221,8 +243,12 @@ export class AsyncRateLimiter<
  * ```
  */
 export function asyncRateLimit<
-  TFn extends (...args: Array<any>) => Promise<any>,
->(fn: TFn, initialOptions: Omit<AsyncRateLimiterOptions, 'enabled'>) {
+  TFn extends AnyAsyncFunction,
+  TArgs extends Parameters<TFn>,
+>(
+  fn: TFn,
+  initialOptions: Omit<AsyncRateLimiterOptions<TFn, TArgs>, 'enabled'>,
+) {
   const rateLimiter = new AsyncRateLimiter(fn, initialOptions)
   return rateLimiter.maybeExecute.bind(rateLimiter)
 }

package/src/async-throttler.ts

@@ -1,26 +1,36 @@
+import type { AnyAsyncFunction } from './types'
+
 /**
  * Options for configuring an async throttled function
  */
-export interface AsyncThrottlerOptions {
+export interface AsyncThrottlerOptions<
+  TFn extends AnyAsyncFunction,
+  TArgs extends Parameters<TFn>,
+> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
    */
   enabled?: boolean
+  /**
+   * Optional error handler for when the throttled function throws
+   */
+  onError?: (error: unknown) => void
+  /**
+   * Optional function to call when the throttled function is executed
+   */
+  onExecute?: (throttler: AsyncThrottler<TFn, TArgs>) => void
   /**
    * Time window in milliseconds during which the function can only be executed once
    * Defaults to 0ms
    */
   wait: number
-  /**
-   * Optional error handler for when the throttled function throws
-   */
-  onError?: (error: unknown) => void
 }
 
-const defaultOptions: Required<AsyncThrottlerOptions> = {
+const defaultOptions: Required<AsyncThrottlerOptions<any, any>> = {
   enabled: true,
   onError: () => {},
+  onExecute: () => {},
   wait: 0,
 }
 
@@ -47,22 +57,23 @@ const defaultOptions: Required<AsyncThrottlerOptions> = {
  * ```
  */
 export class AsyncThrottler<
-  TFn extends (...args: Array<any>) => Promise<any>,
+  TFn extends AnyAsyncFunction,
   TArgs extends Parameters<TFn>,
 > {
-  private abortController: AbortController | null = null
-  private executionCount = 0
-  private isExecuting = false
-  private isScheduled = false
-  private lastArgs: TArgs | undefined
-  private nextExecutionTime = 0
-  private options: Required<AsyncThrottlerOptions>
+  private _options: Required<AsyncThrottlerOptions<TFn, TArgs>>
+  private _abortController: AbortController | null = null
+  private _executionCount = 0
+  private _isExecuting = false
+  private _isPending = false
+  private _lastArgs: TArgs | undefined
+  private _lastExecutionTime = 0
+  private _nextExecutionTime = 0
 
   constructor(
     private fn: TFn,
-    initialOptions: AsyncThrottlerOptions,
+    initialOptions: AsyncThrottlerOptions<TFn, TArgs>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -73,39 +84,20 @@ export class AsyncThrottler<
    * Returns the new options state
    */
   setOptions(
-    newOptions: Partial<AsyncThrottlerOptions>,
-  ): Required<AsyncThrottlerOptions> {
-    this.options = {
-      ...this.options,
+    newOptions: Partial<AsyncThrottlerOptions<TFn, TArgs>>,
+  ): Required<AsyncThrottlerOptions<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
-  }
-
-  /**
-   * Returns the next execution time
-   */
-  getNextExecutionTime(): number {
-    return this.nextExecutionTime
+    return this._options
   }
 
   /**
-   * Cancels any pending execution
+   * Returns the current options
    */
-  cancel(): void {
-    if (this.abortController) {
-      this.abortController.abort()
-      this.abortController = null
-    }
-    this.isScheduled = false
-    this.lastArgs = undefined
+  getOptions(): Required<AsyncThrottlerOptions<TFn, TArgs>> {
+    return this._options
   }
 
   /**
@@ -113,39 +105,40 @@ export class AsyncThrottler<
    * 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.isScheduled) return
-    this.isScheduled = true
+    this._lastArgs = args
+    if (this._isPending) return
+    this._isPending = true
 
-    this.abortController = new AbortController()
-    const signal = this.abortController.signal
+    this._abortController = new AbortController()
+    const signal = this._abortController.signal
 
     try {
-      while (this.isExecuting) {
-        await this.delay(this.options.wait, signal)
+      while (this._isExecuting) {
+        await this.delay(this._options.wait, signal)
       }
 
-      while (Date.now() < this.nextExecutionTime) {
-        await this.delay(this.nextExecutionTime - Date.now(), signal)
+      while (Date.now() < this._nextExecutionTime) {
+        await this.delay(this._nextExecutionTime - Date.now(), signal)
       }
 
-      this.isScheduled = false
-      this.isExecuting = true
+      this._isPending = false
+      this._isExecuting = true
 
-      await this.executeFunction(...this.lastArgs)
+      await this.executeFunction(...this._lastArgs)
     } catch (error) {
       if (error instanceof Error && error.name === 'AbortError') {
         return // Silent return on cancellation
       }
       try {
-        this.options.onError(error)
+        this._options.onError(error)
       } catch {
         // Ignore errors from error handler
       }
     } finally {
-      this.nextExecutionTime = Date.now() + this.options.wait
-      this.isExecuting = false
-      this.abortController = null
+      this._lastExecutionTime = Date.now()
+      this._nextExecutionTime = this._lastExecutionTime + this._options.wait
+      this._isExecuting = false
+      this._abortController = null
     }
   }
 
@@ -164,9 +157,50 @@ export class AsyncThrottler<
   }
 
   private async executeFunction(...args: TArgs): Promise<void> {
-    if (!this.options.enabled) return
-    this.executionCount++
+    if (!this._options.enabled) return
+    this._executionCount++
     await this.fn(...args)
+    this._options.onExecute(this)
+  }
+
+  /**
+   * Cancels any pending execution
+   */
+  cancel(): void {
+    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
+   */
+  getLastExecutionTime(): number {
+    return this._lastExecutionTime
+  }
+
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime(): number {
+    return this._nextExecutionTime
+  }
+
+  /**
+   * Returns the current pending state
+   */
+  getIsPending(): boolean {
+    return this._isPending
   }
 }
 
@@ -187,8 +221,9 @@ export class AsyncThrottler<
  * ```
  */
 export function asyncThrottle<
-  TFn extends (...args: Array<any>) => Promise<any>,
->(fn: TFn, initialOptions: Omit<AsyncThrottlerOptions, 'enabled'>) {
+  TFn extends AnyAsyncFunction,
+  TArgs extends Parameters<TFn>,
+>(fn: TFn, initialOptions: Omit<AsyncThrottlerOptions<TFn, TArgs>, 'enabled'>) {
   const asyncThrottler = new AsyncThrottler(fn, initialOptions)
   return asyncThrottler.maybeExecute.bind(asyncThrottler)
 }

package/src/debouncer.ts

@@ -1,7 +1,12 @@
+import type { AnyFunction } from './types'
+
 /**
  * Options for configuring a debounced function
  */
-export interface DebouncerOptions {
+export interface DebouncerOptions<
+  TFn extends AnyFunction,
+  TArgs extends Parameters<TFn>,
+> {
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -12,6 +17,10 @@ export interface DebouncerOptions {
    * Defaults to false.
    */
   leading?: boolean
+  /**
+   * Callback function that is called after the function is executed
+   */
+  onExecute?: (debouncer: Debouncer<TFn, TArgs>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -24,11 +33,12 @@ export interface DebouncerOptions {
   wait: number
 }
 
-const defaultOptions: Required<DebouncerOptions> = {
+const defaultOptions: Required<DebouncerOptions<any, any>> = {
   enabled: true,
   leading: false,
   trailing: true,
   wait: 0,
+  onExecute: () => {},
 }
 
 /**
@@ -54,20 +64,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, TArgs extends Parameters<TFn>> {
+  private _canLeadingExecute = true
+  private _isPending = false
+  private _executionCount = 0
+  private _options: Required<DebouncerOptions<TFn, TArgs>>
+  private _timeoutId: NodeJS.Timeout | undefined
 
   constructor(
     private fn: TFn,
-    initialOptions: DebouncerOptions,
+    initialOptions: DebouncerOptions<TFn, TArgs>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -78,20 +86,26 @@ export class Debouncer<
    * Returns the new options state
    */
   setOptions(
-    newOptions: Partial<DebouncerOptions>,
-  ): Required<DebouncerOptions> {
-    this.options = {
-      ...this.options,
+    newOptions: Partial<DebouncerOptions<TFn, TArgs>>,
+  ): Required<DebouncerOptions<TFn, TArgs>> {
+    this._options = {
+      ...this._options,
       ...newOptions,
     }
-    return this.options
+
+    // 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, TArgs>> {
+    return this._options
   }
 
   /**
@@ -100,39 +114,61 @@ export class Debouncer<
    */
   maybeExecute(...args: TArgs): void {
     // Handle leading execution
-    if (this.options.leading && this.canLeadingExecute) {
+    if (this._options.leading && this._canLeadingExecute) {
       this.executeFunction(...args)
-      this.canLeadingExecute = false
+      this._canLeadingExecute = false
+    }
+
+    // Start pending state
+    if (this._options.leading || 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
+    this._timeoutId = setTimeout(() => {
+      this._canLeadingExecute = true
+      this._isPending = false
       // Execute trailing only if enabled
-      if (this.options.trailing) {
+      if (this._options.trailing) {
         this.executeFunction(...args)
       }
-    }, this.options.wait)
+    }, this._options.wait)
   }
 
   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++
+    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,9 +191,9 @@ 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, Parameters<TFn>>, 'enabled'>,
 ) {
   const debouncer = new Debouncer(fn, initialOptions)
   return debouncer.maybeExecute.bind(debouncer)