Open History to see the last commit
1---
2id: AsyncBatcher
3title: AsyncBatcher
4---
5
6Defined in: [async-batcher.ts:265](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L265)
7
8A class that collects items and processes them in batches asynchronously.
9
10Async vs Sync Versions:
11The async version provides advanced features over the sync Batcher:
12- Returns promises that can be awaited for batch results
13- Built-in retry support via AsyncRetryer integration
14- Abort support to cancel in-flight batch executions
15- Cancel support to prevent pending batches from starting
16- Comprehensive error handling with onError callbacks and throwOnError control
17- Detailed execution tracking (success/error/settle counts)
18
19The sync Batcher is lighter weight and simpler when you don't need async features,
20return values, or execution control.
21
22What is Batching?
23Batching is a technique for grouping multiple operations together to be processed as a single unit.
24
25The AsyncBatcher provides a flexible way to implement async batching with configurable:
26- Maximum batch size (number of items per batch)
27- Time-based batching (process after X milliseconds)
28- Custom batch processing logic via getShouldExecute
29- Event callbacks for monitoring batch operations
30- Error handling for failed batch operations
31
32Error Handling:
33- If an `onError` handler is provided, it will be called with the error, the batch of items that failed, and batcher instance
34- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
35- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
36- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
37- The error state can be checked using the AsyncBatcher instance
38
39State Management:
40- Uses TanStack Store for reactive state management
41- Use `initialState` to provide initial state values when creating the async batcher
42- Use `onSuccess` callback to react to successful batch execution and implement custom logic
43- Use `onError` callback to react to batch execution errors and implement custom error handling
44- Use `onSettled` callback to react to batch execution completion (success or error) and implement custom logic
45- Use `onExecute` callback to react to batch execution and implement custom logic
46- Use `onItemsChange` callback to react to items being added or removed from the batcher
47- The state includes total items processed, success/error counts, and execution status
48- State can be accessed via `asyncBatcher.store.state` when using the class directly
49- When using framework adapters (React/Solid), state is accessed from `asyncBatcher.state`
50
51## Example
52
53```ts
54const batcher = new AsyncBatcher<number>(
55 async (items) => {
56 const result = await processItems(items);
57 console.log('Processing batch:', items);
58 return result;
59 },
60 {
61 maxSize: 5,
62 wait: 2000,
63 onSuccess: (result) => console.log('Batch succeeded:', result),
64 onError: (error) => console.error('Batch failed:', error)
65 }
66);
67
68batcher.addItem(1);
69batcher.addItem(2);
70// After 2 seconds or when 5 items are added, whichever comes first,
71// the batch will be processed and the result will be available
72// batcher.execute() // manually trigger a batch
73```
74
75## Type Parameters
76
77### TValue
78
79`TValue`
80
81## Constructors
82
83### Constructor
84
85```ts
86new AsyncBatcher<TValue>(fn, initialOptions): AsyncBatcher<TValue>;
87```
88
89Defined in: [async-batcher.ts:277](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L277)
90
91#### Parameters
92
93##### fn
94
95(`items`) => `Promise`\<`any`\>
96
97##### initialOptions
98
99[`AsyncBatcherOptions`](../interfaces/AsyncBatcherOptions.md)\<`TValue`\>
100
101#### Returns
102
103`AsyncBatcher`\<`TValue`\>
104
105## Properties
106
107### asyncRetryers
108
109```ts
110asyncRetryers: Map<number, AsyncRetryer<(items) => Promise<any>>>;
111```
112
113Defined in: [async-batcher.ts:271](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L271)
114
115***
116
117### fn
118
119```ts
120fn: (items) => Promise<any>;
121```
122
123Defined in: [async-batcher.ts:278](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L278)
124
125#### Parameters
126
127##### items
128
129`TValue`[]
130
131#### Returns
132
133`Promise`\<`any`\>
134
135***
136
137### key
138
139```ts
140key: string | undefined;
141```
142
143Defined in: [async-batcher.ts:269](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L269)
144
145***
146
147### options
148
149```ts
150options: AsyncBatcherOptionsWithOptionalCallbacks<TValue>;
151```
152
153Defined in: [async-batcher.ts:270](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L270)
154
155***
156
157### store
158
159```ts
160readonly store: Store<Readonly<AsyncBatcherState<TValue>>>;
161```
162
163Defined in: [async-batcher.ts:266](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L266)
164
165## Methods
166
167### abort()
168
169```ts
170abort(): void;
171```
172
173Defined in: [async-batcher.ts:494](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L494)
174
175Aborts all ongoing executions with the internal abort controllers.
176Does NOT cancel any pending execution that have not started yet.
177Does NOT clear out the items.
178
179#### Returns
180
181`void`
182
183***
184
185### addItem()
186
187```ts
188addItem(item): Promise<any>;
189```
190
191Defined in: [async-batcher.ts:346](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L346)
192
193Adds an item to the async batcher
194If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
195
196#### Parameters
197
198##### item
199
200`TValue`
201
202#### Returns
203
204`Promise`\<`any`\>
205
206The result from the batch function, or undefined if an error occurred and was handled by onError
207
208#### Throws
209
210The error from the batch function if no onError handler is configured or throwOnError is true
211
212***
213
214### cancel()
215
216```ts
217cancel(): void;
218```
219
220Defined in: [async-batcher.ts:507](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L507)
221
222Cancels any pending execution that have not started yet.
223Does NOT abort any execution already in progress.
224Does NOT clear out the items.
225
226#### Returns
227
228`void`
229
230***
231
232### clear()
233
234```ts
235clear(): void;
236```
237
238Defined in: [async-batcher.ts:455](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L455)
239
240Removes all items from the async batcher
241
242#### Returns
243
244`void`
245
246***
247
248### flush()
249
250```ts
251flush(): Promise<any>;
252```
253
254Defined in: [async-batcher.ts:429](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L429)
255
256Processes the current batch of items immediately
257
258#### Returns
259
260`Promise`\<`any`\>
261
262***
263
264### getAbortSignal()
265
266```ts
267getAbortSignal(executionCount?): AbortSignal | null;
268```
269
270Defined in: [async-batcher.ts:483](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L483)
271
272Returns the AbortSignal for a specific execution.
273If no executionCount is provided, returns the signal for the most recent execution.
274Returns null if no execution is found or not currently executing.
275
276#### Parameters
277
278##### executionCount?
279
280`number`
281
282Optional specific execution to get signal for
283
284#### Returns
285
286`AbortSignal` \| `null`
287
288#### Example
289
290```typescript
291const batcher = new AsyncBatcher(
292 async (items: string[]) => {
293 const signal = batcher.getAbortSignal()
294 if (signal) {
295 const response = await fetch('/api/batch', {
296 method: 'POST',
297 body: JSON.stringify(items),
298 signal
299 })
300 return response.json()
301 }
302 },
303 { maxSize: 10, wait: 100 }
304)
305```
306
307***
308
309### peekAllItems()
310
311```ts
312peekAllItems(): TValue[];
313```
314
315Defined in: [async-batcher.ts:437](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L437)
316
317Returns a copy of all items in the async batcher
318
319#### Returns
320
321`TValue`[]
322
323***
324
325### peekFailedItems()
326
327```ts
328peekFailedItems(): TValue[];
329```
330
331Defined in: [async-batcher.ts:441](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L441)
332
333#### Returns
334
335`TValue`[]
336
337***
338
339### reset()
340
341```ts
342reset(): void;
343```
344
345Defined in: [async-batcher.ts:517](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L517)
346
347Resets the async batcher state to its default values
348
349#### Returns
350
351`void`
352
353***
354
355### setOptions()
356
357```ts
358setOptions(newOptions): void;
359```
360
361Defined in: [async-batcher.ts:305](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L305)
362
363Updates the async batcher options
364
365#### Parameters
366
367##### newOptions
368
369`Partial`\<[`AsyncBatcherOptions`](../interfaces/AsyncBatcherOptions.md)\<`TValue`\>\>
370
371#### Returns
372
373`void`