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

useAsyncBatcher.md

105 lines3.9 KB

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 }),
103utility.addItem('item')
104// Selected state: utility.state.value.size
105```