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

batching.md

235 lines7.8 KB

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 }
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 }),
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.