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

Batcher.md

251 lines4.7 KB

1---
2id: Batcher
3title: Batcher
4---
5​
6Defined in: [batcher.ts:145](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L145)
7​
8A class that collects items and processes them in batches.
9​
10Batching is a technique for grouping multiple operations together to be processed as a single unit.
11This synchronous version is lighter weight and often all you need - upgrade to AsyncBatcher when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
12​
13The Batcher provides a flexible way to implement batching with configurable:
14- Maximum batch size (number of items per batch)
15- Time-based batching (process after X milliseconds)
16- Custom batch processing logic via getShouldExecute
17- Event callbacks for monitoring batch operations
18​
19State Management:
20- Uses TanStack Store for reactive state management
21- Use `initialState` to provide initial state values when creating the batcher
22- Use `onExecute` callback to react to batch execution and implement custom logic
23- Use `onItemsChange` callback to react to items being added or removed from the batcher
24- The state includes batch execution count, total items processed, items, and running status
25- State can be accessed via `batcher.store.state` when using the class directly
26- When using framework adapters (React/Solid), state is accessed from `batcher.state`
27​
28## Example
29​
30```ts
31const batcher = new Batcher<number>(
32 (items) => console.log('Processing batch:', items),
33 {
34 maxSize: 5,
35 wait: 2000,
36 onExecute: (batch, batcher) => console.log('Batch executed:', batch)
37 }
38);
39​
40batcher.addItem(1);
41batcher.addItem(2);
42// After 2 seconds or when 5 items are added, whichever comes first,
43// the batch will be processed
44// batcher.flush() // manually trigger a batch
45```
46​
47## Type Parameters
48​
49### TValue
50​
51`TValue`
52​
53## Constructors
54​
55### Constructor
56​
57```ts
58new Batcher<TValue>(fn, initialOptions): Batcher<TValue>;
59```
60​
61Defined in: [batcher.ts:153](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L153)
62​
63#### Parameters
64​
65##### fn
66​
67(`items`) => `void`
68​
69##### initialOptions
70​
71[`BatcherOptions`](../interfaces/BatcherOptions.md)\<`TValue`\>
72​
73#### Returns
74​
75`Batcher`\<`TValue`\>
76​
77## Properties
78​
79### fn
80​
81```ts
82fn: (items) => void;
83```
84​
85Defined in: [batcher.ts:154](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L154)
86​
87#### Parameters
88​
89##### items
90​
91`TValue`[]
92​
93#### Returns
94​
95`void`
96​
97***
98​
99### key
100​
101```ts
102key: string | undefined;
103```
104​
105Defined in: [batcher.ts:149](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L149)
106​
107***
108​
109### options
110​
111```ts
112options: BatcherOptionsWithOptionalCallbacks<TValue>;
113```
114​
115Defined in: [batcher.ts:150](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L150)
116​
117***
118​
119### store
120​
121```ts
122readonly store: Store<Readonly<BatcherState<TValue>>>;
123```
124​
125Defined in: [batcher.ts:146](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L146)
126​
127## Methods
128​
129### addItem()
130​
131```ts
132addItem(item): void;
133```
134​
135Defined in: [batcher.ts:211](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L211)
136​
137Adds an item to the batcher
138If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
139​
140#### Parameters
141​
142##### item
143​
144`TValue`
145​
146#### Returns
147​
148`void`
149​
150***
151​
152### cancel()
153​
154```ts
155cancel(): void;
156```
157​
158Defined in: [batcher.ts:289](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L289)
159​
160Cancels any pending execution that was scheduled.
161Does NOT clear out the items.
162​
163#### Returns
164​
165`void`
166​
167***
168​
169### clear()
170​
171```ts
172clear(): void;
173```
174​
175Defined in: [batcher.ts:281](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L281)
176​
177Removes all items from the batcher
178​
179#### Returns
180​
181`void`
182​
183***
184​
185### flush()
186​
187```ts
188flush(): void;
189```
190​
191Defined in: [batcher.ts:259](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L259)
192​
193Processes the current batch of items immediately
194​
195#### Returns
196​
197`void`
198​
199***
200​
201### peekAllItems()
202​
203```ts
204peekAllItems(): TValue[];
205```
206​
207Defined in: [batcher.ts:267](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L267)
208​
209Returns a copy of all items in the batcher
210​
211#### Returns
212​
213`TValue`[]
214​
215***
216​
217### reset()
218​
219```ts
220reset(): void;
221```
222​
223Defined in: [batcher.ts:297](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L297)
224​
225Resets the batcher state to its default values
226​
227#### Returns
228​
229`void`
230​
231***
232​
233### setOptions()
234​
235```ts
236setOptions(newOptions): void;
237```
238​
239Defined in: [batcher.ts:180](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/batcher.ts#L180)
240​
241Updates the batcher options
242​
243#### Parameters
244​
245##### newOptions
246​
247`Partial`\<[`BatcherOptions`](../interfaces/BatcherOptions.md)\<`TValue`\>\>
248​
249#### Returns
250​
251`void`