@tanstack/pacer 0.5.0 → 0.7.0

package/src/async-rate-limiter.ts

@@ -1,5 +1,5 @@
 import { parseFunctionOrValue } from './utils'
-import type { AnyAsyncFunction } from './types'
+import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 /**
  * Options for configuring an async rate-limited function
@@ -17,7 +17,9 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
    */
   limit: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)
   /**
-   * Optional error handler for when the rate-limited function throws
+   * Optional error handler for when the rate-limited function throws.
+   * If provided, the handler will be called with the error and rate limiter instance.
+   * This can be used alongside throwOnError - the handler will be called before any error is thrown.
    */
   onError?: (error: unknown, rateLimiter: AsyncRateLimiter<TFn>) => void
   /**
@@ -35,6 +37,12 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
     result: ReturnType<TFn>,
     rateLimiter: AsyncRateLimiter<TFn>,
   ) => void
+  /**
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
+   */
+  throwOnError?: boolean
   /**
    * Time window in milliseconds within which the limit applies.
    * Can be a number or a function that returns a number.
@@ -49,14 +57,16 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
   windowType?: 'fixed' | 'sliding'
 }
 
-const defaultOptions: Required<
-  Omit<AsyncRateLimiterOptions<any>, 'limit' | 'window'>
+type AsyncRateLimiterOptionsWithOptionalCallbacks = OptionalKeys<
+  AsyncRateLimiterOptions<any>,
+  'onError' | 'onReject' | 'onSettled' | 'onSuccess'
+>
+
+const defaultOptions: Omit<
+  AsyncRateLimiterOptionsWithOptionalCallbacks,
+  'limit' | 'window'
 > = {
   enabled: true,
-  onError: () => {},
-  onReject: () => {},
-  onSettled: () => {},
-  onSuccess: () => {},
   windowType: 'fixed',
 }
 
@@ -84,11 +94,29 @@ const defaultOptions: Required<
  * Rate limiting is best used for hard API limits or resource constraints. For UI updates or
  * smoothing out frequent events, throttling or debouncing usually provide better user experience.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and rate limiter instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncRateLimiter instance
+ * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+ *
  * @example
  * ```ts
  * const rateLimiter = new AsyncRateLimiter(
  *   async (id: string) => await api.getData(id),
- *   { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
+ *   {
+ *     limit: 5,
+ *     window: 1000,
+ *     windowType: 'sliding',
+ *     onError: (error) => {
+ *       console.error('API call failed:', error);
+ *     },
+ *     onReject: (limiter) => {
+ *       console.log(`Rate limit exceeded. Try again in ${limiter.getMsUntilNextWindow()}ms`);
+ *     }
+ *   }
  * );
  *
  * // Will execute immediately until limit reached, then block
@@ -97,7 +125,7 @@ const defaultOptions: Required<
  * ```
  */
 export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
-  private _options: AsyncRateLimiterOptions<TFn>
+  private _options: AsyncRateLimiterOptionsWithOptionalCallbacks
   private _errorCount = 0
   private _executionTimes: Array<number> = []
   private _lastResult: ReturnType<TFn> | undefined
