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

UseAsyncBatcher.md

165 lines5.1 KB

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```