Skip to content
Source
Sign inSign up
TanStack/pacer
Open History to see the last commit

AsyncBatcher.md

373 lines8.4 KB

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 }
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`