@tanstack/pacer 0.9.1 → 0.10.0

package/src/async-debouncer.ts

@@ -176,6 +176,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   #resolvePreviousPromise:
     | ((value?: ReturnType<TFn> | undefined) => void)
     | null = null
+  #rejectPreviousPromise: ((reason?: unknown) => void) | null = null
 
   constructor(
     private fn: TFn,
@@ -270,8 +271,9 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
       this.#setState({ isPending: true })
     }
 
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       this.#resolvePreviousPromise = resolve
+      this.#rejectPreviousPromise = reject
       this.#timeoutId = setTimeout(async () => {
         // Execute trailing if enabled
         if (this.options.trailing && this.store.state.lastArgs) {
@@ -305,7 +307,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
       })
       this.options.onError?.(error, this)
       if (this.options.throwOnError) {
-        throw error
+        this.#rejectPreviousPromiseInternal(error)
       }
     } finally {
       this.#setState({
@@ -322,11 +324,31 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   /**
    * Processes the current pending execution immediately
    */
-  flush = (): void => {
+  flush = async (): Promise<ReturnType<TFn> | undefined> => {
     if (this.store.state.isPending && this.store.state.lastArgs) {
       this.#abortExecution() // abort any current execution
       this.#clearTimeout() // clear any existing timeout
-      this.#execute(...this.store.state.lastArgs)
+      const result = await this.#execute(...this.store.state.lastArgs)
+
+      // Resolve any pending promise from maybeExecute
+      this.#resolvePreviousPromiseInternal()
+
+      return result
+    }
+    return undefined
+  }
+
+  #resolvePreviousPromiseInternal = (): void => {
+    if (this.#resolvePreviousPromise) {
+      this.#resolvePreviousPromise(this.store.state.lastResult)
+      this.#resolvePreviousPromise = null
+    }
+  }
+
+  #rejectPreviousPromiseInternal = (error: unknown): void => {
+    if (this.#rejectPreviousPromise) {
+      this.#rejectPreviousPromise(error)
+      this.#rejectPreviousPromise = null
     }
   }
 
@@ -339,10 +361,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
 
   #cancelPendingExecution = (): void => {
     this.#clearTimeout()
-    if (this.#resolvePreviousPromise) {
-      this.#resolvePreviousPromise(this.store.state.lastResult)
-      this.#resolvePreviousPromise = null
-    }
+    this.#resolvePreviousPromiseInternal()
     this.#setState({
       isPending: false,
       isExecuting: false,

package/src/async-queuer.ts

@@ -32,14 +32,14 @@ export interface AsyncQueuerState<TValue> {
    * Whether the queuer is active and will process items automatically
    */
   isRunning: boolean
-  /**
-   * Timestamps when items were added to the queue for expiration tracking
-   */
-  itemTimestamps: Array<number>
   /**
    * Array of items currently waiting to be processed
    */
   items: Array<TValue>
+  /**
+   * Timestamps when items were added to the queue for expiration tracking
+   */
+  itemTimestamps: Array<number>
   /**
    * The result from the most recent task execution
    */
@@ -507,6 +507,12 @@ export class AsyncQueuer<TValue> {
     return item
   }
 
+  #getAllItems = (): Array<TValue> => {
+    const items = this.peekAllItems()
+    this.clear()
+    return items
+  }
+
   /**
    * Removes and returns the next item from the queue and executes the task function with it.
    *
@@ -552,14 +558,26 @@ export class AsyncQueuer<TValue> {
    * Processes a specified number of items to execute immediately with no wait time
    * If no numberOfItems is provided, all items will be processed
    */
