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

async-batching.md

214 lines8.1 KB

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 )
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)
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 },
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 }),
189​
190console.log(
191 batcher.state.size,
192 batcher.state.isExecuting,
193 batcher.state.failedItems,
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.