Open History to see the last commit
1---
2title: React Async Batching Guide
3id: async-batching
4---
5
6Async batching keeps the collection and trigger behavior described in the [Batching Guide](./batching.md), while adding Promise results, retries, error callbacks, failed-item tracking, and control over in-flight work.
7
8Use it when one async operation should process several collected items together. Use an [Async Queue](./async-queuing.md) when each item needs its own execution or when you need to limit concurrency.
9
10## How async batching works
11
12Items collect until any configured trigger fires:
13
14```text
15add A ─── add B ─── add C
16 │ │ │
17 └─ wait reset └─ maxSize reached
18 │
19 └─ execute [A, B, C]
20```
21
22A batch executes when:
23
24- its length reaches `maxSize`,
25- `getShouldExecute(items, batcher)` returns `true`, or
26- no new item arrives for `wait` milliseconds.
27
28Both `maxSize` and `wait` default to `Infinity`, so configure at least one trigger or call `flush()` manually. The wait timer restarts on every addition. It measures a quiet period, not a maximum age for the oldest item.
29
30## Choose an API
31
32- `useAsyncBatchedCallback` for adding items
33- `useAsyncBatcher` for flush, failed items, and selected execution state
34
35## React example
36
37```tsx
38import { useAsyncBatcher } from '@tanstack/react-pacer'
39
40function AnalyticsButton() {
41 const batcher = useAsyncBatcher(
42 sendEvents,
43 { maxSize: 20, wait: 1000 },
44 (state) => ({
45 size: state.size,
46 isExecuting: state.isExecuting,
47 }),
48 )
49
50 return (
51 <button onClick={() => void batcher.addItem({ type: 'click' })}>
52 Track ({batcher.state.size} pending)
53 </button>
54 )
55}
56```
57
58The focused snippets later in this guide use `useAsyncBatcher` and assume they run inside a component or another hook.
59
60## Promise results
61
62`flush()` returns the batch function's result and is the clearest way to await a specific batch.
63
64`addItem()` also returns a Promise, but it should not be treated as an individual item's result receipt:
65
66- If that addition reaches `maxSize` or satisfies `getShouldExecute`, its Promise owns the triggered execution and resolves with the batch result.
67- If it only schedules the wait timer, its Promise resolves without the later batch result.
68- Another addition may reset the timer and change which items execute together.
69
70Use `onSuccess`, `onError`, and `onSettled` when all additions need to observe the eventual batch outcome.
71
72## Batch boundaries and overlapping work
73
74The batcher copies and clears the current items before calling the async function. Items added while that function is active collect in a new batch:
75
76```text
77execute [A, B] ───────────────── finish
78 add C ─── add D ─── execute [C, D] ─── finish
79```
80
81If the second batch's trigger fires before the first finishes, both batch functions can overlap. `useAsyncBatcher` does not have a concurrency option. Serialize batch executions outside the batcher or send the completed batches through an async queue when overlap is unsafe.
82
83## Errors and failed items
84
85Async batchers provide these callbacks:
86
87- `onSuccess(result, batch, batcher)` after success.
88- `onError(error, batch, batcher)` after the batch's retries fail.
89- `onSettled(batch, batcher)` after either outcome.
90- `onItemsChange(batcher)` when items are added or removed for execution.
91
92Without `onError`, `throwOnError` defaults to `true`, so `flush()` or a size-triggering `addItem()` rejects on failure. Providing `onError` changes that default to `false`; the Promise then resolves with `undefined`.
93
94Items are removed from the pending collection before execution. A failed batch is not automatically requeued. Its items are added to `failedItems` and are available through `peekFailedItems()` until `clear()` or a later execution clears that collection.
95
96```ts
97const failed = batcher.peekFailedItems()
98for (const item of failed) {
99 saveForManualRecovery(item)
100}
101```
102
103For non-idempotent operations, verify the server outcome before resubmitting a failed batch.
104
105## Retrying batches
106
107Configure retries for each batch execution with `asyncRetryerOptions`:
108
109```ts
110const batcher = useAsyncBatcher(sendEvents, {
111 maxSize: 20,
112 wait: 1000,
113 asyncRetryerOptions: {
114 maxAttempts: 3,
115 backoff: 'exponential',
116 baseWait: 500,
117 jitter: 0.2,
118 },
119})
120```
121
122`maxAttempts` includes the first attempt, and every retry receives the same copied batch. See the [Async Retrying Guide](./async-retrying.md) before retrying operations with side effects.
123
124## Flushing, canceling, and clearing
125
126- `flush()` clears the pending timer and immediately executes the current items.
127- `cancel()` clears the pending timer but keeps the collected items.
128- `clear()` removes collected items and failed items, but does not clear a scheduled timer.
129- `peekAllItems()` returns a copy of the currently collected items.
130
131Because `clear()` leaves the timer in place, use `cancel()` followed by `clear()` when no empty timer should remain:
132
133```ts
134batcher.cancel()
135batcher.clear()
136```
137
138The batch function is not called when an eventual timer or `flush()` finds no items.
139
140## Aborting active work
141
142`abort()` aborts active retryers. It does not cancel a pending batch or remove collected items. Pass the batcher's signal to the underlying API for cancellation to propagate:
143
144```ts
145const batcher = useAsyncBatcher(
146 async (events: Array<AnalyticsEvent>) => {
147 return fetch('/api/analytics/batch', {
148 method: 'POST',
149 body: JSON.stringify(events),
150 signal: batcher.getAbortSignal() ?? undefined,
151 })
152 },
153 { maxSize: 20, wait: 1000 },
154)
155
156batcher.abort()
157```
158
159When executions overlap, pass an `executionCount` to `getAbortSignal()` when you need a specific execution's signal.
160
161### Resetting safely
162
163`reset()` restores default state, but it does not clear a scheduled timer or guarantee that active underlying work stops. Use the lifecycle methods first when a complete cleanup is required:
164
165```ts
166batcher.cancel()
167batcher.abort()
168batcher.reset()
169```
170
171## React lifecycle
172
173The adapter cancels the pending wait timer and aborts active work when its owner is destroyed. Providing `onUnmount` replaces that default cleanup, so a custom callback must perform every required lifecycle action. When custom cleanup flushes work, remember that user callbacks can run while the component is being destroyed.
174
175## Configuration and reactive state
176
177The adapter subscribes only to the state returned by the selector argument. Without a selector, the adapter state is empty. Create the utility at the top level of a component or another hook and select only fields used by the view:
178
179```ts
180const batcher = useAsyncBatcher(
181 sendEvents,
182 { maxSize: 20, wait: 1000 },
183 (state) => ({
184 size: state.size,
185 isExecuting: state.isExecuting,
186 failedItems: state.failedItems,
187 }),
188)
189
190console.log(
191 batcher.state.size,
192 batcher.state.isExecuting,
193 batcher.state.failedItems,
194)
195```
196
197Option functions and lifecycle callbacks receive the underlying public utility instance. The `.store.state` reads inside those callbacks in the examples above are supported. Rendering code should read the selected adapter state shown here.
198
199`wait` may be a number or a function that receives the batcher instance. `setOptions()` merges new options, and `asyncBatcherOptions()` creates reusable, type-checked option objects.
200
201Do not use `started` to pause a batcher. It is currently a no-op, so every `addItem()` call evaluates the configured triggers.
202
203To restore selected state that your app has persisted, pass a partial snapshot through `initialState`. It is merged with the defaults. Restore only durable fields. Pending timers and active executions are not restored.
204
205Common state includes:
206
207- `items`, `size`, and `isPending`: The next batch and its timer state.
208- `isExecuting`: Whether a batch is reported as executing.
209- `lastResult`: The most recent successful result.
210- `failedItems` and `totalItemsFailed`: Failure tracking.
211- `successCount`, `errorCount`, and `settleCount`: Batch outcome counts.
212- `totalItemsProcessed`: Items in successful batch executions.
213
214See the [React API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.