function asyncBatch<TValue>(fn, options): (item) => Promise<any>;
Defined in: async-batcher.ts:588
Creates an async batcher that processes items in batches.
Async vs Sync Versions: The async version provides advanced features over the sync batch function:
- 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 batch function 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.
Configuration Options:
maxSize: Maximum number of items per batch (default: Infinity)wait: Time to wait before processing batch (default: Infinity)getShouldExecute: Custom logic to trigger batch processingasyncRetryerOptions: Configure retry behavior for batch executionsstarted: Whether to start processing immediately (default: true)
Error Handling:
- If an
onErrorhandler is provided, it will be called with the error, the batch of items that failed, and batcher instance - If
throwOnErroris true (default when no onError handler is provided), the error will be thrown - If
throwOnErroris 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 AsyncBatcher instance
State Management:
- Uses TanStack Store for reactive state management
- Use
initialStateto provide initial state values when creating the async batcher - Use
onSuccesscallback to react to successful batch execution and implement custom logic - Use
onErrorcallback to react to batch execution errors and implement custom error handling - Use
onSettledcallback to react to batch execution completion (success or error) and implement custom logic - Use
onItemsChangecallback 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 the underlying AsyncBatcher instance's
store.stateproperty - When using framework adapters (React/Solid), state is accessed from the hook's state property
Type Parameters#
TValue#
TValue
Parameters#
fn#
(items) => Promise<any>
options#
AsyncBatcherOptions<TValue>
Returns#
(item): Promise<any>;
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
Example#
const batchItems = asyncBatch<number>(
async (items) => {
const result = await processApiCall(items);
console.log('Processing:', items);
return result;
},
{
maxSize: 3,
wait: 1000,
onSuccess: (result) => console.log('Batch succeeded:', result),
onError: (error) => console.error('Batch failed:', error)
}
);
batchItems(1);
batchItems(2);
batchItems(3); // Triggers batch processing