@tanstack/pacer 0.1.0 → 0.3.0

package/src/rate-limiter.ts

@@ -1,29 +1,9 @@
-/**
- * Information about a rate limit rejection
- */
-export interface RateLimitRejectionInfo {
-  /**
-   * Number of milliseconds until the next execution will be possible
-   */
-  msUntilNextWindow: number
-  /**
-   * Current number of executions in the window
-   */
-  currentExecutions: number
-  /**
-   * Maximum allowed executions per window
-   */
-  limit: number
-  /**
-   * Total number of rejections that have occurred
-   */
-  rejectionCount: number
-}
+import type { AnyFunction } from './types'
 
 /**
  * Options for configuring a rate-limited function
  */
-export interface RateLimiterOptions {
+export interface RateLimiterOptions<TFn extends AnyFunction> {
   /**
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -34,18 +14,24 @@ export interface RateLimiterOptions {
    */
   limit: number
   /**
-   * Time window in milliseconds within which the limit applies
+   * Callback function that is called after the function is executed
    */
-  window: number
+  onExecute?: (rateLimiter: RateLimiter<TFn>) => void
   /**
    * Optional callback function that is called when an execution is rejected due to rate limiting
    */
-  onReject?: (info: RateLimitRejectionInfo) => void
+  onReject?: (rateLimiter: RateLimiter<TFn>) => void
+  /**
+   * Time window in milliseconds within which the limit applies
+   */
+  window: number
 }
 
-const defaultOptions: Required<Omit<RateLimiterOptions, 'onReject'>> = {
+const defaultOptions: Required<RateLimiterOptions<any>> = {
   enabled: true,
   limit: 1,
+  onExecute: () => {},
+  onReject: () => {},
   window: 0,
 }
 
@@ -74,20 +60,17 @@ const defaultOptions: Required<Omit<RateLimiterOptions, 'onReject'>> = {
  * rateLimiter.maybeExecute('123');
  * ```
  */
-export class RateLimiter<
-  TFn extends (...args: Array<any>) => any,
-  TArgs extends Parameters<TFn>,
-> {
-  private executionCount = 0
-  private rejectionCount = 0
-  private executionTimes: Array<number> = []
-  private options: RateLimiterOptions
+export class RateLimiter<TFn extends AnyFunction> {
+  private _executionCount = 0
+  private _rejectionCount = 0
+  private _executionTimes: Array<number> = []
+  private _options: RateLimiterOptions<TFn>
 
   constructor(
     private fn: TFn,
-    initialOptions: RateLimiterOptions,
+    initialOptions: RateLimiterOptions<TFn>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -97,34 +80,15 @@ export class RateLimiter<
    * Updates the rate limiter options
    * Returns the new options state
    */
-  setOptions(newOptions: Partial<RateLimiterOptions>): RateLimiterOptions {
-    this.options = {
-      ...this.options,
-      ...newOptions,
-    }
-    return this.options
-  }
-
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount(): number {
-    return this.executionCount
+  setOptions(newOptions: Partial<RateLimiterOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
   }
 
   /**
-   * Returns the number of times the function has been rejected
+   * Returns the current rate limiter options
    */
-  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<RateLimiterOptions<TFn>> {
+    return this._options as Required<RateLimiterOptions<TFn>>
   }
 
   /**
@@ -142,10 +106,10 @@ export class RateLimiter<
    * rateLimiter.maybeExecute('arg1', 'arg2'); // false
    * ```
    */
-  maybeExecute(...args: TArgs): boolean {
+  maybeExecute(...args: Parameters<TFn>): boolean {
     this.cleanupOldExecutions()
 
-    if (this.executionTimes.length < this.options.limit) {
+    if (this._executionTimes.length < this._options.limit) {
       this.executeFunction(...args)
       return true
     }
@@ -155,45 +119,67 @@ export class RateLimiter<
     return false
   }
 
-  private executeFunction(...args: TArgs): void {
-    if (!this.options.enabled) return
+  private executeFunction(...args: Parameters<TFn>): void {
+    if (!this._options.enabled) return
     const now = Date.now()
-    this.executionCount++
-    this.executionTimes.push(now)
-    this.fn(...args)
+    this._executionCount++
+    this._executionTimes.push(now)
+    this.fn(...args) // execute the function
+    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 {
+    const oldestExecution = Math.min(...this._executionTimes)
+    return oldestExecution + this._options.window - Date.now()
+  }
+
   /**
    * Resets the rate limiter state
    */
   reset(): void {
-    this.executionTimes = []
-    this.executionCount = 0
-    this.rejectionCount = 0
+    this._executionTimes = []
+    this._executionCount = 0
+    this._rejectionCount = 0
   }
 }
 
@@ -214,8 +200,8 @@ export class RateLimiter<
  * const rateLimited = rateLimit(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`);
  *   }
  * });
  *
@@ -227,9 +213,9 @@ export class RateLimiter<
  * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
  * ```
  */
-export function rateLimit<TFn extends (...args: Array<any>) => any>(
+export function rateLimit<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<RateLimiterOptions, 'enabled'>,
+  initialOptions: Omit<RateLimiterOptions<TFn>, 'enabled'>,
 ) {
   const rateLimiter = new RateLimiter(fn, initialOptions)
   return rateLimiter.maybeExecute.bind(rateLimiter)

package/src/throttler.ts

@@ -1,7 +1,9 @@
+import type { AnyFunction } from './types'
+
 /**
  * Options for configuring a throttled function
  */
-export interface ThrottlerOptions {
+export interface ThrottlerOptions<TFn extends AnyFunction> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -12,6 +14,10 @@ export interface ThrottlerOptions {
    * Defaults to true.
    */
   leading?: boolean
+  /**
+   * Callback function that is called after the function is executed
+   */
+  onExecute?: (throttler: Throttler<TFn>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -23,9 +29,10 @@ export interface ThrottlerOptions {
   wait: number
 }
 
-const defaultOptions: Required<ThrottlerOptions> = {
+const defaultOptions: Required<ThrottlerOptions<any>> = {
   enabled: true,
   leading: true,
+  onExecute: () => {},
   trailing: true,
   wait: 0,
 }
@@ -41,8 +48,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 +64,18 @@ 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> {
+  private _executionCount = 0
+  private _lastArgs: Parameters<TFn> | undefined
+  private _lastExecutionTime = 0
+  private _options: Required<ThrottlerOptions<TFn>>
+  private _timeoutId: NodeJS.Timeout | undefined
 
   constructor(
     private fn: TFn,
-    initialOptions: ThrottlerOptions,
+    initialOptions: ThrottlerOptions<TFn>,
   ) {
-    this.options = {
+    this._options = {
       ...defaultOptions,
       ...initialOptions,
     }
@@ -82,35 +85,20 @@ export class Throttler<
    * Updates the throttler options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<ThrottlerOptions>,
-  ): Required<ThrottlerOptions> {
-    this.options = {
-      ...this.options,
-      ...newOptions,
-    }
-    return this.options
-  }
-
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount(): number {
-    return this.executionCount
-  }
+  setOptions(newOptions: Partial<ThrottlerOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
 
-  /**
-   * Returns the last execution time
-   */
-  getLastExecutionTime(): number {
-    return this.lastExecutionTime
+    // End the pending state if the debouncer is disabled
+    if (!this._options.enabled) {
+      this.cancel()
+    }
   }
 
   /**
-   * Returns the next execution time
+   * Returns the current throttler options
    */
-  getNextExecutionTime(): number {
-    return this.lastExecutionTime + this.options.wait
+  getOptions(): Required<ThrottlerOptions<TFn>> {
+    return this._options
   }
 
   /**
@@ -135,38 +123,40 @@ export class Throttler<
    * throttled.maybeExecute('c', 'd');
    * ```
    */
-  maybeExecute(...args: TArgs): void {
+  maybeExecute(...args: Parameters<TFn>): 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) {
-        this.executeFunction(...args)
-      }
-      this.lastExecutionTime = now
+    if (this._options.leading && timeSinceLastExecution >= this._options.wait) {
+      this.executeFunction(...args)
     } 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) {
+        const _timeSinceLastExecution = this._lastExecutionTime
+          ? now - this._lastExecutionTime
+          : 0
+        const timeoutDuration = this._options.wait - _timeSinceLastExecution
+        this._timeoutId = setTimeout(() => {
+          if (this._lastArgs !== undefined) {
+            this.executeFunction(...this._lastArgs)
           }
-          this.lastExecutionTime = Date.now()
-          this.timeoutId = undefined
-        }, this.options.wait - timeSinceLastExecution)
+        }, timeoutDuration)
       }
     }
   }
 
-  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
+    this.fn(...args) // EXECUTE!
+    this._executionCount++
+    this._lastExecutionTime = Date.now()
+    this._timeoutId = undefined
+    this._lastArgs = undefined
+    this._options.onExecute(this)
   }
 
   /**
@@ -179,12 +169,40 @@ 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
     }
   }
+
+  /**
+   * Returns the last execution time
+   */
+  getLastExecutionTime(): number {
+    return this._lastExecutionTime
+  }
+
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime(): number {
+    return this._lastExecutionTime + this._options.wait
+  }
+
+  /**
+   * 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._timeoutId
+  }
 }
 
 /**
@@ -213,9 +231,9 @@ export class Throttler<
  * });
  * ```
  */
-export function throttle<TFn extends (...args: Array<any>) => any>(
+export function throttle<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<ThrottlerOptions, 'enabled'>,
+  initialOptions: Omit<ThrottlerOptions<TFn>, 'enabled'>,
 ) {
   const throttler = new Throttler(fn, initialOptions)
   return throttler.maybeExecute.bind(throttler)

package/src/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents a function that can be called with any arguments and returns any value.
+ */
+export type AnyFunction = (...args: Array<any>) => any
+
+/**
+ * Represents an asynchronous function that can be called with any arguments and returns a promise.
+ */
+export type AnyAsyncFunction = (...args: Array<any>) => Promise<any>

package/src/utils.ts

@@ -0,0 +1,13 @@
+export function bindInstanceMethods<T extends Record<string, any>>(
+  instance: T,
+): 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)
+}