@@ -113,12 +141,12 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     this._options = {
       ...defaultOptions,
       ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
   }
 
   /**
    * Updates the rate limiter options
-   * Returns the new options state
    */
   setOptions(newOptions: Partial<AsyncRateLimiterOptions<TFn>>): void {
     this._options = { ...this._options, ...newOptions }
@@ -127,8 +155,8 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   /**
    * Returns the current rate limiter options
    */
-  getOptions(): Required<AsyncRateLimiterOptions<TFn>> {
-    return this._options as Required<AsyncRateLimiterOptions<TFn>>
+  getOptions(): AsyncRateLimiterOptions<TFn> {
+    return this._options
   }
 
   /**
@@ -157,6 +185,19 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
    * Will reject execution if the number of calls in the current window exceeds the limit.
    * If execution is allowed, waits for any previous execution to complete before proceeding.
    *
+   * Error Handling:
+   * - If the rate-limited function throws and no `onError` handler is configured,
+   *   the error will be thrown from this method.
+   * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+   *   and this method will return undefined.
+   * - If the rate limit is exceeded, the execution will be rejected and the `onReject` handler
+   *   will be called if configured.
+   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+   * - Rate limit rejections can be tracked using `getRejectionCount()`.
+   *
+   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+   * @throws The error from the rate-limited function if no onError handler is configured
+   *
    * @example
    * ```ts
    * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
@@ -179,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 {
@@ -189,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
       }
     }
@@ -198,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
@@ -213,6 +254,11 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     } catch (error) {
       this._errorCount++
       this._options.onError?.(error, this)
+      if (this._options.throwOnError) {
+        throw error
+      } else {
+        console.error(error)
+      }
     } finally {
       this._isExecuting = false
       this._settleCount++
@@ -326,6 +372,14 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  * 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.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and rate limiter instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncRateLimiter instance
+ * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+ *
  * @example
  * ```ts
  * // Rate limit to 5 calls per minute with a sliding window
@@ -333,6 +387,9 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  *   limit: 5,
  *   window: 60000,
  *   windowType: 'sliding',
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   },
  *   onReject: (rateLimiter) => {
  *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }

package/src/async-throttler.ts

@@ -1,5 +1,5 @@
 import { parseFunctionOrValue } from './utils'
-import type { AnyAsyncFunction } from './types'
+import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 /**
  * Options for configuring an async throttled function
@@ -17,7 +17,9 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
    */
   leading?: boolean
   /**
-   * Optional error handler for when the throttled function throws
+   * Optional error handler for when the throttled function throws.
+   * If provided, the handler will be called with the error and throttler instance.
+   * This can be used alongside throwOnError - the handler will be called before any error is thrown.
    */
   onError?: (error: unknown, asyncThrottler: AsyncThrottler<TFn>) => void
   /**
@@ -31,6 +33,12 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
     result: ReturnType<TFn>,
     asyncThrottler: AsyncThrottler<TFn>,
   ) => void
+  /**
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
+   */
+  throwOnError?: boolean
   /**
    * Whether to execute the function on the trailing edge of the wait period
    * Defaults to true
@@ -44,12 +52,14 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
   wait: number | ((throttler: AsyncThrottler<TFn>) => number)
 }
 
-const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
+type AsyncThrottlerOptionsWithOptionalCallbacks = OptionalKeys<
+  AsyncThrottlerOptions<any>,
+  'onError' | 'onSettled' | 'onSuccess'
+>
+
+const defaultOptions: AsyncThrottlerOptionsWithOptionalCallbacks = {
   enabled: true,
   leading: true,
-  onError: () => {},
-  onSettled: () => {},
-  onSuccess: () => {},
   trailing: true,
   wait: 0,
 }
@@ -68,12 +78,24 @@ const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
  * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
  * ensure a maximum execution frequency.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
  * @example
  * ```ts
  * const throttler = new AsyncThrottler(async (value: string) => {
  *   const result = await saveToAPI(value);
  *   return result; // Return value is preserved
- * }, { wait: 1000 });
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
  *
  * // Will only execute once per second no matter how often called
  * // Returns the API response directly
@@ -81,7 +103,7 @@ const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
  * ```
  */
 export class AsyncThrottler<TFn extends AnyAsyncFunction> {
-  private _options: Required<AsyncThrottlerOptions<TFn>>
+  private _options: AsyncThrottlerOptionsWithOptionalCallbacks
   private _abortController: AbortController | null = null
   private _errorCount = 0
   private _isExecuting = false
@@ -92,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,
@@ -100,12 +125,12 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     this._options = {
       ...defaultOptions,
       ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
   }
 
   /**
    * Updates the throttler options
-   * Returns the new options state
    */
   setOptions(newOptions: Partial<AsyncThrottlerOptions<TFn>>): void {
     this._options = { ...this._options, ...newOptions }
@@ -119,7 +144,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   /**
    * Returns the current options
    */
-  getOptions(): Required<AsyncThrottlerOptions<TFn>> {
+  getOptions(): AsyncThrottlerOptions<TFn> {
     return this._options
   }
 
@@ -127,7 +152,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
    * Returns the current enabled state of the throttler
    */
   getEnabled(): boolean {
-    return parseFunctionOrValue(this._options.enabled, this)
+    return !!parseFunctionOrValue(this._options.enabled, this)
   }
 
   /**
@@ -138,8 +163,18 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   }
 
   /**
-   * Attempts to execute the throttled function
-   * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+   * Attempts to execute the throttled function.
+   * If a call is already in progress, it may be blocked or queued depending on the `wait` option.
+   *
+   * Error Handling:
+   * - If the throttled function throws and no `onError` handler is configured,
+   *   the error will be thrown from this method.
+   * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+   *   and this method will return undefined.
+   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+   *
+   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+   * @throws The error from the throttled function if no onError handler is configured
    */
   async maybeExecute(
     ...args: Parameters<TFn>
@@ -148,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)
@@ -170,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)
         }
@@ -179,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
@@ -188,21 +227,33 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
       this._isExecuting = true
       this._lastResult = await this.fn(...args) // EXECUTE!
       this._successCount++
-      this._options.onSuccess(this._lastResult!, this)
+      this._options.onSuccess?.(this._lastResult!, this)
     } catch (error) {
       this._errorCount++
-      this._options.onError(error, this)
+      this._options.onError?.(error, this)
+      if (this._options.throwOnError) {
+        throw error
+      } else {
+        console.error(error)
+      }
     } finally {
       this._isExecuting = false
       this._settleCount++
       this._abortController = null
       this._lastExecutionTime = Date.now()
       this._nextExecutionTime = this._lastExecutionTime + this.getWait()
-      this._options.onSettled(this)
+      this._options.onSettled?.(this)
     }
     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
    */
@@ -215,6 +266,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
       this._abortController.abort()
       this._abortController = null
     }
+    this.resolvePreviousPromise()
     this._lastArgs = undefined
   }
 
@@ -284,12 +336,24 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
  * 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 throttled function.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
  * @example
  * ```ts
  * const throttled = asyncThrottle(async (value: string) => {
  *   const result = await saveToAPI(value);
  *   return result; // Return value is preserved
- * }, { wait: 1000 });
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
  *
  * // This will execute at most once per second
  * // Returns the API response directly

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)
+}