@tanstack/pacer 0.2.0 → 0.4.0

package/src/async-queuer.ts

@@ -10,6 +10,16 @@ export interface AsyncQueuerOptions<TValue> {
    * Maximum number of concurrent tasks to process
    */
   concurrency?: number
+  /**
+   * 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: () => Promise<TValue>, addedAt: number) => boolean
   /**
    * Default position to get items from during processing
    * @default 'front'
@@ -49,7 +59,11 @@ export interface AsyncQueuerOptions<TValue> {
    */
   onReject?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void
   /**
-   * Whether the queuer should start processing tasks immediately
+   * Callback fired whenever an item expires in the queuer
+   */
+  onExpire?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void
+  /**
+   * Whether the queuer should start processing tasks immediately or not.
    */
   started?: boolean
   /**
@@ -61,6 +75,8 @@ export interface AsyncQueuerOptions<TValue> {
 const defaultOptions: Required<AsyncQueuerOptions<any>> = {
   addItemsTo: 'back',
   concurrency: 1,
+  expirationDuration: Infinity,
+  getIsExpired: () => false,
   getItemsFrom: 'front',
   getPriority: (item) => (item as any)?.priority ?? 0,
   initialItems: [],
@@ -69,7 +85,8 @@ const defaultOptions: Required<AsyncQueuerOptions<any>> = {
   onIsRunningChange: () => {},
   onItemsChange: () => {},
   onReject: () => {},
-  started: false,
+  onExpire: () => {},
+  started: true,
   wait: 0,
 }
 
@@ -83,6 +100,7 @@ const defaultOptions: Required<AsyncQueuerOptions<any>> = {
  * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
  * - Pause/resume task processing
  * - Task cancellation
+ * - Item expiration to clear stale items from the queue
  *
  * Tasks are processed concurrently up to the configured concurrency limit. When a task completes,
  * the next pending task is processed if below the concurrency limit.
@@ -107,7 +125,9 @@ export class AsyncQueuer<TValue> {
   private _activeItems: Set<() => Promise<TValue>> = new Set()
   private _executionCount = 0
   private _rejectionCount = 0
+  private _expirationCount = 0
   private _items: Array<() => Promise<TValue>> = []
+  private _itemTimestamps: Array<number> = []
   private _onErrorCallbacks: Array<(error: Error) => void> = []
   private _onSettledCallbacks: Array<(result: TValue | Error) => void> = []
   private _onSuccessCallbacks: Array<(result: TValue) => void> = []
@@ -129,11 +149,8 @@ export class AsyncQueuer<TValue> {
    * Updates the queuer options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<AsyncQueuerOptions<TValue>>,
-  ): AsyncQueuerOptions<TValue> {
+  setOptions(newOptions: Partial<AsyncQueuerOptions<TValue>>): void {
     this._options = { ...this._options, ...newOptions }
-    return this._options
   }
 
   /**
@@ -152,6 +169,9 @@ export class AsyncQueuer<TValue> {
       return
     }
 
+    // Check for expired items
+    this.checkExpiredItems()
+
     while (
       this._activeItems.size < this._options.concurrency &&
       !this.getIsEmpty()
@@ -196,6 +216,56 @@ export class AsyncQueuer<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)
+    }
+  }
+
   /**
    * Starts the queuer and processes items
    */
@@ -295,15 +365,19 @@ export class AsyncQueuer<TValue> {
 
         if (insertIndex === -1) {
           this._items.push(task)
+          this._itemTimestamps.push(Date.now())
         } else {
           this._items.splice(insertIndex, 0, task)
+          this._itemTimestamps.splice(insertIndex, 0, Date.now())
         }
       } else {
         // Default FIFO/LIFO behavior
         if (position === 'front') {
           this._items.unshift(task)
+          this._itemTimestamps.unshift(Date.now())
         } else {
           this._items.push(task)
+          this._itemTimestamps.push(Date.now())
         }
       }
 
@@ -328,8 +402,10 @@ export class AsyncQueuer<TValue> {
 
     if (position === 'front') {
       item = this._items.shift()
+      this._itemTimestamps.shift()
     } else {
       item = this._items.pop()
+      this._itemTimestamps.pop()
     }
 
     if (item !== undefined) {
@@ -455,6 +531,13 @@ export class AsyncQueuer<TValue> {
       )
     }
   }
+
+  /**
+   * Returns the number of items that have expired from the queuer
+   */
+  getExpirationCount(): number {
+    return this._expirationCount
+  }
 }
 
 /**
@@ -474,7 +557,9 @@ export class AsyncQueuer<TValue> {
  * @param options - Configuration options for the AsyncQueuer
  * @returns A bound addItem function that can be used to add tasks to the queuer
  */
