@tanstack/pacer 0.3.0 → 0.5.0

package/src/debouncer.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 DebouncerOptions<TFn extends AnyFunction> {
   /**
    * Whether the debouncer 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 | ((debouncer: Debouncer<TFn>) => boolean)
   /**
    * Whether to execute on the leading edge of the timeout.
    * The first call will execute immediately and the rest will wait the delay.
@@ -25,10 +27,11 @@ export interface DebouncerOptions<TFn extends AnyFunction> {
    */
   trailing?: boolean
   /**
-   * Delay in milliseconds before executing the function
+   * Delay in milliseconds before executing the function.
+   * Can be a number or a function that returns a number.
    * Defaults to 0ms
    */
-  wait: number
+  wait: number | ((debouncer: Debouncer<TFn>) => number)
 }
 
 const defaultOptions: Required<DebouncerOptions<any>> = {
@@ -99,6 +102,20 @@ export class Debouncer<TFn extends AnyFunction> {
     return this._options
   }
 
+  /**
+   * Returns the current enabled state of the debouncer
+   */
+  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 debounced function
    * If a call is already in progress, it will be queued
@@ -127,11 +144,11 @@ export class Debouncer<TFn extends AnyFunction> {
       if (this._options.trailing && !_didLeadingExecute) {
         this.executeFunction(...args)
       }
-    }, this._options.wait)
+    }, this.getWait())
   }
 
   private executeFunction(...args: Parameters<TFn>): void {
-    if (!this._options.enabled) return undefined
+    if (!this.getEnabled()) return undefined
     this.fn(...args) // EXECUTE!
     this._isPending = false
     this._executionCount++
@@ -160,7 +177,7 @@ export class Debouncer<TFn extends AnyFunction> {
    * Returns `true` if debouncing
    */
   getIsPending(): boolean {
-    return this._options.enabled && this._isPending
+    return this.getEnabled() && this._isPending
   }
 }
 
@@ -186,7 +203,7 @@ export class Debouncer<TFn extends AnyFunction> {
  */
 export function debounce<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<DebouncerOptions<TFn>, 'enabled'>,
+  initialOptions: DebouncerOptions<TFn>,
 ): (...args: Parameters<TFn>) => void {
   const debouncer = new Debouncer(fn, initialOptions)
   return debouncer.maybeExecute.bind(debouncer)

package/src/queuer.ts

@@ -1,3 +1,5 @@
+import { parseFunctionOrValue } from './utils'
+
 /**
  * Options for configuring a Queuer instance
  */
@@ -60,9 +62,11 @@ export interface QueuerOptions<TValue> {
    */
   started?: boolean
   /**
-   * Time in milliseconds to wait between processing items
+   * Time in milliseconds to wait between processing items.
+   * Can be a number or a function that returns a number.
+   * @default 0
    */
-  wait?: number
+  wait?: number | ((queuer: Queuer<TValue>) => number)
 }
 
 const defaultOptions: Required<QueuerOptions<any>> = {
@@ -78,7 +82,7 @@ const defaultOptions: Required<QueuerOptions<any>> = {
   onItemsChange: () => {},
   onReject: () => {},
   onExpire: () => {},
-  started: false,
+  started: true,
   wait: 0,
 }
 
@@ -178,6 +182,13 @@ export class Queuer<TValue> {
     return this._options
   }
 
+  /**
+   * Returns the current wait time in milliseconds
+   */
+  getWait(): number {
+    return parseFunctionOrValue(this._options.wait, this)
+  }
+
   /**
    * Processes items in the queuer
    */
@@ -197,9 +208,10 @@ export class Queuer<TValue> {
       }
       this._onItemsChanges.forEach((cb) => cb(nextItem))
 
-      if (this._options.wait > 0) {
+      const wait = this.getWait()
+      if (wait > 0) {
         // Use setTimeout to wait before processing next item
-        setTimeout(() => this.tick(), this._options.wait)
+        setTimeout(() => this.tick(), wait)
         return
       }
 
@@ -493,7 +505,7 @@ export class Queuer<TValue> {
  * processPriority(3) // Processed before 1
  * ```
  */
-export function queue<TValue>(options: QueuerOptions<TValue> = {}) {
-  const queuer = new Queuer<TValue>({ ...options, started: true })
+export function queue<TValue>(options: QueuerOptions<TValue>) {
+  const queuer = new Queuer<TValue>(options)
   return queuer.addItem.bind(queuer)
 }

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,17 @@ 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
+   * - 'sliding': Uses a sliding window that allows executions as old ones expire
+   * Defaults to 'fixed'
+   */
+  windowType?: 'fixed' | 'sliding'
 }
 
 const defaultOptions: Required<RateLimiterOptions<any>> = {
@@ -33,6 +43,7 @@ const defaultOptions: Required<RateLimiterOptions<any>> = {
   onExecute: () => {},
   onReject: () => {},
   window: 0,
+  windowType: 'fixed',
 }
 
 /**
@@ -42,6 +53,12 @@ const defaultOptions: Required<RateLimiterOptions<any>> = {
  * then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
  * all executions happen immediately, followed by a complete block.
  *
+ * The rate limiter supports two types of windows:
+ * - 'fixed': A strict window that resets after the window period. All executions within the window count
+ *   towards the limit, and the window resets completely after the period.
+ * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
+ *   consistent rate of execution over time.
+ *
  * For smoother execution patterns, consider using:
  * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
  * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
@@ -53,7 +70,7 @@ const defaultOptions: Required<RateLimiterOptions<any>> = {
  * ```ts
  * const rateLimiter = new RateLimiter(
  *   (id: string) => api.getData(id),
- *   { limit: 5, window: 1000 } // 5 calls per second
+ *   { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
  * );
  *
  * // Will execute immediately until limit reached, then block
@@ -91,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.
@@ -109,18 +147,30 @@ export class RateLimiter<TFn extends AnyFunction> {
   maybeExecute(...args: Parameters<TFn>): boolean {
     this.cleanupOldExecutions()
 
-    if (this._executionTimes.length < this._options.limit) {
-      this.executeFunction(...args)
-      return true
+    if (this._options.windowType === 'sliding') {
+      // For sliding window, we can execute if we have capacity in the current window
+      if (this._executionTimes.length < this.getLimit()) {
+        this.executeFunction(...args)
+        return true
+      }
+    } else {
+      // 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.getWindow() <= now
+
+      if (isNewWindow || this._executionTimes.length < this.getLimit()) {
+        this.executeFunction(...args)
+        return true
+      }
     }
 
     this.rejectFunction()
-
     return false
   }
 
   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)
@@ -137,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,
     )
@@ -162,15 +212,18 @@ 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)
   }
 
   /**
    * Returns the number of milliseconds until the next execution will be possible
    */
   getMsUntilNextWindow(): number {
+    if (this.getRemainingInWindow() > 0) {
+      return 0
+    }
     const oldestExecution = Math.min(...this._executionTimes)
-    return oldestExecution + this._options.window - Date.now()
+    return oldestExecution + this.getWindow() - Date.now()
   }
 
   /**
@@ -191,15 +244,22 @@ export class RateLimiter<TFn extends AnyFunction> {
  * - A throttler ensures even spacing between executions, which can be better for consistent performance
  * - A debouncer collapses multiple calls into one, which is better for handling bursts of events
  *
+ * The rate limiter supports two types of windows:
+ * - 'fixed': A strict window that resets after the window period. All executions within the window count
+ *   towards the limit, and the window resets completely after the period.
+ * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
+ *   consistent rate of execution over time.
+ *
  * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically
  * need to enforce a hard limit on the number of executions within a time period.
  *
  * @example
  * ```ts
- * // Rate limit to 5 calls per minute
+ * // Rate limit to 5 calls per minute with a sliding window
  * const rateLimited = rateLimit(makeApiCall, {
  *   limit: 5,
  *   window: 60000,
+ *   windowType: 'sliding',
  *   onReject: (rateLimiter) => {
  *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }
@@ -215,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,
+  )
 }