Function: 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