-export function asyncQueue<TValue>(options: AsyncQueuerOptions<TValue> = {}) {
-  const queuer = new AsyncQueuer<TValue>({ ...options, started: true })
+export function asyncQueue<TValue>(
+  options: Omit<AsyncQueuerOptions<TValue>, 'started'> = {},
+) {
+  const queuer = new AsyncQueuer<TValue>(options)
   return queuer.addItem.bind(queuer)
 }

package/src/async-rate-limiter.ts

@@ -3,10 +3,7 @@ import type { AnyAsyncFunction } from './types'
 /**
  * Options for configuring an async rate-limited function
  */
-export interface AsyncRateLimiterOptions<
-  TFn extends AnyAsyncFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
   /**
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -19,28 +16,44 @@ export interface AsyncRateLimiterOptions<
   /**
    * Optional error handler for when the rate-limited function throws
    */
-  onError?: (error: unknown) => void
+  onError?: (error: unknown, rateLimiter: AsyncRateLimiter<TFn>) => void
+  /**
+   * Optional callback function that is called when an execution is rejected due to rate limiting
+   */
+  onReject?: (rateLimiter: AsyncRateLimiter<TFn>) => void
   /**
    * Optional function to call when the rate-limited function is executed
    */
-  onExecute?: (rateLimiter: AsyncRateLimiter<TFn, TArgs>) => void
+  onSettled?: (rateLimiter: AsyncRateLimiter<TFn>) => void
   /**
-   * Optional callback function that is called when an execution is rejected due to rate limiting
+   * Optional function to call when the rate-limited function is executed
    */
-  onReject?: (rateLimiter: AsyncRateLimiter<TFn, TArgs>) => void
+  onSuccess?: (
+    result: ReturnType<TFn>,
+    rateLimiter: AsyncRateLimiter<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<
-  Omit<AsyncRateLimiterOptions<any, any>, 'limit' | 'window'>
+  Omit<AsyncRateLimiterOptions<any>, 'limit' | 'window'>
 > = {
   enabled: true,
-  onReject: () => {},
   onError: () => {},
-  onExecute: () => {},
+  onReject: () => {},
+  onSettled: () => {},
+  onSuccess: () => {},
+  windowType: 'fixed',
 }
 
 /**
@@ -50,6 +63,16 @@ const defaultOptions: Required<
  * 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.
+ *
+ * Unlike the non-async RateLimiter, this async version supports returning values from the rate-limited function,
+ * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+ * instead of setting the result on a state variable from within the rate-limited function.
+ *
  * 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)
@@ -61,25 +84,27 @@ const defaultOptions: Required<
  * ```ts
  * const rateLimiter = new AsyncRateLimiter(
  *   async (id: string) => await 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
- * await rateLimiter.maybeExecute('123');
+ * // Returns the API response directly
+ * const data = await rateLimiter.maybeExecute('123');
  * ```
  */
-export class AsyncRateLimiter<
-  TFn extends AnyAsyncFunction,
-  TArgs extends Parameters<TFn>,
-> {
-  private _executionCount = 0
+export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
+  private _options: AsyncRateLimiterOptions<TFn>
+  private _errorCount = 0
   private _executionTimes: Array<number> = []
-  private _options: AsyncRateLimiterOptions<TFn, TArgs>
+  private _lastResult: ReturnType<TFn> | undefined
   private _rejectionCount = 0
+  private _settleCount = 0
+  private _successCount = 0
+  private _isExecuting = false
 
   constructor(
     private fn: TFn,
-    initialOptions: AsyncRateLimiterOptions<TFn, TArgs>,
+    initialOptions: AsyncRateLimiterOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -91,21 +116,15 @@ export class AsyncRateLimiter<
    * Updates the rate limiter options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<AsyncRateLimiterOptions<TFn, TArgs>>,
-  ): AsyncRateLimiterOptions<TFn, TArgs> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
-    }
-    return this._options
+  setOptions(newOptions: Partial<AsyncRateLimiterOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
   }
 
   /**
    * Returns the current rate limiter options
    */
-  getOptions(): Required<AsyncRateLimiterOptions<TFn, TArgs>> {
-    return this._options as Required<AsyncRateLimiterOptions<TFn, TArgs>>
+  getOptions(): Required<AsyncRateLimiterOptions<TFn>> {
+    return this._options as Required<AsyncRateLimiterOptions<TFn>>
   }
 
   /**
@@ -124,38 +143,55 @@ export class AsyncRateLimiter<
    * await rateLimiter.maybeExecute('arg1', 'arg2'); // Rejected
    * ```
    */
-  async maybeExecute(...args: TArgs): Promise<boolean> {
+  async maybeExecute(
+    ...args: Parameters<TFn>
+  ): Promise<ReturnType<TFn> | undefined> {
     this.cleanupOldExecutions()
 
-    if (this._executionTimes.length < this._options.limit) {
-      await 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) {
+        await this.executeFunction(...args)
+        return this._lastResult
+      }
+    } 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) {
+        await this.executeFunction(...args)
+        return this._lastResult
+      }
     }
 
     this.rejectFunction()
-    return false
+    return undefined
   }
 
-  private async executeFunction(...args: TArgs): Promise<void> {
+  private async executeFunction(
+    ...args: Parameters<TFn>
+  ): Promise<ReturnType<TFn> | undefined> {
     if (!this._options.enabled) return
+    this._isExecuting = true
     const now = Date.now()
-    this._executionCount++
     this._executionTimes.push(now)
 
     try {
-      await this.fn(...args)
+      this._lastResult = await this.fn(...args)
+      this._successCount++
+      this._options.onSuccess?.(this._lastResult!, this)
     } catch (error) {
-      if (this._options.onError) {
-        try {
-          this._options.onError(error)
-        } catch (error) {
-          console.error('Error in onError handler', error)
-        }
-      }
-      throw error
+      this._errorCount++
+      this._options.onError?.(error, this)
     } finally {
-      this._options.onExecute?.(this)
+      this._isExecuting = false
+      this._settleCount++
+      this._options.onSettled?.(this)
     }
+
+    return this._lastResult
   }
 
   private rejectFunction(): void {
@@ -173,33 +209,60 @@ export class AsyncRateLimiter<
     )
   }
 
+  /**
+   * 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
+   * For fixed windows, this is the time until the current window resets
+   * For sliding windows, this is the time until the oldest execution expires
+   */
+  getMsUntilNextWindow(): number {
+    if (this.getRemainingInWindow() > 0) {
+      return 0
+    }
+    const oldestExecution = Math.min(...this._executionTimes)
+    return oldestExecution + this._options.window - Date.now()
+  }
+
   /**
    * Returns the number of times the function has been executed
    */
-  getExecutionCount(): number {
-    return this._executionCount
+  getSuccessCount(): number {
+    return this._successCount
   }
 
   /**
-   * Returns the number of times the function has been rejected
+   * Returns the number of times the function has been settled
    */
-  getRejectionCount(): number {
-    return this._rejectionCount
+  getSettleCount(): number {
+    return this._settleCount
   }
 
   /**
-   * Returns the number of remaining executions allowed in the current window
+   * Returns the number of times the function has errored
    */
-  getRemainingInWindow(): number {
-    this.cleanupOldExecutions()
-    return Math.max(0, this._options.limit - this._executionTimes.length)
+  getErrorCount(): number {
+    return this._errorCount
   }
 
   /**
-   * Returns the number of milliseconds until the next execution will be possible
+   * Returns the number of times the function has been rejected
    */
-  getMsUntilNextWindow(): number {
-    return this.getRemainingInWindow() * this._options.window
+  getRejectionCount(): number {
+    return this._rejectionCount
+  }
+
+  /**
+   * Returns whether the function is currently executing
+   */
+  getIsExecuting(): boolean {
+    return this._isExecuting
   }
 
   /**
@@ -207,14 +270,26 @@ export class AsyncRateLimiter<
    */
   reset(): void {
     this._executionTimes = []
-    this._executionCount = 0
+    this._successCount = 0
+    this._errorCount = 0
     this._rejectionCount = 0
+    this._settleCount = 0
   }
 }
 
 /**
  * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.
  *
+ * Unlike the non-async rate limiter, this async version supports returning values from the rate-limited function,
+ * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+ * instead of setting the result on a state variable from within the rate-limited function.
+ *
+ * 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.
+ *
  * Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:
  * - A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets
  * - A throttler ensures even spacing between executions, which can be better for consistent performance
@@ -225,10 +300,11 @@ export class AsyncRateLimiter<
  *
  * @example
  * ```ts
- * // Rate limit to 5 calls per minute
+ * // Rate limit to 5 calls per minute with a sliding window
  * const rateLimited = asyncRateLimit(makeApiCall, {
  *   limit: 5,
  *   window: 60000,
+ *   windowType: 'sliding',
  *   onReject: (rateLimiter) => {
  *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }
@@ -236,18 +312,16 @@ export class AsyncRateLimiter<
  *
  * // First 5 calls will execute immediately
  * // Additional calls will be rejected until the minute window resets
- * await rateLimited();
+ * // Returns the API response directly
+ * const result = await rateLimited();
  *
  * // For more even execution, consider using throttle instead:
  * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
  * ```
  */
-export function asyncRateLimit<
-  TFn extends AnyAsyncFunction,
-  TArgs extends Parameters<TFn>,
->(
+export function asyncRateLimit<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  initialOptions: Omit<AsyncRateLimiterOptions<TFn, TArgs>, 'enabled'>,
+  initialOptions: Omit<AsyncRateLimiterOptions<TFn>, 'enabled'>,
 ) {
   const rateLimiter = new AsyncRateLimiter(fn, initialOptions)
   return rateLimiter.maybeExecute.bind(rateLimiter)