@tanstack/pacer 0.2.0 → 0.4.0

package/src/queuer.ts

@@ -7,6 +7,16 @@ export interface QueuerOptions<TValue> {
    * @default 'back'
    */
   addItemsTo?: QueuePosition
+  /**
+   * Maximum time in milliseconds that an item can stay in the queue
+   * If not provided, items will never expire
+   */
+  expirationDuration?: number
+  /**
+   * Function to determine if an item has expired
+   * If provided, this overrides the expirationDuration behavior
+   */
+  getIsExpired?: (item: TValue, addedAt: number) => boolean
   /**
    * Default position to get items from during processing
    * @default 'front'
@@ -25,6 +35,10 @@ export interface QueuerOptions<TValue> {
    * Maximum number of items allowed in the queuer
    */
   maxSize?: number
+  /**
+   * Callback fired whenever an item expires in the queuer
+   */
+  onExpire?: (item: TValue, queuer: Queuer<TValue>) => void
   /**
    * Callback fired whenever an item is removed from the queuer
    */
@@ -55,12 +69,15 @@ const defaultOptions: Required<QueuerOptions<any>> = {
   addItemsTo: 'back',
   getItemsFrom: 'front',
   getPriority: (item) => item?.priority ?? 0,
+  getIsExpired: () => false,
+  expirationDuration: Infinity,
   initialItems: [],
   maxSize: Infinity,
   onGetNextItem: () => {},
   onIsRunningChange: () => {},
   onItemsChange: () => {},
   onReject: () => {},
+  onExpire: () => {},
   started: false,
   wait: 0,
 }
@@ -99,6 +116,11 @@ export type QueuePosition = 'front' | 'back'
  * - wait: configurable delay between processing items
  * - onItemsChange/onGetNextItem: callbacks for monitoring queuer state
  *
+ * Supports item expiration to clear stale items from the queuer
+ * - expirationDuration: maximum time in milliseconds that an item can stay in the queue
+ * - getIsExpired: function to override default expiration behavior
+ * - onExpire: callback for when an item expires
+ *
  * @example
  * ```ts
  * // FIFO queuer
@@ -122,8 +144,10 @@ export type QueuePosition = 'front' | 'back'
 export class Queuer<TValue> {
   private _options: Required<QueuerOptions<TValue>>
   private _items: Array<TValue> = []
+  private _itemTimestamps: Array<number> = []
   private _executionCount = 0
   private _rejectionCount = 0
+  private _expirationCount = 0
   private _onItemsChanges: Array<(item: TValue) => void> = []
   private _running: boolean
   private _pendingTick = false
@@ -143,11 +167,8 @@ export class Queuer<TValue> {
    * Updates the queuer options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<QueuerOptions<TValue>>,
-  ): QueuerOptions<TValue> {
+  setOptions(newOptions: Partial<QueuerOptions<TValue>>): void {
     this._options = { ...this._options, ...newOptions }
-    return this._options
   }
 
   /**
@@ -165,6 +186,10 @@ export class Queuer<TValue> {
       this._pendingTick = false
       return
     }
+
+    // Check for expired items
+    this.checkExpiredItems()
+
     while (!this.getIsEmpty()) {
       const nextItem = this.getNextItem(this._options.getItemsFrom)
       if (nextItem === undefined) {
@@ -183,6 +208,56 @@ export class Queuer<TValue> {
     this._pendingTick = false
   }
 
+  /**
+   * Checks for and removes expired items from the queuer
+   */
+  private checkExpiredItems() {
+    if (
+      this._options.expirationDuration === Infinity &&
+      this._options.getIsExpired === defaultOptions.getIsExpired
+    )
+      return
+
+    const now = Date.now()
+    const expiredIndices: Array<number> = []
+
+    // Find indices of expired items
+    for (let i = 0; i < this._items.length; i++) {
+      const timestamp = this._itemTimestamps[i]
+      if (timestamp === undefined) continue
+
+      const item = this._items[i]
+      if (item === undefined) continue
+
+      const isExpired =
+        this._options.getIsExpired !== defaultOptions.getIsExpired
+          ? this._options.getIsExpired(item, timestamp)
+          : now - timestamp > this._options.expirationDuration
+
+      if (isExpired) {
+        expiredIndices.push(i)
+      }
+    }
+
+    // Remove expired items from back to front to maintain indices
+    for (let i = expiredIndices.length - 1; i >= 0; i--) {
+      const index = expiredIndices[i]
+      if (index === undefined) continue
+
+      const expiredItem = this._items[index]
+      if (expiredItem === undefined) continue
+
+      this._items.splice(index, 1)
+      this._itemTimestamps.splice(index, 1)
+      this._expirationCount++
+      this._options.onExpire(expiredItem, this)
+    }
+
+    if (expiredIndices.length > 0) {
+      this._options.onItemsChange(this)
+    }
+  }
+
   /**
    * Stops the queuer from processing items
    */
@@ -248,15 +323,19 @@ export class Queuer<TValue> {
 
       if (insertIndex === -1) {
         this._items.push(item)
+        this._itemTimestamps.push(Date.now())
       } else {
         this._items.splice(insertIndex, 0, item)
+        this._itemTimestamps.splice(insertIndex, 0, Date.now())
       }
     } else {
       // Default FIFO/LIFO behavior
       if (position === 'front') {
         this._items.unshift(item)
+        this._itemTimestamps.unshift(Date.now())
       } else {
         this._items.push(item)
+        this._itemTimestamps.push(Date.now())
       }
     }
 
@@ -288,8 +367,10 @@ export class Queuer<TValue> {
 
     if (position === 'front') {
       item = this._items.shift()
+      this._itemTimestamps.shift()
     } else {
       item = this._items.pop()
+      this._itemTimestamps.pop()
     }
 
     if (item !== undefined) {
@@ -362,6 +443,13 @@ export class Queuer<TValue> {
     return this._rejectionCount
   }
 
+  /**
+   * Returns the number of items that have expired from the queuer
+   */
+  getExpirationCount(): number {
+    return this._expirationCount
+  }
+
   /**
    * Returns true if the queuer is running
    */

package/src/rate-limiter.ts

@@ -3,10 +3,7 @@ import type { AnyFunction } from './types'
 /**
  * Options for configuring a rate-limited function
  */
-export interface RateLimiterOptions<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface RateLimiterOptions<TFn extends AnyFunction> {
   /**
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -19,23 +16,31 @@ export interface RateLimiterOptions<
   /**
    * Callback function that is called after the function is executed
    */
-  onExecute?: (rateLimiter: RateLimiter<TFn, TArgs>) => void
+  onExecute?: (rateLimiter: RateLimiter<TFn>) => void
   /**
    * Optional callback function that is called when an execution is rejected due to rate limiting
    */
-  onReject?: (rateLimiter: RateLimiter<TFn, TArgs>) => void
+  onReject?: (rateLimiter: RateLimiter<TFn>) => void
   /**
    * Time window in milliseconds within which the limit applies
    */
   window: 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, any>> = {
+const defaultOptions: Required<RateLimiterOptions<any>> = {
   enabled: true,
   limit: 1,
   onExecute: () => {},
   onReject: () => {},
   window: 0,
+  windowType: 'fixed',
 }
 
 /**
@@ -45,6 +50,12 @@ const defaultOptions: Required<RateLimiterOptions<any, 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)
@@ -56,25 +67,22 @@ const defaultOptions: Required<RateLimiterOptions<any, 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
  * rateLimiter.maybeExecute('123');
  * ```
  */
-export class RateLimiter<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export class RateLimiter<TFn extends AnyFunction> {
   private _executionCount = 0
   private _rejectionCount = 0
   private _executionTimes: Array<number> = []
-  private _options: RateLimiterOptions<TFn, TArgs>
+  private _options: RateLimiterOptions<TFn>
 
   constructor(
     private fn: TFn,
-    initialOptions: RateLimiterOptions<TFn, TArgs>,
+    initialOptions: RateLimiterOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -86,21 +94,15 @@ export class RateLimiter<
    * Updates the rate limiter options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<RateLimiterOptions<TFn, TArgs>>,
-  ): RateLimiterOptions<TFn, TArgs> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
-    }
-    return this._options
+  setOptions(newOptions: Partial<RateLimiterOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
   }
 
   /**
    * Returns the current rate limiter options
    */
-  getOptions(): Required<RateLimiterOptions<TFn, TArgs>> {
-    return this._options as Required<RateLimiterOptions<TFn, TArgs>>
+  getOptions(): Required<RateLimiterOptions<TFn>> {
+    return this._options as Required<RateLimiterOptions<TFn>>
   }
 
   /**
@@ -118,20 +120,32 @@ 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) {
-      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._options.limit) {
+        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._options.window <= now
+
+      if (isNewWindow || this._executionTimes.length < this._options.limit) {
+        this.executeFunction(...args)
+        return true
+      }
     }
 
     this.rejectFunction()
-
     return false
   }
 
-  private executeFunction(...args: TArgs): void {
+  private executeFunction(...args: Parameters<TFn>): void {
     if (!this._options.enabled) return
     const now = Date.now()
     this._executionCount++
@@ -181,6 +195,9 @@ export class RateLimiter<
    * 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()
   }
@@ -203,15 +220,22 @@ export class RateLimiter<
  * - 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`);
  *   }
@@ -227,7 +251,7 @@ export class RateLimiter<
  */
 export function rateLimit<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<RateLimiterOptions<TFn, Parameters<TFn>>, 'enabled'>,
+  initialOptions: Omit<RateLimiterOptions<TFn>, 'enabled'>,
 ) {
   const rateLimiter = new RateLimiter(fn, initialOptions)
   return rateLimiter.maybeExecute.bind(rateLimiter)

package/src/throttler.ts

@@ -3,10 +3,7 @@ import type { AnyFunction } from './types'
 /**
  * Options for configuring a throttled function
  */
-export interface ThrottlerOptions<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface ThrottlerOptions<TFn extends AnyFunction> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -20,7 +17,7 @@ export interface ThrottlerOptions<
   /**
    * Callback function that is called after the function is executed
    */
-  onExecute?: (throttler: Throttler<TFn, TArgs>) => void
+  onExecute?: (throttler: Throttler<TFn>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -32,12 +29,12 @@ export interface ThrottlerOptions<
   wait: number
 }
 
-const defaultOptions: Required<ThrottlerOptions<any, any>> = {
+const defaultOptions: Required<ThrottlerOptions<any>> = {
   enabled: true,
   leading: true,
+  onExecute: () => {},
   trailing: true,
   wait: 0,
-  onExecute: () => {},
 }
 
 /**
@@ -67,17 +64,16 @@ const defaultOptions: Required<ThrottlerOptions<any, any>> = {
  * throttler.maybeExecute('123'); // Throttled
  * ```
  */
-export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
+export class Throttler<TFn extends AnyFunction> {
   private _executionCount = 0
-  private _lastArgs: TArgs | undefined
+  private _lastArgs: Parameters<TFn> | undefined
   private _lastExecutionTime = 0
-  private _options: Required<ThrottlerOptions<TFn, TArgs>>
+  private _options: Required<ThrottlerOptions<TFn>>
   private _timeoutId: NodeJS.Timeout | undefined
-  private _isPending = false
 
   constructor(
     private fn: TFn,
-    initialOptions: ThrottlerOptions<TFn, TArgs>,
+    initialOptions: ThrottlerOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -89,20 +85,19 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * Updates the throttler options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<ThrottlerOptions<TFn, TArgs>>,
-  ): Required<ThrottlerOptions<TFn, TArgs>> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
+  setOptions(newOptions: Partial<ThrottlerOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
+
+    // End the pending state if the debouncer is disabled
+    if (!this._options.enabled) {
+      this.cancel()
     }
-    return this._options
   }
 
   /**
    * Returns the current throttler options
    */
-  getOptions(): Required<ThrottlerOptions<TFn, TArgs>> {
+  getOptions(): Required<ThrottlerOptions<TFn>> {
     return this._options
   }
 
@@ -128,42 +123,40 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * throttled.maybeExecute('c', 'd');
    * ```
    */
-  maybeExecute(...args: TArgs): void {
+  maybeExecute(...args: Parameters<TFn>): void {
     const now = Date.now()
     const timeSinceLastExecution = now - this._lastExecutionTime
 
     // Handle leading execution
-    if (timeSinceLastExecution >= this._options.wait) {
-      if (this._options.leading) {
-        this.executeFunction(...args)
-      }
-      this._lastExecutionTime = now
-      this._isPending = false
+    if (this._options.leading && timeSinceLastExecution >= this._options.wait) {
+      this.executeFunction(...args)
     } else {
       // Store the most recent arguments for potential trailing execution
       this._lastArgs = args
 
       // Set up trailing execution if not already scheduled
       if (!this._timeoutId && this._options.trailing) {
-        this._isPending = true
+        const _timeSinceLastExecution = this._lastExecutionTime
+          ? now - this._lastExecutionTime
+          : 0
+        const timeoutDuration = this._options.wait - _timeSinceLastExecution
         this._timeoutId = setTimeout(() => {
-          if (this._lastArgs) {
+          if (this._lastArgs !== undefined) {
             this.executeFunction(...this._lastArgs)
-            this._lastArgs = undefined
           }
-          this._lastExecutionTime = Date.now()
-          this._timeoutId = undefined
-          this._isPending = false
-          this._options.onExecute(this)
-        }, this._options.wait - timeSinceLastExecution)
+        }, timeoutDuration)
       }
     }
   }
 
-  private executeFunction(...args: TArgs): void {
+  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)
   }
 
   /**
@@ -180,36 +173,35 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
       clearTimeout(this._timeoutId)
       this._timeoutId = undefined
       this._lastArgs = undefined
-      this._isPending = false
     }
   }
 
   /**
-   * Returns the number of times the function has been executed
+   * Returns the last execution time
    */
-  getExecutionCount(): number {
-    return this._executionCount
+  getLastExecutionTime(): number {
+    return this._lastExecutionTime
   }
 
   /**
-   * Returns `true` if there is a pending execution
+   * Returns the next execution time
    */
-  getIsPending(): boolean {
-    return this._options.enabled && this._isPending
+  getNextExecutionTime(): number {
+    return this._lastExecutionTime + this._options.wait
   }
 
   /**
-   * Returns the last execution time
+   * Returns the number of times the function has been executed
    */
-  getLastExecutionTime(): number {
-    return this._lastExecutionTime
+  getExecutionCount(): number {
+    return this._executionCount
   }
 
   /**
-   * Returns the next execution time
+   * Returns `true` if there is a pending execution
    */
-  getNextExecutionTime(): number {
-    return this._lastExecutionTime + this._options.wait
+  getIsPending(): boolean {
+    return this._options.enabled && !!this._timeoutId
   }
 }
 
@@ -239,10 +231,10 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
  * });
  * ```
  */
-export function throttle<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
->(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn, TArgs>, 'enabled'>) {
+export function throttle<TFn extends AnyFunction>(
+  fn: TFn,
+  initialOptions: Omit<ThrottlerOptions<TFn>, 'enabled'>,
+) {
   const throttler = new Throttler(fn, initialOptions)
   return throttler.maybeExecute.bind(throttler)
 }

package/src/types.ts

@@ -1,17 +1,9 @@
 /**
  * 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
+export type AnyFunction = (...args: Array<any>) => 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>
+export type AnyAsyncFunction = (...args: Array<any>) => Promise<any>

package/src/utils.ts

@@ -1,6 +1,6 @@
 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) => {