Open History to see the last commit
1---
2id: Batcher
3title: Batcher
4---
5
6Defined in: [batcher.ts:145](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L145)
7
8A class that collects items and processes them in batches.
9
10Batching is a technique for grouping multiple operations together to be processed as a single unit.
11This 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.
12
13The Batcher provides a flexible way to implement batching with configurable:
14- Maximum batch size (number of items per batch)
15- Time-based batching (process after X milliseconds)
16- Custom batch processing logic via getShouldExecute
17- Event callbacks for monitoring batch operations
18
19State Management:
20- Uses TanStack Store for reactive state management
21- Use `initialState` to provide initial state values when creating the batcher
22- Use `onExecute` callback to react to batch execution and implement custom logic
23- Use `onItemsChange` callback to react to items being added or removed from the batcher
24- The state includes batch execution count, total items processed, items, and running status
25- State can be accessed via `batcher.store.state` when using the class directly
26- When using framework adapters (React/Solid), state is accessed from `batcher.state`
27
28## Example
29
30```ts
31const batcher = new Batcher<number>(
32 (items) => console.log('Processing batch:', items),
33 {
34 maxSize: 5,
35 wait: 2000,
36 onExecute: (batch, batcher) => console.log('Batch executed:', batch)
37 }
38);
39
40batcher.addItem(1);
41batcher.addItem(2);
42// After 2 seconds or when 5 items are added, whichever comes first,
43// the batch will be processed
44// batcher.flush() // manually trigger a batch
45```
46
47## Type Parameters
48
49### TValue
50
51`TValue`
52
53## Constructors
54
55### Constructor
56
57```ts
58new Batcher<TValue>(fn, initialOptions): Batcher<TValue>;
59```
60
61Defined in: [batcher.ts:153](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L153)
62
63#### Parameters
64
65##### fn
66
67(`items`) => `void`
68
69##### initialOptions
70
71[`BatcherOptions`](../interfaces/BatcherOptions.md)\<`TValue`\>
72
73#### Returns
74
75`Batcher`\<`TValue`\>
76
77## Properties
78
79### fn
80
81```ts
82fn: (items) => void;
83```
84
85Defined in: [batcher.ts:154](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L154)
86
87#### Parameters
88
89##### items
90
91`TValue`[]
92
93#### Returns
94
95`void`
96
97***
98
99### key
100
101```ts
102key: string | undefined;
103```
104
105Defined in: [batcher.ts:149](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L149)
106
107***
108
109### options
110
111```ts
112options: BatcherOptionsWithOptionalCallbacks<TValue>;
113```
114
115Defined in: [batcher.ts:150](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L150)
116
117***
118
119### store
120
121```ts
122readonly store: Store<Readonly<BatcherState<TValue>>>;
123```
124
125Defined in: [batcher.ts:146](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L146)
126
127## Methods
128
129### addItem()
130
131```ts
132addItem(item): void;
133```
134
135Defined in: [batcher.ts:211](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L211)
136
137Adds an item to the batcher
138If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
139
140#### Parameters
141
142##### item
143
144`TValue`
145
146#### Returns
147
148`void`
149
150***
151
152### cancel()
153
154```ts
155cancel(): void;
156```
157
158Defined in: [batcher.ts:289](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L289)
159
160Cancels any pending execution that was scheduled.
161Does NOT clear out the items.
162
163#### Returns
164
165`void`
166
167***
168
169### clear()
170
171```ts
172clear(): void;
173```
174
175Defined in: [batcher.ts:281](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L281)
176
177Removes all items from the batcher
178
179#### Returns
180
181`void`
182
183***
184
185### flush()
186
187```ts
188flush(): void;
189```
190
191Defined in: [batcher.ts:259](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L259)
192
193Processes the current batch of items immediately
194
195#### Returns
196
197`void`
198
199***
200
201### peekAllItems()
202
203```ts
204peekAllItems(): TValue[];
205```
206
207Defined in: [batcher.ts:267](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L267)
208
209Returns a copy of all items in the batcher
210
211#### Returns
212
213`TValue`[]
214
215***
216
217### reset()
218
219```ts
220reset(): void;
221```
222
223Defined in: [batcher.ts:297](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L297)
224
225Resets the batcher state to its default values
226
227#### Returns
228
229`void`
230
231***
232
233### setOptions()
234
235```ts
236setOptions(newOptions): void;
237```
238
239Defined in: [batcher.ts:180](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L180)
240
241Updates the batcher options
242
243#### Parameters
244
245##### newOptions
246
247`Partial`\<[`BatcherOptions`](../interfaces/BatcherOptions.md)\<`TValue`\>\>
248
249#### Returns
250
251`void`