Batcher

Defined in: batcher.ts:145

A class that collects items and processes them in batches.

Batching is a technique for grouping multiple operations together to be processed as a single unit. This synchronous version is lighter weight and often all you need - upgrade to AsyncBatcher when you need promises, retry support, abort/cancel capabilities, or advanced error handling.

The Batcher provides a flexible way to implement 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

State Management:

• Uses TanStack Store for reactive state management
• Use initialState to provide initial state values when creating the batcher
• 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 batch execution count, total items processed, items, and running status
• State can be accessed via batcher.store.state when using the class directly
• When using framework adapters (React/Solid), state is accessed from batcher.state

Example

const batcher = new Batcher<number>(
  (items) => console.log('Processing batch:', items),
  {
    maxSize: 5,
    wait: 2000,
    onExecute: (batch, batcher) => console.log('Batch executed:', batch)
  }
);

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

Type Parameters

TValue

TValue

Constructors

Constructor

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

Defined in: batcher.ts:153

Parameters

fn

(items) => void

initialOptions

BatcherOptions<TValue>

Returns

Batcher<TValue>

Properties

fn

fn: (items) => void;

Defined in: batcher.ts:154

Parameters

items

TValue[]

Returns

void

key

key: string | undefined;

Defined in: batcher.ts:149

options

options: BatcherOptionsWithOptionalCallbacks<TValue>;

Defined in: batcher.ts:150

store

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

Defined in: batcher.ts:146

Methods

addItem()

addItem(item): void;

Defined in: batcher.ts:211

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

Parameters

item

TValue

Returns

void

cancel()

cancel(): void;

Defined in: batcher.ts:289

Cancels any pending execution that was scheduled. Does NOT clear out the items.

Returns

void

clear()

clear(): void;

Defined in: batcher.ts:281

Removes all items from the batcher

Returns

void

flush()

flush(): void;

Defined in: batcher.ts:259

Processes the current batch of items immediately

Returns

void

peekAllItems()

peekAllItems(): TValue[];

Defined in: batcher.ts:267

Returns a copy of all items in the batcher

Returns

TValue[]

reset()

reset(): void;

Defined in: batcher.ts:297

Resets the batcher state to its default values

Returns

void

setOptions()

setOptions(newOptions): void;

Defined in: batcher.ts:180

Updates the batcher options

Parameters

newOptions

Partial<BatcherOptions<TValue>>

Returns

void