-  flush = (
+  flush = async (
     numberOfItems: number = this.store.state.items.length,
     position?: QueuePosition,
-  ): void => {
+  ): Promise<void> => {
     this.#clearTimeouts() // clear any pending timeouts
-    for (let i = 0; i < numberOfItems; i++) {
-      this.execute(position)
-    }
+    await Promise.all(
+      Array.from({ length: numberOfItems }, () => this.execute(position)),
+    )
+  }
+
+  /**
+   * Processes all items in the queue as a batch using the provided function
+   * The queue is cleared after processing
+   */
+  flushAsBatch = async (
+    batchFunction: (items: Array<TValue>) => Promise<any>,
+  ): Promise<void> => {
+    this.#clearTimeouts() // clear any pending timeouts
+    const items = this.#getAllItems()
+    await batchFunction(items)
   }
 
   /**

package/src/async-rate-limiter.ts

@@ -11,6 +11,10 @@ export interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
    * Array of timestamps when executions occurred for rate limiting calculations
    */
   executionTimes: Array<number>
+  /**
+   * Whether the rate limiter has exceeded the limit
+   */
+  isExceeded: boolean
   /**
    * Whether the rate-limited function is currently executing asynchronously
    */
@@ -27,6 +31,10 @@ export interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
    * Number of function executions that have completed (either successfully or with errors)
    */
   settleCount: number
+  /**
+   * Current execution status - 'disabled' when not active, 'executing' when executing, 'idle' when not executing, 'exceeded' when rate limit is exceeded
+   */
+  status: 'disabled' | 'executing' | 'exceeded' | 'idle'
   /**
    * Number of function executions that have completed successfully
    */
@@ -39,11 +47,13 @@ function getDefaultAsyncRateLimiterState<
   return {
     errorCount: 0,
     executionTimes: [],
+    isExceeded: false,
     isExecuting: false,
     lastResult: undefined,
     rejectionCount: 0,
     settleCount: 0,
     successCount: 0,
+    status: 'idle',
   }
 }
 
@@ -189,6 +199,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     AsyncRateLimiterState<TFn>
   >(getDefaultAsyncRateLimiterState<TFn>())
   options: AsyncRateLimiterOptions<TFn>
+  #timeoutIds: Set<NodeJS.Timeout> = new Set()
 
   constructor(
     private fn: TFn,
@@ -200,6 +211,9 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
       throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
     this.#setState(this.options.initialState ?? {})
+    for (const executionTime of this.#getExecutionTimesInWindow()) {
+      this.#setCleanupTimeout(executionTime)
+    }
   }
 
   /**
@@ -215,7 +229,19 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
         ...state,
         ...newState,
       }
-      return combinedState
+      const isExceeded = combinedState.executionTimes.length >= this.#getLimit()
+      const status = !this.#getEnabled()
+        ? 'disabled'
+        : combinedState.isExecuting
+          ? 'executing'
+          : isExceeded
+            ? 'exceeded'
+            : 'idle'
+      return {
+        ...combinedState,
+        isExceeded,
+        status,
+      }
     })
   }
 
@@ -270,7 +296,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   ): Promise<ReturnType<TFn> | undefined> => {
     this.#cleanupOldExecutions()
 
-    const relevantExecutionTimes = this.#getRelevantExecutionTimes()
+    const relevantExecutionTimes = this.#getExecutionTimesInWindow()
 
     if (relevantExecutionTimes.length < this.#getLimit()) {
       await this.#execute(...args)
@@ -297,7 +323,8 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     })
 
     try {
-      const result = await this.fn(...args)
+      const result = await this.fn(...args) // EXECUTE!
+      this.#setCleanupTimeout(now)
       this.#setState({
         successCount: this.store.state.successCount + 1,
         lastResult: result,
@@ -322,7 +349,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     return this.store.state.lastResult
   }
 
-  #getRelevantExecutionTimes = (): Array<number> => {
+  #getExecutionTimesInWindow = (): Array<number> => {
     if (this.options.windowType === 'sliding') {
       // For sliding window, return all executions within the current window
       return this.store.state.executionTimes.filter(
@@ -331,22 +358,54 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     } else {
       // For fixed window, return all executions in the current window
       // The window starts from the oldest execution time
+      if (this.store.state.executionTimes.length === 0) {
+        return []
+      }
       const oldestExecution = Math.min(...this.store.state.executionTimes)
       const windowStart = oldestExecution
+      const windowEnd = windowStart + this.#getWindow()
+      const now = Date.now()
+
+      // If the window has expired, return empty array
+      if (now > windowEnd) {
+        return []
+      }
+
+      // Otherwise, return all executions in the current window
       return this.store.state.executionTimes.filter(
-        (time) =>
-          time >= windowStart && time <= windowStart + this.#getWindow(),
+        (time) => time >= windowStart && time <= windowEnd,
       )
     }
   }
 
+  #setCleanupTimeout = (executionTime: number): void => {
+    if (
+      this.options.windowType === 'sliding' ||
+      this.#timeoutIds.size === 0 // new fixed window
+    ) {
+      const now = Date.now()
+      const timeUntilExpiration = executionTime - now + this.#getWindow() + 1
+      const timeoutId = setTimeout(() => {
+        this.#cleanupOldExecutions()
+        this.#clearTimeout(timeoutId)
+      }, timeUntilExpiration)
+      this.#timeoutIds.add(timeoutId)
+    }
+  }
+
+  #clearTimeout = (timeoutId: NodeJS.Timeout): void => {
+    clearTimeout(timeoutId)
+    this.#timeoutIds.delete(timeoutId)
+  }
+
+  #clearTimeouts = (): void => {
+    this.#timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId))
+    this.#timeoutIds.clear()
+  }
+
   #cleanupOldExecutions = (): void => {
-    const now = Date.now()
-    const windowStart = now - this.#getWindow()
     this.#setState({
-      executionTimes: this.store.state.executionTimes.filter(
-        (time) => time > windowStart,
-      ),
+      executionTimes: this.#getExecutionTimesInWindow(),
     })
   }
 
@@ -354,7 +413,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
    * Returns the number of remaining executions allowed in the current window
    */
   getRemainingInWindow = (): number => {
-    const relevantExecutionTimes = this.#getRelevantExecutionTimes()
+    const relevantExecutionTimes = this.#getExecutionTimesInWindow()
     return Math.max(0, this.#getLimit() - relevantExecutionTimes.length)
   }
 
@@ -376,6 +435,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
    */
   reset = (): void => {
     this.#setState(getDefaultAsyncRateLimiterState())
+    this.#clearTimeouts()
   }
 }
 

