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