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

batching.md

225 lines7.2 KB

1---
2title: React Batching Guide
3id: batching
4---
5​
6Batching collects items and passes them to one function as an array. A batch can run when it reaches a configured size, after no new items arrive for a configured wait, or when custom logic says it is ready.
7​
8Batching reduces the number of operations by processing several items together. Unlike queuing, it does not call the wrapped function once for each item.
9​
10## How batching works
11​
12```text
13Batching (process every 3 items or after 2 quiet ticks)
14Timeline: [1 second per tick]
15Calls: ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️
16Batch: [ABC] [] [DE] [] [FGH] []
17Executed: ✅ ✅ ✅
18 [======================================================]
19 ^ Items are grouped and processed together
20​
21 [Size reached] [Wait elapsed] [Size reached]
22```
23​
24Each execution receives a copy of the items currently collected. The batcher clears those items before calling the wrapped function.
25​
26## When to use batching
27​
28Choose batching when:
29​
30- A bulk operation is more efficient than individual operations.
31- Network requests, database writes, or analytics events can be grouped.
32- A maximum batch size or quiet-period trigger matches the workload.
33- Individual item results are unnecessary.
34​
35Choose another utility when:
36​
37- Every item should run individually and in order. Use [queuing](./queuing.md).
38- Only the latest value matters. Use [debouncing](./debouncing.md).
39- Calls should be spaced over time. Use [throttling](./throttling.md).
40- Batch processing returns a Promise or needs retries and abort support. Use [async batching](./async-batching.md).
41​
42## Choose an API
43​
44- `useBatchedCallback` for a stable item-adder
45- `useBatcher` for flush, cancel, collected items, and selected state
46​
47Use the callback API when adding items is all the component needs. Use the instance API for `flush()`, `cancel()`, collected items, selected state, and dynamic options.
48​
49## React example
50​
51```tsx
52import { useBatcher } from '@tanstack/react-pacer'
53​
54function AnalyticsButton() {
55 const batcher = useBatcher(
56 sendEvents,
57 { maxSize: 20, wait: 1000 },
58 (state) => ({
59 size: state.size,
60 }),
61 )
62​
63 return (
64 <button onClick={() => batcher.addItem({ type: 'click' })}>
65 Track ({batcher.state.size} pending)
66 </button>
67 )
69```
70​
71The focused snippets later in this guide use `useBatcher` and assume they run inside a component or another hook.
72​
73## Choosing batch triggers
74​
75### Batch size
76​
77`maxSize` executes the batch as soon as the number of collected items reaches the limit.
78​
79```ts
80const batcher = useBatcher(processBatch, {
81 maxSize: 100,
82})
83```
84​
85The default is `Infinity`, so a size trigger is disabled unless you provide one.
86​
87### Wait time
88​
89`wait` executes a batch after no new items arrive for the configured duration. Every added item restarts the timer.
90​
91```ts
92const batcher = useBatcher(processBatch, {
93 wait: 1000,
94})
95```
96​
97The default is `Infinity`, so a time trigger is disabled unless you provide one. A continuous stream of items can keep restarting the timer. Combine `wait` with `maxSize` when a batch must eventually run under continuous traffic.
98​
99### Custom trigger
100​
101`getShouldExecute` runs after each item is added. Return `true` to execute the current batch immediately.
102​
103```ts
104const batcher = useBatcher<number>(processBatch, {
105 getShouldExecute: (items) => items.includes(0),
106})
107​
108batcher.addItem(4)
109batcher.addItem(0) // Executes [4, 0].
110```
111​
112If several triggers are configured, the first one reached executes the batch.
113​
114## Controlling collected items
115​
116### Flush
117​
118`flush()` clears the pending timer and executes all currently collected items. It does nothing when the batch is empty.
119​
120```ts
121batcher.addItem('event-1')
122batcher.addItem('event-2')
123batcher.flush()
124```
125​
126### Cancel
127​
128`cancel()` clears the pending timer but keeps the collected items. A later item can schedule a new timer, or you can call `flush()`.
129​
130```ts
131batcher.cancel()
132console.log(batcher.peekAllItems()) // Items are still present.
133```
134​
135### Clear
136​
137`clear()` removes all collected items. It does not clear the timer itself, although that timer has no items to execute unless more items are added.
138​
139```ts
140batcher.clear()
141```
142​
143### Reset
144​
145`reset()` restores batch state and counters to their defaults. It does not cancel an already scheduled timer. Call `cancel()` before `reset()` when pending work must be discarded.
146​
147```ts
148batcher.cancel()
149batcher.reset()
150```
151​
152## Configuring and observing batches
153​
154Use `setOptions()` to update future trigger behavior:
155​
156```ts
157batcher.setOptions({
158 maxSize: 20,
159 wait: 500,
160})
161```
162​
163Changing `wait` does not reschedule an existing timer. The next `addItem()` call replaces that timer using the current value.
164​
165The `wait` option may be a function that receives the batcher instance:
166​
167```ts
168const batcher = useBatcher(processBatch, {
169 wait: (batcher) => (batcher.store.state.size > 10 ? 100 : 500),
170})
171```
172​
173Use `onItemsChange` to observe collection changes and `onExecute` to observe completed batch calls:
174​
175```ts
176const batcher = useBatcher(processBatch, {
177 maxSize: 10,
178 onItemsChange: (batcher) => {
179 console.log('Collected:', batcher.store.state.size)
180 },
181 onExecute: (items, batcher) => {
182 console.log('Processed:', items)
183 console.log('Batches:', batcher.store.state.executionCount)
184 },
185})
186```
187​
188Do not use `started` to pause a batcher. It is currently a no-op, so every `addItem()` call evaluates the configured triggers.
189​
190## React lifecycle
191​
192The adapter cancels the pending wait timer while retaining collected items 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.
193​
194## Reactive state
195​
196The 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:
197​
198```ts
199const batcher = useBatcher(
200 processBatch,
201 { maxSize: 20, wait: 1000 },
202 (state) => ({
203 size: state.size,
204 isPending: state.isPending,
205 }),
207​
208console.log(batcher.state.size, batcher.state.isPending)
209```
210​
211Option 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.
212​
213To 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 are not restored.
214​
215Commonly useful state includes:
216​
217- `items`: Items currently collected.
218- `size`: Number of collected items.
219- `isEmpty`: Whether the batch is empty.
220- `isPending`: Whether a wait timer is active.
221- `executionCount`: Completed batch executions.
222- `totalItemsProcessed`: Items passed to completed batch executions.
223- `status`: `'idle'` or `'pending'`.
224​
225See the [React API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.