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
initialStateto provide initial state values when creating the batcher - Use
onExecutecallback to react to batch execution and implement custom logic - Use
onItemsChangecallback 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.statewhen 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