📄 tanstack/pacer/latest/docs/reference/classes/AsyncBatcher

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


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

TValue

Constructors
------------ ### Constructor

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


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>>>;


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

Defined in: async-batcher.ts:271

### fn()

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


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

Defined in: async-batcher.ts:278

#### Parameters ##### items

TValue[]

#### Returns

Promise<any>

### key

key: string | undefined;


key: string | undefined;

Defined in: async-batcher.ts:269

### options

options: AsyncBatcherOptionsWithOptionalCallbacks<TValue>;


options: AsyncBatcherOptionsWithOptionalCallbacks<TValue>;

Defined in: async-batcher.ts:270

### store

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


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

Defined in: async-batcher.ts:266

Methods
------- ### abort()

abort(): void;


abort(): void;

Defined in: async-batcher.ts:488

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>;


addItem(item): Promise<any>;

Defined in: async-batcher.ts:340

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;


cancel(): void;

Defined in: async-batcher.ts:501

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;


clear(): void;

Defined in: async-batcher.ts:449

Removes all items from the async batcher

#### Returns

void

### flush()

flush(): Promise<any>;


flush(): Promise<any>;

Defined in: async-batcher.ts:423

Processes the current batch of items immediately

#### Returns

Promise<any>

### getAbortSignal()

getAbortSignal(executeCount?): AbortSignal | null;


getAbortSignal(executeCount?): AbortSignal | null;

Defined in: async-batcher.ts:477

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

#### Parameters ##### executeCount?

number

Optional specific execution to get signal for

#### Returns

AbortSignal | null

#### Example

typescript

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


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

### peekAllItems()

peekAllItems(): TValue[];


peekAllItems(): TValue[];

Defined in: async-batcher.ts:431

Returns a copy of all items in the async batcher

#### Returns

TValue[]

### peekFailedItems()

peekFailedItems(): TValue[];


peekFailedItems(): TValue[];

Defined in: async-batcher.ts:435

#### Returns

TValue[]

### reset()

reset(): void;


reset(): void;

Defined in: async-batcher.ts:511

Resets the async batcher state to its default values

#### Returns

void

### setOptions()

setOptions(newOptions): void;


setOptions(newOptions): void;

Defined in: async-batcher.ts:299

Updates the async batcher options

#### Parameters ##### newOptions

Partial<AsyncBatcherOptions <TValue>>

void

Partners Become a Partner

scarf analytics