Open History to see the last commit
1---
2id: useAsyncBatcher
3title: useAsyncBatcher
4---
5
6```ts
7function useAsyncBatcher<TValue, TSelected>(
8 fn,
9 options?,
10selector?): VueAsyncBatcher<TValue, TSelected>;
11```
12
13Defined in: [async-batcher/useAsyncBatcher.ts:96](https://github.com/TanStack/pacer/blob/main/packages/vue-pacer/src/async-batcher/useAsyncBatcher.ts#L96)
14
15Creates and retains the AsyncBatcher for its Vue owner.
16
17Collects items and processes them together when maxSize, wait, or getShouldExecute triggers a batch. Use addItem to accumulate work and flush to process a partial batch.
18
19The callback may return a Promise. Core result, error, retry, and abort behavior is preserved.
20Use onSuccess, onError, and onSettled for execution outcomes.
21
22## State and subscriptions
23
24Pass a selector to track only the state consumed by the owner. The default selection is {},
25so utility state changes do not update the owner unless it opts in. Selection uses shallow
26comparison. The raw store remains available for additional subscriptions.
27Read selected state through utility.state.value in JavaScript. Vue templates unwrap refs.
28Use utility.Subscribe with a scoped slot to select state in a child without updating the owner.
29
30Available state fields:
31
32- `errorCount`: Number of batch executions that have resulted in errors
33- `executionCount`: Number of batch executions that have been started
34- `failedItems`: Array of items that failed during batch processing
35- `isEmpty`: Whether the batcher has no items to process (items array is empty)
36- `isExecuting`: Whether a batch is currently being processed asynchronously
37- `isPending`: Whether the batcher is waiting for the timeout to trigger batch processing
38- `items`: Array of items currently queued for batch processing
39- `lastResult`: The result from the most recent batch execution
40- `settleCount`: Number of batch executions that have completed (either successfully or with errors)
41- `size`: Number of items currently in the batch queue
42- `status`: Current processing status - 'idle' when not processing, 'pending' when waiting for timeout, 'executing' when processing, 'populated' when items are present, but no wait is configured
43- `successCount`: Number of batch executions that have completed successfully
44- `totalItemsFailed`: Total number of items that have failed processing across all batches
45- `totalItemsProcessed`: Total number of items that have been processed across all batches
46
47## Options and ownership
48
49Pass an options object with property getters or a factory. Top-level properties are read
50reactively; function-valued core options remain callbacks. Local options override provider
51defaults. Updates retain the utility, its store, counters, and pending work.
52Disposing the component or effect scope calls cancel() and abort().
53onUnmount replaces default cleanup and receives the same adapter instance. A custom callback
54must perform all required cleanup. Use flush() where supported to finish pending work.
55
56## Type Parameters
57
58### TValue
59
60`TValue`
61
62### TSelected
63
64`TSelected` = \{
65\}
66
67## Parameters
68
69### fn
70
71(`items`) => `Promise`\<`any`\>
72
73Function executed by the utility.
74
75### options?
76
77[`VuePacerOptions`](../type-aliases/VuePacerOptions.md)\<[`VueAsyncBatcherOptions`](../interfaces/VueAsyncBatcherOptions.md)\<`TValue`, `TSelected`\>\> = `{}`
78
79Core options or a reactive factory, plus an optional onUnmount callback.
80
81### selector?
82
83(`state`) => `TSelected`
84
85Selects state that updates the owner. Omit to leave selected state empty.
86
87## Returns
88
89[`VueAsyncBatcher`](../interfaces/VueAsyncBatcher.md)\<`TValue`, `TSelected`\>
90
91The retained utility instance with selected state and child subscriptions.
92
93## Example
94
95```ts
96import { useAsyncBatcher } from '@tanstack/vue-pacer'
97
98const utility = useAsyncBatcher(
99 async (items: Array<string>) => { console.log(items) },
100 { maxSize: 5, wait: 1000 },
101 (state) => ({ size: state.size }),
102)
103utility.addItem('item')
104// Selected state: utility.state.value.size
105```