Open History to see the last commit
1---
2id: UseAsyncBatcher
3title: UseAsyncBatcher
4---
5
6Defined in: [packages/ember-pacer/src/async-batcher/useAsyncBatcher.ts:100](https://github.com/TanStack/pacer/blob/main/packages/ember-pacer/src/async-batcher/useAsyncBatcher.ts#L100)
7
8Creates and retains the AsyncBatcher for its Ember owner.
9
10Collects 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.
11
12The callback may return a Promise. Core result, error, retry, and abort behavior is preserved.
13Use onSuccess, onError, and onSettled for execution outcomes.
14
15## State and subscriptions
16
17Pass a selector to track only the state consumed by the owner. The default selection is {},
18so utility state changes do not update the owner unless it opts in. Selection uses shallow
19comparison. The raw store remains available for additional subscriptions.
20The selector is the second positional argument. Read utility.state from the template.
21The contextual utility.Subscribe helper selects state for a child template.
22
23Available state fields:
24
25- `errorCount`: Number of batch executions that have resulted in errors
26- `executionCount`: Number of batch executions that have been started
27- `failedItems`: Array of items that failed during batch processing
28- `isEmpty`: Whether the batcher has no items to process (items array is empty)
29- `isExecuting`: Whether a batch is currently being processed asynchronously
30- `isPending`: Whether the batcher is waiting for the timeout to trigger batch processing
31- `items`: Array of items currently queued for batch processing
32- `lastResult`: The result from the most recent batch execution
33- `settleCount`: Number of batch executions that have completed (either successfully or with errors)
34- `size`: Number of items currently in the batch queue
35- `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
36- `successCount`: Number of batch executions that have completed successfully
37- `totalItemsFailed`: Total number of items that have failed processing across all batches
38- `totalItemsProcessed`: Total number of items that have been processed across all batches
39
40## Options and ownership
41
42Tracked named arguments update options after rendering. createPacerScope supplies shared
43defaults through contextual helpers. Local named options override those defaults.
44Removing the helper invocation calls cancel() and abort().
45onUnmount replaces default cleanup and receives the same adapter instance. A custom callback
46must perform all required cleanup. Use flush() where supported to finish pending work.
47
48## Example
49
50```gts
51import { on } from '@ember/modifier'
52import { fn } from '@ember/helper'
53import { useAsyncBatcher } from '@tanstack/ember-pacer'
54import type { AsyncBatcherState } from '@tanstack/ember-pacer'
55
56const select = (state: AsyncBatcherState<string>) => ({ size: state.size })
57
58<template>
59 {{#let (useAsyncBatcher @process select maxSize=5 wait=1000) as |utility|}}
60 <button {{on "click" (fn utility.addItem "item")}}>Schedule</button>
61 <span>{{utility.state.size}}</span>
62 {{/let}}
63</template>
64```
65
66## Extends
67
68- `default`\<\{
69 `Args`: \{
70 `Named`: [`EmberAsyncBatcherOptions`](../interfaces/EmberAsyncBatcherOptions.md)\<`TValue`, `TSelected`\>;
71 `Positional`: \| \[(`items`) => `Promise`\<`any`\>\]
72 \| \[(`items`) => `Promise`\<`any`\>, (`state`) => `TSelected`\];
73 \};
74 `Return`: [`EmberAsyncBatcher`](../interfaces/EmberAsyncBatcher.md)\<`TValue`, `TSelected`\>;
75\}\>
76
77## Type Parameters
78
79### TValue
80
81`TValue`
82
83### TSelected
84
85`TSelected` = \{
86\}
87
88## Constructors
89
90### Constructor
91
92```ts
93new UseAsyncBatcher<TValue, TSelected>(owner?): UseAsyncBatcher;
94```
95
96Defined in: node\_modules/.pnpm/ember-source@7.3.0\_@glimmer+component@2.1.1\_supports-color@7.2.0\_\_supports-color@7.2.0/node\_modules/ember-source/types/stable/@ember/object/index.d.ts:28
97
98#### Parameters
99
100##### owner?
101
102`Owner`
103
104#### Returns
105
106`UseAsyncBatcher`
107
108#### Inherited from
109
110```ts
111Helper<{
112 Args: {
113 Positional:
114 | [fn: (items: Array<TValue>) => Promise<any>]
115 | [
116 fn: (items: Array<TValue>) => Promise<any>,
117 selector: (state: AsyncBatcherState<TValue>) => TSelected,
118 ]
119 Named: EmberAsyncBatcherOptions<TValue, TSelected>
120 }
121 Return: EmberAsyncBatcher<TValue, TSelected>
122}>.constructor
123```
124
125## Methods
126
127### compute()
128
129```ts
130compute(positional, options): EmberAsyncBatcher<TValue, TSelected>;
131```
132
133Defined in: [packages/ember-pacer/src/async-batcher/useAsyncBatcher.ts:120](https://github.com/TanStack/pacer/blob/main/packages/ember-pacer/src/async-batcher/useAsyncBatcher.ts#L120)
134
135Override this function when writing a class-based helper.
136
137#### Parameters
138
139##### positional
140
141\[(`items`) => `Promise`\<`any`\>, (`state`) => `TSelected`\]
142
143The positional arguments to the helper
144
145##### options
146
147[`EmberAsyncBatcherOptions`](../interfaces/EmberAsyncBatcherOptions.md)\<`TValue`, `TSelected`\>
148
149#### Returns
150
151[`EmberAsyncBatcher`](../interfaces/EmberAsyncBatcher.md)\<`TValue`, `TSelected`\>
152
153#### Method
154
155compute
156
157#### Since
158
1591.13.0
160
161#### Overrides
162
163```ts
164Helper.compute
165```