@tanstack/pacer 0.6.0 → 0.7.0

package/src/async-rate-limiter.ts

@@ -147,7 +147,6 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
 
   /**
    * Updates the rate limiter options
-   * Returns the new options state
    */
   setOptions(newOptions: Partial<AsyncRateLimiterOptions<TFn>>): void {
     this._options = { ...this._options, ...newOptions }
@@ -221,7 +220,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     if (this._options.windowType === 'sliding') {
       // For sliding window, we can execute if we have capacity in the current window
       if (this._executionTimes.length < limit) {
-        await this.executeFunction(...args)
+        await this.execute(...args)
         return this._lastResult
       }
     } else {
@@ -231,7 +230,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
       const isNewWindow = oldestExecution + window <= now
 
       if (isNewWindow || this._executionTimes.length < limit) {
-        await this.executeFunction(...args)
+        await this.execute(...args)
         return this._lastResult
       }
     }
@@ -240,7 +239,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     return undefined
   }
 
-  private async executeFunction(
+  private async execute(
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> {
     if (!this.getEnabled()) return

package/src/async-throttler.ts

@@ -114,6 +114,9 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   private _settleCount = 0
   private _successCount = 0
   private _timeoutId: NodeJS.Timeout | null = null
+  private _resolvePreviousPromise:
+    | ((value?: ReturnType<TFn> | undefined) => void)
+    | null = null
 
   constructor(
     private fn: TFn,
@@ -128,7 +131,6 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
 
   /**
    * Updates the throttler options
-   * Returns the new options state
    */
   setOptions(newOptions: Partial<AsyncThrottlerOptions<TFn>>): void {
     this._options = { ...this._options, ...newOptions }
@@ -181,15 +183,18 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     const timeSinceLastExecution = now - this._lastExecutionTime
     const wait = this.getWait()
 
+    this.resolvePreviousPromise()
+
     // Handle leading execution
     if (this._options.leading && timeSinceLastExecution >= wait) {
-      await this.executeFunction(...args)
+      await this.execute(...args)
       return this._lastResult
     } else {
       // Store the most recent arguments for potential trailing execution
       this._lastArgs = args
 
       return new Promise((resolve) => {
+        this._resolvePreviousPromise = resolve
         // Clear any existing timeout to ensure we use the latest arguments
         if (this._timeoutId) {
           clearTimeout(this._timeoutId)
@@ -203,8 +208,9 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
           const timeoutDuration = wait - _timeSinceLastExecution
           this._timeoutId = setTimeout(async () => {
             if (this._lastArgs !== undefined) {
-              await this.executeFunction(...this._lastArgs)
+              await this.execute(...this._lastArgs)
             }
+            this._resolvePreviousPromise = null
             resolve(this._lastResult)
           }, timeoutDuration)
         }
@@ -212,7 +218,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     }
   }
 
-  private async executeFunction(
+  private async execute(
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> {
     if (!this.getEnabled() || this._isExecuting) return undefined
@@ -241,6 +247,13 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     return this._lastResult
   }
 
+  private resolvePreviousPromise(): void {
+    if (this._resolvePreviousPromise) {
+      this._resolvePreviousPromise(this._lastResult)
+      this._resolvePreviousPromise = null
+    }
+  }
+
   /**
    * Cancels any pending execution or aborts any execution in progress
    */
@@ -253,6 +266,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
       this._abortController.abort()
       this._abortController = null
     }
+    this.resolvePreviousPromise()
     this._lastArgs = undefined
   }
 

package/src/batcher.ts

@@ -0,0 +1,253 @@
+import type { OptionalKeys } from './types'
+
+/**
+ * Options for configuring a Batcher instance
+ */
+export interface BatcherOptions<TValue> {
+  /**
+   * Custom function to determine if a batch should be processed
+   * Return true to process the batch immediately
+   */
+  getShouldExecute?: (items: Array<TValue>, batcher: Batcher<TValue>) => boolean
+  /**
+   * Maximum number of items in a batch
+   * @default Infinity
+   */
+  maxSize?: number
+  /**
+   * Callback fired after a batch is processed
+   */
+  onExecute?: (batcher: Batcher<TValue>) => void
+  /**
+   * Callback fired when the batcher's running state changes
+   */
+  onIsRunningChange?: (batcher: Batcher<TValue>) => void
+  /**
+   * Callback fired after items are added to the batcher
+   */
+  onItemsChange?: (batcher: Batcher<TValue>) => void
+  /**
+   * Whether the batcher should start processing immediately
+   * @default true
+   */
+  started?: boolean
+  /**
+   * Maximum time in milliseconds to wait before processing a batch.
+   * If the wait duration has elapsed, the batch will be processed.
+   * If not provided, the batch will not be triggered by a timeout.
+   * @default Infinity
+   */
+  wait?: number
+}
+
+type BatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<
+  Required<BatcherOptions<TValue>>,
+  'onExecute' | 'onItemsChange' | 'onIsRunningChange'
+>
+
+const defaultOptions: BatcherOptionsWithOptionalCallbacks<any> = {
+  getShouldExecute: () => false,
+  maxSize: Infinity,
+  started: true,
+  wait: Infinity,
+}
+
+/**
+ * A class that collects items and processes them in batches.
+ *
+ * Batching is a technique for grouping multiple operations together to be processed as a single unit.
+ *
+ * The Batcher provides a flexible way to implement batching with configurable:
+ * - Maximum batch size (number of items per batch)
+ * - Time-based batching (process after X milliseconds)
+ * - Custom batch processing logic via getShouldExecute
+ * - Event callbacks for monitoring batch operations
+ *
+ * @example
+ * ```ts
+ * const batcher = new Batcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   {
+ *     maxSize: 5,
+ *     wait: 2000,
+ *     onExecuteBatch: (items) => console.log('Batch executed:', items)
+ *   }
+ * );
+ *
+ * batcher.addItem(1);
+ * batcher.addItem(2);
+ * // After 2 seconds or when 5 items are added, whichever comes first,
+ * // the batch will be processed
+ * // batcher.execute() // manually trigger a batch
+ * ```
+ */
+export class Batcher<TValue> {
+  private _options: BatcherOptionsWithOptionalCallbacks<TValue>
+  private _batchExecutionCount = 0
+  private _itemExecutionCount = 0
+  private _items: Array<TValue> = []
+  private _running: boolean
+  private _timeoutId: NodeJS.Timeout | null = null
+
+  constructor(
+    private fn: (items: Array<TValue>) => void,
+    initialOptions: BatcherOptions<TValue>,
+  ) {
+    this._options = { ...defaultOptions, ...initialOptions }
+    this._running = this._options.started
+  }
+
+  /**
+   * Updates the batcher options
+   */
+  setOptions(newOptions: Partial<BatcherOptions<TValue>>): void {
+    this._options = { ...this._options, ...newOptions }
+  }
+
+  /**
+   * Returns the current batcher options
+   */
+  getOptions(): BatcherOptions<TValue> {
+    return this._options
+  }
+
+  /**
+   * Adds an item to the batcher
+   * If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
+   */
+  addItem(item: TValue): void {
+    this._items.push(item)
+    this._options.onItemsChange?.(this)
+
+    const shouldProcess =
+      this._items.length >= this._options.maxSize ||
+      this._options.getShouldExecute(this._items, this)
+
+    if (shouldProcess) {
+      this.execute()
+    } else if (
+      this._running &&
+      !this._timeoutId &&
+      this._options.wait !== Infinity
+    ) {
+      this._timeoutId = setTimeout(() => this.execute(), this._options.wait)
+    }
+  }
+
+  /**
+   * Processes the current batch of items.
+   * This method will automatically be triggered if the batcher is running and any of these conditions are met:
+   * - The number of items reaches batchSize
+   * - The wait duration has elapsed
+   * - The getShouldExecute function returns true upon adding an item
+   *
+   * You can also call this method manually to process the current batch at any time.
+   */
+  execute(): void {
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId)
+      this._timeoutId = null
+    }
+
+    if (this._items.length === 0) {
+      return
+    }
+
+    const batch = this.getAllItems() // copy of the items to be processed (to prevent race conditions)
+    this._items = [] // Clear items before processing to prevent race conditions
+    this._options.onItemsChange?.(this) // Call onItemsChange to notify listeners that the items have changed
+
+    this.fn(batch)
+    this._batchExecutionCount++
+    this._itemExecutionCount += batch.length
+    this._options.onExecute?.(this)
+  }
+
+  /**
+   * Stops the batcher from processing batches
+   */
+  stop(): void {
+    this._running = false
+    this._options.onIsRunningChange?.(this)
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId)
+      this._timeoutId = null
+    }
+  }
+
+  /**
+   * Starts the batcher and processes any pending items
+   */
+  start(): void {
+    this._running = true
+    this._options.onIsRunningChange?.(this)
+    if (this._items.length > 0 && !this._timeoutId) {
+      this._timeoutId = setTimeout(() => this.execute(), this._options.wait)
+    }
+  }
+
+  /**
+   * Returns the current number of items in the batcher
+   */
+  getSize(): number {
+    return this._items.length
+  }
+
+  /**
+   * Returns true if the batcher is empty
+   */
+  getIsEmpty(): boolean {
+    return this._items.length === 0
+  }
+
+  /**
+   * Returns true if the batcher is running
+   */
+  getIsRunning(): boolean {
+    return this._running
+  }
+
+  /**
+   * Returns a copy of all items currently in the batcher
+   */
+  getAllItems(): Array<TValue> {
+    return [...this._items]
+  }
+
+  /**
+   * Returns the number of times batches have been processed
+   */
+  getBatchExecutionCount(): number {
+    return this._batchExecutionCount
+  }
+
+  /**
+   * Returns the total number of individual items that have been processed
+   */
+  getItemExecutionCount(): number {
+    return this._itemExecutionCount
+  }
+}
+
+/**
+ * Creates a batcher that processes items in batches
+ *
+ * @example
+ * ```ts
+ * const batchItems = batch<number>({
+ *   batchSize: 3,
+ *   processBatch: (items) => console.log('Processing:', items)
+ * });
+ *
+ * batchItems(1);
+ * batchItems(2);
+ * batchItems(3); // Triggers batch processing
+ * ```
+ */
+export function batch<TValue>(
+  fn: (items: Array<TValue>) => void,
+  options: BatcherOptions<TValue>,
+) {
+  const batcher = new Batcher<TValue>(fn, options)
+  return batcher.addItem.bind(batcher)
+}

package/src/debouncer.ts

@@ -84,7 +84,6 @@ export class Debouncer<TFn extends AnyFunction> {
 
   /**
    * Updates the debouncer options
-   * Returns the new options state
    */
   setOptions(newOptions: Partial<DebouncerOptions<TFn>>): void {
     this._options = { ...this._options, ...newOptions }
@@ -127,7 +126,7 @@ export class Debouncer<TFn extends AnyFunction> {
     if (this._options.leading && this._canLeadingExecute) {
       this._canLeadingExecute = false
       _didLeadingExecute = true
-      this.executeFunction(...args)
+      this.execute(...args)
     }
 
     // Start pending state to indicate that the debouncer is waiting for the trailing edge
@@ -142,12 +141,12 @@ export class Debouncer<TFn extends AnyFunction> {
     this._timeoutId = setTimeout(() => {
       this._canLeadingExecute = true
       if (this._options.trailing && !_didLeadingExecute) {
-        this.executeFunction(...args)
+        this.execute(...args)
       }
     }, this.getWait())
   }
 
-  private executeFunction(...args: Parameters<TFn>): void {
+  private execute(...args: Parameters<TFn>): void {
     if (!this.getEnabled()) return undefined
     this.fn(...args) // EXECUTE!
     this._isPending = false

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './async-debouncer'
 export * from './async-queuer'
 export * from './async-rate-limiter'
 export * from './async-throttler'
+export * from './batcher'
 export * from './compare'
 export * from './debouncer'
 export * from './queuer'