Open History to see the last commit
1---
2title: Lit 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- `createBatcher` for flush, cancel, collected items, and selected state
45
46Use the batcher's bound `addItem` method as an event handler. Keep the instance for `flush()`, `cancel()`, collected items, selected state, and dynamic options.
47
48## Lit example
49
50Pass the owning Lit controller host as the first argument. Disconnecting the host runs cleanup; reconnecting restores its subscription. The example imports application operations from `./api`.
51
52```ts
53import { LitElement, html } from 'lit'
54import { createBatcher } from '@tanstack/lit-pacer'
55import { sendEvents } from './api'
56
57class Example extends LitElement {
58 batcher = createBatcher(
59 this,
60 sendEvents,
61 { maxSize: 20, wait: 1000 },
62 (state) => ({ size: state.size, executionCount: state.executionCount }),
63 )
64
65 override render() {
66 return html`
67 <button @click=${() => void this.batcher.addItem({ type: 'click' })}>
68 Track
69 </button>
70 <output>${this.batcher.state.size}</output>
71 `
72 }
73}
74
75customElements.define('pacer-example', Example)
76```
77
78The focused snippets below create utilities in a Lit component constructor, where `this` is the controller host. Call their control methods from event handlers.
79
80## Choosing batch triggers
81
82### Batch size
83
84`maxSize` executes the batch as soon as the number of collected items reaches the limit.
85
86```ts
87const batcher = createBatcher(this, processBatch, {
88 maxSize: 100,
89})
90```
91
92The default is `Infinity`, so a size trigger is disabled unless you provide one.
93
94### Wait time
95
96`wait` executes a batch after no new items arrive for the configured duration. Every added item restarts the timer.
97
98```ts
99const batcher = createBatcher(this, processBatch, {
100 wait: 1000,
101})
102```
103
104The 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.
105
106### Custom trigger
107
108`getShouldExecute` runs after each item is added. Return `true` to execute the current batch immediately.
109
110```ts
111const batcher = createBatcher<number>(processBatch, {
112 getShouldExecute: (items) => items.includes(0),
113})
114
115batcher.addItem(4)
116batcher.addItem(0) // Executes [4, 0].
117```
118
119If several triggers are configured, the first one reached executes the batch.
120
121## Controlling collected items
122
123### Flush
124
125`flush()` clears the pending timer and executes all currently collected items. It does nothing when the batch is empty.
126
127```ts
128batcher.addItem('event-1')
129batcher.addItem('event-2')
130batcher.flush()
131```
132
133### Cancel
134
135`cancel()` clears the pending timer but keeps the collected items. A later item can schedule a new timer, or you can call `flush()`.
136
137```ts
138batcher.cancel()
139console.log(batcher.peekAllItems()) // Items are still present.
140```
141
142### Clear
143
144`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.
145
146```ts
147batcher.clear()
148```
149
150### Reset
151
152`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.
153
154```ts
155batcher.cancel()
156batcher.reset()
157```
158
159## Configuring and observing batches
160
161Use `setOptions()` to update future trigger behavior:
162
163```ts
164batcher.setOptions({
165 maxSize: 20,
166 wait: 500,
167})
168```
169
170Changing `wait` does not reschedule an existing timer. The next `addItem()` call replaces that timer using the current value.
171
172The `wait` option may be a function that receives the batcher instance:
173
174```ts
175const batcher = createBatcher(this, processBatch, {
176 wait: (batcher) => (batcher.store.state.size > 10 ? 100 : 500),
177})
178```
179
180Use `onItemsChange` to observe collection changes and `onExecute` to observe completed batch calls:
181
182```ts
183const batcher = createBatcher(this, processBatch, {
184 maxSize: 10,
185 onItemsChange: (batcher) => {
186 console.log('Collected:', batcher.store.state.size)
187 },
188 onExecute: (items, batcher) => {
189 console.log('Processed:', items)
190 console.log('Batches:', batcher.store.state.executionCount)
191 },
192})
193```
194
195Do not use `started` to pause a batcher. It is currently a no-op, so every `addItem()` call evaluates the configured triggers.
196
197## Lit lifecycle
198
199The 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.
200
201## Reactive state
202
203The adapter subscribes only to the state returned by the selector argument. Without a selector, the adapter state is empty. Create the utility on its owning host and select the fields used by `render()`. Store changes request a host update:
204
205```ts
206const batcher = createBatcher(
207 this,
208 processBatch,
209 { maxSize: 20, wait: 1000 },
210 (state) => ({
211 size: state.size,
212 isPending: state.isPending,
213 }),
214)
215
216console.log(batcher.state.size, batcher.state.isPending)
217```
218
219Use `utility.subscribe(childHost, selector)` for an independently subscribed child host. It returns a selected-state getter and cleans up when that child disconnects.
220
221Option 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.
222
223To 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.
224
225Commonly useful state includes:
226
227- `items`: Items currently collected.
228- `size`: Number of collected items.
229- `isEmpty`: Whether the batch is empty.
230- `isPending`: Whether a wait timer is active.
231- `executionCount`: Completed batch executions.
232- `totalItemsProcessed`: Items passed to completed batch executions.
233- `status`: `'idle'` or `'pending'`.
234
235See the [Lit API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.