asyncBatch

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 processing
• asyncRetryerOptions: Configure retry behavior for batch executions
• started: Whether to start processing immediately (default: true)

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 underlying 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 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 the underlying AsyncBatcher instance's store.state property
• 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