package/src/async-throttler.ts

@@ -187,6 +187,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   #resolvePreviousPromise:
     | ((value?: ReturnType<TFn> | undefined) => void)
     | null = null
+  #rejectPreviousPromise: ((reason?: unknown) => void) | null = null
 
   constructor(
     private fn: TFn,
@@ -287,8 +288,9 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
       await this.#execute(...args)
       return this.store.state.lastResult
     } else {
-      return new Promise((resolve) => {
+      return new Promise((resolve, reject) => {
         this.#resolvePreviousPromise = resolve
+        this.#rejectPreviousPromise = reject
         // Clear any existing timeout to ensure we use the latest arguments
         this.#clearTimeout()
 
@@ -330,9 +332,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
       })
       this.options.onError?.(error, this)
       if (this.options.throwOnError) {
-        throw error
-      } else {
-        console.error(error)
+        this.#rejectPreviousPromiseInternal(error)
       }
     } finally {
       const lastExecutionTime = Date.now()
@@ -353,12 +353,18 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   /**
    * Processes the current pending execution immediately
    */
-  flush = (): void => {
+  flush = async (): Promise<ReturnType<TFn> | undefined> => {
     if (this.store.state.isPending && this.store.state.lastArgs) {
       this.#abortExecution() // abort any current execution
       this.#clearTimeout() // clear any existing timeout
-      this.#execute(...this.store.state.lastArgs)
+      const result = await this.#execute(...this.store.state.lastArgs)
+
+      // Resolve any pending promise from maybeExecute
+      this.#resolvePreviousPromiseInternal()
+
+      return result
     }
+    return undefined
   }
 
   #resolvePreviousPromiseInternal = (): void => {
@@ -368,6 +374,13 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     }
   }
 
+  #rejectPreviousPromiseInternal = (error: unknown): void => {
+    if (this.#rejectPreviousPromise) {
+      this.#rejectPreviousPromise(error)
+      this.#rejectPreviousPromise = null
+    }
+  }
+
   #clearTimeout = (): void => {
     if (this.#timeoutId) {
       clearTimeout(this.#timeoutId)

package/src/batcher.ts

@@ -15,14 +15,6 @@ export interface BatcherState<TValue> {
    * Whether the batcher is waiting for the timeout to trigger batch processing
    */
   isPending: boolean
-  /**
-   * Whether the batcher is active and will process items automatically
-   */
-  isRunning: boolean
-  /**
-   * Total number of items that have been processed across all batches
-   */
-  totalItemsProcessed: number
   /**
    * Array of items currently queued for batch processing
    */
@@ -35,6 +27,10 @@ export interface BatcherState<TValue> {
    * Current processing status - 'idle' when not processing, 'pending' when waiting for timeout
    */
   status: 'idle' | 'pending'
+  /**
+   * Total number of items that have been processed across all batches
+   */
+  totalItemsProcessed: number
 }
 
 function getDefaultBatcherState<TValue>(): BatcherState<TValue> {
@@ -42,7 +38,6 @@ function getDefaultBatcherState<TValue>(): BatcherState<TValue> {
     executionCount: 0,
     isEmpty: true,
     isPending: false,
-    isRunning: true,
     totalItemsProcessed: 0,
     items: [],
     size: 0,
@@ -204,7 +199,7 @@ export class Batcher<TValue> {
 
     if (shouldProcess) {
       this.#execute()
-    } else if (this.store.state.isRunning && this.options.wait !== Infinity) {
+    } else if (this.options.wait !== Infinity) {
       this.#clearTimeout() // clear any pending timeout to replace it with a new one
       this.#timeoutId = setTimeout(() => this.#execute(), this.#getWait())
     }
@@ -244,24 +239,6 @@ export class Batcher<TValue> {
     this.#execute() // execute immediately
   }
 
-  /**
-   * Stops the batcher from processing batches
-   */
-  stop = (): void => {
-    this.#setState({ isRunning: false })
-    this.#clearTimeout()
-  }
-
-  /**
-   * Starts the batcher and processes any pending items
-   */
-  start = (): void => {
-    this.#setState({ isRunning: true })
-    if (this.store.state.items.length > 0) {
-      this.#execute()
-    }
-  }
-
   /**
    * Returns a copy of all items in the batcher
    */

package/src/queuer.ts

@@ -26,14 +26,14 @@ export interface QueuerState<TValue> {
    * Whether the queuer is active and will process items automatically
    */
   isRunning: boolean
-  /**
-   * Timestamps when items were added to the queue for expiration tracking
-   */
-  itemTimestamps: Array<number>
   /**
    * Array of items currently waiting to be processed
    */
   items: Array<TValue>
+  /**
+   * Timestamps when items were added to the queue for expiration tracking
+   */
+  itemTimestamps: Array<number>
   /**
    * Whether the queuer has a pending timeout for processing the next item
    */
@@ -112,14 +112,14 @@ 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
    */
   onExecute?: (item: TValue, queuer: Queuer<TValue>) => void
+  /**
+   * Callback fired whenever an item expires in the queuer
+   */
+  onExpire?: (item: TValue, queuer: Queuer<TValue>) => void
   /**
    * Callback fired whenever an item is added or removed from the queuer
    */
@@ -472,6 +472,12 @@ export class Queuer<TValue> {
     return item
   }
 
+  #getAllItems = (): Array<TValue> => {
+    const items = this.peekAllItems()
+    this.clear()
+    return items
+  }
+
   /**
    * Removes and returns the next item from the queue and processes it using the provided function.
    *
@@ -509,6 +515,16 @@ export class Queuer<TValue> {
     this.#tick()
   }
 
+  /**
+   * Processes all items in the queue as a batch using the provided function
+   * The queue is cleared after processing
+   */
+  flushAsBatch = (batchFunction: (items: Array<TValue>) => void): void => {
+    const items = this.#getAllItems()
+    this.clear()
+    batchFunction(items)
+  }
+
   /**
    * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
    * Internal use only.

package/src/rate-limiter.ts

@@ -11,17 +11,27 @@ export interface RateLimiterState {
    * Array of timestamps when executions occurred for rate limiting calculations
    */
   executionTimes: Array<number>
+  /**
+   * Whether the rate limiter has exceeded the limit
+   */
+  isExceeded: boolean
   /**
    * Number of function executions that have been rejected due to rate limiting
    */
   rejectionCount: number
+  /**
+   * Current execution status - 'disabled' when not active, 'executing' when executing, 'idle' when not executing, 'exceeded' when rate limit is exceeded
+   */
+  status: 'disabled' | 'exceeded' | 'idle'
 }
 
 function getDefaultRateLimiterState(): RateLimiterState {
   return structuredClone({
     executionCount: 0,
     executionTimes: [],
+    isExceeded: false,
     rejectionCount: 0,
+    status: 'idle',
   })
 }
 
@@ -123,6 +133,7 @@ export class RateLimiter<TFn extends AnyFunction> {
   readonly store: Store<Readonly<RateLimiterState>> =
     new Store<RateLimiterState>(getDefaultRateLimiterState())
   options: RateLimiterOptions<TFn>
+  #timeoutIds: Set<NodeJS.Timeout> = new Set()
 
   constructor(
     private fn: TFn,
@@ -133,6 +144,9 @@ export class RateLimiter<TFn extends AnyFunction> {
       ...initialOptions,
     }
     this.#setState(this.options.initialState ?? {})
+    for (const executionTime of this.#getExecutionTimesInWindow()) {
+      this.#setCleanupTimeout(executionTime)
+    }
   }
 
   /**
@@ -148,7 +162,17 @@ export class RateLimiter<TFn extends AnyFunction> {
         ...state,
         ...newState,
       }
-      return combinedState
+      const isExceeded = combinedState.executionTimes.length >= this.#getLimit()
+      const status = !this.#getEnabled()
+        ? 'disabled'
+        : isExceeded
+          ? 'exceeded'
+          : 'idle'
+      return {
+        ...combinedState,
+        isExceeded,
+        status,
+      }
     })
   }
 
@@ -191,7 +215,7 @@ export class RateLimiter<TFn extends AnyFunction> {
   maybeExecute = (...args: Parameters<TFn>): boolean => {
     this.#cleanupOldExecutions()
 
-    const relevantExecutionTimes = this.#getRelevantExecutionTimes()
+    const relevantExecutionTimes = this.#getExecutionTimesInWindow()
 
     if (relevantExecutionTimes.length < this.#getLimit()) {
       this.#execute(...args)
@@ -210,13 +234,16 @@ export class RateLimiter<TFn extends AnyFunction> {
     const now = Date.now()
     this.fn(...args) // EXECUTE!
     this.store.state.executionTimes.push(now) // mutate state directly for performance
+
+    this.#setCleanupTimeout(now)
+
     this.#setState({
       executionCount: this.store.state.executionCount + 1,
     })
     this.options.onExecute?.(this)
   }
 
-  #getRelevantExecutionTimes = (): Array<number> => {
+  #getExecutionTimesInWindow = (): Array<number> => {
     if (this.options.windowType === 'sliding') {
       // For sliding window, return all executions within the current window
       return this.store.state.executionTimes.filter(
@@ -225,22 +252,54 @@ export class RateLimiter<TFn extends AnyFunction> {
     } else {
       // For fixed window, return all executions in the current window
       // The window starts from the oldest execution time
+      if (this.store.state.executionTimes.length === 0) {
+        return []
+      }
       const oldestExecution = Math.min(...this.store.state.executionTimes)
       const windowStart = oldestExecution
+      const windowEnd = windowStart + this.#getWindow()
+      const now = Date.now()
+
+      // If the window has expired, return empty array
+      if (now > windowEnd) {
+        return []
+      }
+
+      // Otherwise, return all executions in the current window
       return this.store.state.executionTimes.filter(
-        (time) =>
-          time >= windowStart && time <= windowStart + this.#getWindow(),
+        (time) => time >= windowStart && time <= windowEnd,
       )
     }
   }
 
+  #setCleanupTimeout = (executionTime: number): void => {
+    if (
+      this.options.windowType === 'sliding' ||
+      this.#timeoutIds.size === 0 // new fixed window
+    ) {
+      const now = Date.now()
+      const timeUntilExpiration = executionTime - now + this.#getWindow() + 1
+      const timeoutId = setTimeout(() => {
+        this.#cleanupOldExecutions()
+        this.#clearTimeout(timeoutId)
+      }, timeUntilExpiration)
+      this.#timeoutIds.add(timeoutId)
+    }
+  }
+
+  #clearTimeout = (timeoutId: NodeJS.Timeout): void => {
+    clearTimeout(timeoutId)
+    this.#timeoutIds.delete(timeoutId)
+  }
+
+  #clearTimeouts = (): void => {
+    this.#timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId))
+    this.#timeoutIds.clear()
+  }
+
   #cleanupOldExecutions = (): void => {
-    const now = Date.now()
-    const windowStart = now - this.#getWindow()
     this.#setState({
-      executionTimes: this.store.state.executionTimes.filter(
-        (time) => time > windowStart,
-      ),
+      executionTimes: this.#getExecutionTimesInWindow(),
     })
   }
 
@@ -248,7 +307,7 @@ export class RateLimiter<TFn extends AnyFunction> {
    * Returns the number of remaining executions allowed in the current window
    */
   getRemainingInWindow = (): number => {
-    const relevantExecutionTimes = this.#getRelevantExecutionTimes()
+    const relevantExecutionTimes = this.#getExecutionTimesInWindow()
     return Math.max(0, this.#getLimit() - relevantExecutionTimes.length)
   }
 
@@ -268,6 +327,7 @@ export class RateLimiter<TFn extends AnyFunction> {
    */
   reset = (): void => {
     this.#setState(getDefaultRateLimiterState())
+    this.#clearTimeouts()
   }
 }