@tanstack/pacer 0.4.0 → 0.5.0

package/src/rate-limiter.ts

@@ -1,3 +1,4 @@
+import { parseFunctionOrValue } from './utils'
 import type { AnyFunction } from './types'
 
 /**
@@ -8,11 +9,12 @@ export interface RateLimiterOptions<TFn extends AnyFunction> {
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
    */
-  enabled?: boolean
+  enabled?: boolean | ((rateLimiter: RateLimiter<TFn>) => boolean)
   /**
-   * Maximum number of executions allowed within the time window
+   * Maximum number of executions allowed within the time window.
+   * Can be a number or a callback function that receives the rate limiter instance and returns a number.
    */
-  limit: number
+  limit: number | ((rateLimiter: RateLimiter<TFn>) => number)
   /**
    * Callback function that is called after the function is executed
    */
@@ -22,9 +24,10 @@ export interface RateLimiterOptions<TFn extends AnyFunction> {
    */
   onReject?: (rateLimiter: RateLimiter<TFn>) => void
   /**
-   * Time window in milliseconds within which the limit applies
+   * Time window in milliseconds within which the limit applies.
+   * Can be a number or a callback function that receives the rate limiter instance and returns a number.
    */
-  window: number
+  window: number | ((rateLimiter: RateLimiter<TFn>) => number)
   /**
    * Type of window to use for rate limiting
    * - 'fixed': Uses a fixed window that resets after the window period
@@ -105,6 +108,27 @@ export class RateLimiter<TFn extends AnyFunction> {
     return this._options as Required<RateLimiterOptions<TFn>>
   }
 
+  /**
+   * Returns the current enabled state of the rate limiter
+   */
+  getEnabled(): boolean {
+    return parseFunctionOrValue(this._options.enabled, this)!
+  }
+
+  /**
+   * Returns the current limit of executions allowed within the time window
+   */
+  getLimit(): number {
+    return parseFunctionOrValue(this._options.limit, this)
+  }
+
+  /**
+   * Returns the current time window in milliseconds
+   */
+  getWindow(): number {
+    return parseFunctionOrValue(this._options.window, this)
+  }
+
   /**
    * Attempts to execute the rate-limited function if within the configured limits.
    * Will reject execution if the number of calls in the current window exceeds the limit.
@@ -125,7 +149,7 @@ export class RateLimiter<TFn extends AnyFunction> {
 
     if (this._options.windowType === 'sliding') {
       // For sliding window, we can execute if we have capacity in the current window
-      if (this._executionTimes.length < this._options.limit) {
+      if (this._executionTimes.length < this.getLimit()) {
         this.executeFunction(...args)
         return true
       }
@@ -133,9 +157,9 @@ export class RateLimiter<TFn extends AnyFunction> {
       // For fixed window, we need to check if we're in a new window
       const now = Date.now()
       const oldestExecution = Math.min(...this._executionTimes)
-      const isNewWindow = oldestExecution + this._options.window <= now
+      const isNewWindow = oldestExecution + this.getWindow() <= now
 
-      if (isNewWindow || this._executionTimes.length < this._options.limit) {
+      if (isNewWindow || this._executionTimes.length < this.getLimit()) {
         this.executeFunction(...args)
         return true
       }
@@ -146,7 +170,7 @@ export class RateLimiter<TFn extends AnyFunction> {
   }
 
   private executeFunction(...args: Parameters<TFn>): void {
-    if (!this._options.enabled) return
+    if (!this.getEnabled()) return
     const now = Date.now()
     this._executionCount++
     this._executionTimes.push(now)
@@ -163,7 +187,7 @@ export class RateLimiter<TFn extends AnyFunction> {
 
   private cleanupOldExecutions(): void {
     const now = Date.now()
-    const windowStart = now - this._options.window
+    const windowStart = now - this.getWindow()
     this._executionTimes = this._executionTimes.filter(
       (time) => time > windowStart,
     )
@@ -188,7 +212,7 @@ export class RateLimiter<TFn extends AnyFunction> {
    */
   getRemainingInWindow(): number {
     this.cleanupOldExecutions()
-    return Math.max(0, this._options.limit - this._executionTimes.length)
+    return Math.max(0, this.getLimit() - this._executionTimes.length)
   }
 
   /**
@@ -199,7 +223,7 @@ export class RateLimiter<TFn extends AnyFunction> {
       return 0
     }
     const oldestExecution = Math.min(...this._executionTimes)
-    return oldestExecution + this._options.window - Date.now()
+    return oldestExecution + this.getWindow() - Date.now()
   }
 
   /**
@@ -251,7 +275,7 @@ export class RateLimiter<TFn extends AnyFunction> {
  */
 export function rateLimit<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<RateLimiterOptions<TFn>, 'enabled'>,
+  initialOptions: RateLimiterOptions<TFn>,
 ) {
   const rateLimiter = new RateLimiter(fn, initialOptions)
   return rateLimiter.maybeExecute.bind(rateLimiter)

package/src/throttler.ts

@@ -1,3 +1,4 @@
+import { parseFunctionOrValue } from './utils'
 import type { AnyFunction } from './types'
 
 /**
@@ -6,9 +7,10 @@ import type { AnyFunction } from './types'
 export interface ThrottlerOptions<TFn extends AnyFunction> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
+   * Can be a boolean or a function that returns a boolean.
    * Defaults to true.
    */
-  enabled?: boolean
+  enabled?: boolean | ((throttler: Throttler<TFn>) => boolean)
   /**
    * Whether to execute on the leading edge of the timeout.
    * Defaults to true.
@@ -24,9 +26,11 @@ export interface ThrottlerOptions<TFn extends AnyFunction> {
    */
   trailing?: boolean
   /**
-   * Time window in milliseconds during which the function can only be executed once
+   * Time window in milliseconds during which the function can only be executed once.
+   * Can be a number or a function that returns a number.
+   * Defaults to 0ms
    */
-  wait: number
+  wait: number | ((throttler: Throttler<TFn>) => number)
 }
 
 const defaultOptions: Required<ThrottlerOptions<any>> = {
@@ -101,6 +105,20 @@ export class Throttler<TFn extends AnyFunction> {
     return this._options
   }
 
+  /**
+   * Returns the current enabled state of the throttler
+   */
+  getEnabled(): boolean {
+    return parseFunctionOrValue(this._options.enabled, this)
+  }
+
+  /**
+   * Returns the current wait time in milliseconds
+   */
+  getWait(): number {
+    return parseFunctionOrValue(this._options.wait, this)
+  }
+
   /**
    * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
    *
@@ -126,9 +144,10 @@ export class Throttler<TFn extends AnyFunction> {
   maybeExecute(...args: Parameters<TFn>): void {
     const now = Date.now()
     const timeSinceLastExecution = now - this._lastExecutionTime
+    const wait = this.getWait()
 
     // Handle leading execution
-    if (this._options.leading && timeSinceLastExecution >= this._options.wait) {
+    if (this._options.leading && timeSinceLastExecution >= wait) {
       this.executeFunction(...args)
     } else {
       // Store the most recent arguments for potential trailing execution
@@ -139,7 +158,7 @@ export class Throttler<TFn extends AnyFunction> {
         const _timeSinceLastExecution = this._lastExecutionTime
           ? now - this._lastExecutionTime
           : 0
-        const timeoutDuration = this._options.wait - _timeSinceLastExecution
+        const timeoutDuration = wait - _timeSinceLastExecution
         this._timeoutId = setTimeout(() => {
           if (this._lastArgs !== undefined) {
             this.executeFunction(...this._lastArgs)
@@ -150,7 +169,7 @@ export class Throttler<TFn extends AnyFunction> {
   }
 
   private executeFunction(...args: Parameters<TFn>): void {
-    if (!this._options.enabled) return
+    if (!this.getEnabled()) return
     this.fn(...args) // EXECUTE!
     this._executionCount++
     this._lastExecutionTime = Date.now()
@@ -187,7 +206,7 @@ export class Throttler<TFn extends AnyFunction> {
    * Returns the next execution time
    */
   getNextExecutionTime(): number {
-    return this._lastExecutionTime + this._options.wait
+    return this._lastExecutionTime + this.getWait()
   }
 
   /**
@@ -201,7 +220,7 @@ export class Throttler<TFn extends AnyFunction> {
    * Returns `true` if there is a pending execution
    */
   getIsPending(): boolean {
-    return this._options.enabled && !!this._timeoutId
+    return this.getEnabled() && !!this._timeoutId
   }
 }
 
@@ -233,7 +252,7 @@ export class Throttler<TFn extends AnyFunction> {
  */
 export function throttle<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<ThrottlerOptions<TFn>, 'enabled'>,
+  initialOptions: ThrottlerOptions<TFn>,
 ) {
   const throttler = new Throttler(fn, initialOptions)
   return throttler.maybeExecute.bind(throttler)

package/src/utils.ts

@@ -1,13 +1,27 @@
+import type { AnyFunction } from './types'
+
+export function isFunction<T extends AnyFunction>(value: any): value is T {
+  return typeof value === 'function'
+}
+
+export function parseFunctionOrValue<T, TArgs extends Array<any>>(
+  value: T | ((...args: TArgs) => T),
+  ...args: TArgs
+): T {
+  return isFunction(value) ? value(...args) : value
+}
+
 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) => {
+  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).reduce(
+    (acc: any, key) => {
       const method = instance[key as keyof T]
-      if (typeof method === 'function') {
+      if (isFunction(method)) {
         acc[key] = method.bind(instance)
       }
       return acc
-    }, {} as T)
+    },
+    instance,
+  )
 }