AsyncBatcher

Defined in: async-batcher.ts:265

A class that collects items and processes them in batches asynchronously.

Async vs Sync Versions: The async version provides advanced features over the sync Batcher:

Returns promises that can be awaited for batch results
Built-in retry support via AsyncRetryer integration
Abort support to cancel in-flight batch executions
Cancel support to prevent pending batches from starting
Comprehensive error handling with onError callbacks and throwOnError control
Detailed execution tracking (success/error/settle counts)

The sync Batcher is lighter weight and simpler when you don't need async features, return values, or execution control.

What is Batching? Batching is a technique for grouping multiple operations together to be processed as a single unit.

The AsyncBatcher provides a flexible way to implement async 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
Error handling for failed batch operations

Error Handling:

If an onError handler is provided, it will be called with the error, the batch of items that failed, and batcher 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 AsyncBatcher instance

State Management:

Uses TanStack Store for reactive state management
Use initialState to provide initial state values when creating the async batcher
Use onSuccess callback to react to successful batch execution and implement custom logic
Use onError callback to react to batch execution errors and implement custom error handling
Use onSettled callback to react to batch execution completion (success or error) and implement custom logic
Use onExecute callback to react to batch execution and implement custom logic
Use onItemsChange callback to react to items being added or removed from the batcher
The state includes total items processed, success/error counts, and execution status
State can be accessed via asyncBatcher.store.state when using the class directly
When using framework adapters (React/Solid), state is accessed from asyncBatcher.state

Example

const batcher = new AsyncBatcher<number>(
  async (items) => {
    const result = await processItems(items);
    console.log('Processing batch:', items);
    return result;
  },
  {
    maxSize: 5,
    wait: 2000,
    onSuccess: (result) => console.log('Batch succeeded:', result),
    onError: (error) => console.error('Batch failed:', error)
  }
);

batcher.addItem(1);
batcher.addItem(2);
// After 2 seconds or when 5 items are added, whichever comes first,
// the batch will be processed and the result will be available
// batcher.execute() // manually trigger a batch

Type Parameters

TValue

Constructors

Constructor

new AsyncBatcher<TValue>(fn, initialOptions): AsyncBatcher<TValue>;

Defined in: async-batcher.ts:277

Parameters

fn

(items) => Promise<any>

initialOptions

AsyncBatcherOptions<TValue>

Returns

AsyncBatcher<TValue>

Properties

asyncRetryers

asyncRetryers: Map<number, AsyncRetryer<(items) => Promise<any>>>;

Defined in: async-batcher.ts:271

fn

fn: (items) => Promise<any>;

Defined in: async-batcher.ts:278

Parameters

items

TValue[]

Returns

Promise<any>

key

key: string | undefined;

Defined in: async-batcher.ts:269

options

options: AsyncBatcherOptionsWithOptionalCallbacks<TValue>;

Defined in: async-batcher.ts:270

store

readonly store: Store<Readonly<AsyncBatcherState<TValue>>>;

Defined in: async-batcher.ts:266

Methods

abort()

abort(): void;

Defined in: async-batcher.ts:494

Aborts all ongoing executions with the internal abort controllers. Does NOT cancel any pending execution that have not started yet. Does NOT clear out the items.

Returns

void

addItem()

addItem(item): Promise<any>;

Defined in: async-batcher.ts:346

Adds an item to the async batcher If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed

Parameters

item

TValue

Returns

Promise<any>

The result from the batch function, or undefined if an error occurred and was handled by onError

Throws

The error from the batch function if no onError handler is configured or throwOnError is true

cancel()

cancel(): void;

Defined in: async-batcher.ts:507

Cancels any pending execution that have not started yet. Does NOT abort any execution already in progress. Does NOT clear out the items.

Returns

void

clear()

clear(): void;

Defined in: async-batcher.ts:455

Removes all items from the async batcher

Returns

void

flush()

flush(): Promise<any>;

Defined in: async-batcher.ts:429

Processes the current batch of items immediately

Returns

Promise<any>

getAbortSignal()

getAbortSignal(executionCount?): AbortSignal | null;

Defined in: async-batcher.ts:483

Returns the AbortSignal for a specific execution. If no executionCount is provided, returns the signal for the most recent execution. Returns null if no execution is found or not currently executing.

Parameters

executionCount?

number

Optional specific execution to get signal for

Returns

AbortSignal | null

Example

const batcher = new AsyncBatcher(
  async (items: string[]) => {
    const signal = batcher.getAbortSignal()
    if (signal) {
      const response = await fetch('/api/batch', {
        method: 'POST',
        body: JSON.stringify(items),
        signal
      })
      return response.json()
    }
  },
  { maxSize: 10, wait: 100 }
)