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

async-queuing.md

216 lines9.2 KB

1---
2title: React Async Queuing Guide
3id: async-queuing
4---
5​
6Async queuing keeps the ordering, capacity, priority, expiration, and start or stop controls described in the [Queuing Guide](./queuing.md). It adds controlled concurrency, Promise-aware processing, per-item retries, result callbacks, and control over active work.
7​
8Use it when every accepted item should eventually run, but only a limited number of async operations should be active at once. Use [Async Rate Limiting](./async-rate-limiting.md) when excess calls should be rejected by a time window instead of waiting.
9​
10## How async queuing works
11​
12Items move through two stages:
13​
14```text
15pending queue active work, concurrency: 2
16​
17[ A, B, C, D ] start A [ A ]
18[ B, C, D ] start B [ A, B ]
19[ B, C, D ] B finishes [ A ]
20[ C, D ] wait, C [ A, C ]
21```
22​
23`concurrency` limits automatically scheduled active items. Its default is `1`. With `wait: 0`, a free slot is filled after an item settles. With a positive `wait`, the queue waits that long after a settled item before checking for more work.
24​
25The queue controls start order. With concurrency greater than `1`, completion order depends on the work itself.
26​
27## Choose an API
28​
29- `useAsyncQueuedState` for reactive pending items
30- `useAsyncQueuer` for concurrency, ordering, and lifecycle control
31​
32## React example
33​
34```tsx
35import { useAsyncQueuedState } from '@tanstack/react-pacer'
36​
37function UploadQueue() {
38 const [pending, queue] = useAsyncQueuedState(
39 uploadFile,
40 { concurrency: 2 },
41 (state) => ({
42 items: state.items,
43 activeItems: state.activeItems,
44 }),
45 )
46​
47 return (
48 <button onClick={() => queue.addItem(nextFile())}>
49 Upload ({pending.length} waiting, {queue.state.activeItems.length} active)
50 </button>
51 )
53```
54​
55The focused snippets later in this guide use `useAsyncQueuer` and assume they run inside a component or another hook.
56​
57Pass `initialItems` when work is already available at creation time. The queue applies its normal insertion and capacity rules, and automatic processing can begin immediately unless `started: false` is set.
58​
59## Ordering pending items
60​
61The synchronous ordering rules still apply:
62​
63- The default adds at the back and reads from the front, producing FIFO order.
64- Set `getItemsFrom: 'back'` for LIFO order.
65- Set `addItemsTo` or pass a position to `addItem()` to control insertion.
66- Set `getPriority(item)` to order higher numeric priorities first.
67​
68Priority ordering takes precedence over front or back removal.
69​
70```ts
71const queue = useAsyncQueuer(processJob, {
72 started: false,
73 concurrency: 2,
74 getPriority: (job) => job.priority,
75})
76​
77queue.addItem({ id: 'low', priority: 1 })
78queue.addItem({ id: 'high', priority: 10 })
79queue.addItem({ id: 'medium', priority: 5 })
80queue.start()
81```
82​
83The high and medium jobs start first. Their relative completion order is not guaranteed.
84​
85## Capacity and rejection
86​
87`maxSize` limits pending items, not active items. Once an item starts, it leaves the pending queue and frees one pending slot. `addItem()` returns `false` and calls `onReject` when the pending queue is full. `undefined` is also rejected because the queue uses it internally to mean that no item is available.
88​
89```ts
90if (!queue.addItem(job)) {
91 saveForLater(job)
93```
94​
95Capacity does not provide backpressure by itself because callers do not await an open slot. Handle rejection explicitly when dropping an item is unacceptable.
96​
97## Results and errors
98​
99Automatically scheduled work runs in the background. Observe results through `onSuccess` or by selecting `lastResult` through the adapter state. Observe failures through `onError` and selected error counters.
100​
101For direct control, `execute()` removes and processes one pending item. Its Promise resolves with the item that was processed, not the wrapped function's result. The result is passed to `onSuccess` and stored as `lastResult`.
102​
103Without `onError`, `throwOnError` defaults to `true`. Background scheduling catches that rejection after updating callbacks and state so the queue can continue. A direct call to `execute()` or `flush()` can reject to its caller. Providing `onError` changes the default to `false`.
104​
105Callbacks include:
106​
107- `onSuccess(result, item, queue)` after a successful item.
108- `onError(error, item, queue)` after its retries fail.
109- `onSettled(item, queue)` after either outcome.
110- `onItemsChange(queue)` when the pending collection changes.
111- `onReject(item, queue)` and `onExpire(item, queue)` for items that never execute.
112​
113An item is removed from the pending queue before its function starts. A failed item is not automatically added back.
114​
115## Retrying items
116​
117Each started item receives its own retryer:
118​
119```ts
120const queue = useAsyncQueuer(processJob, {
121 concurrency: 2,
122 asyncRetryerOptions: {
123 maxAttempts: 3,
124 backoff: 'exponential',
125 baseWait: 500,
126 jitter: 0.2,
127 },
128})
129```
130​
131A retry remains part of the same active item and continues to occupy a concurrency slot. `maxAttempts` includes the first attempt. See the [Async Retrying Guide](./async-retrying.md) before retrying jobs with side effects.
132​
133## Starting, stopping, and flushing
134​
135Queues start automatically unless `started: false` is set.
136​
137- `stop()` prevents new automatic starts and clears pending wait timers. It does not abort active items or remove pending items.
138- `start()` resumes automatic processing.
139- `clear()` removes pending items. It does not affect active items.
140- `flush(count?)` starts pending items immediately without normal wait spacing.
141- `flushAsBatch(fn)` removes all pending items and passes them to one async batch function.
142​
143`flush()` uses direct executions and can start more work than the configured `concurrency`. Use it as an intentional drain operation, not as normal scheduling.
144​
145If any directly flushed item rejects with `throwOnError: true`, `flush()` rejects after all requested executions settle. Remaining pending work resumes afterward when the queue is running.
146​
147## Expiration
148​
149Pending items can expire through `expirationDuration` or `getIsExpired(item, addedAt)`. Expiration is checked when the queue ticks, not by a timer dedicated to each item. A stopped queue therefore evaluates stale items after it resumes.
150​
151Expired items are removed, call `onExpire`, and never reach the processing function. Active items do not expire.
152​
153## Aborting active work
154​
155`abort()` aborts the retryers for all active executions. It does not clear pending items. Cancellation reaches the underlying API only when the processing function uses its signal:
156​
157```ts
158const queue = useAsyncQueuer(
159 async (job: Job) => {
160 return fetch(`/api/jobs/${job.id}`, {
161 method: 'POST',
162 signal: queue.getAbortSignal() ?? undefined,
163 })
164 },
165 { concurrency: 2 },
167​
168queue.abort()
169```
170​
171When multiple executions overlap, pass an `executionCount` to `getAbortSignal()` when you need a specific execution's signal.
172​
173### Resetting safely
174​
175`reset()` restores default state, including an empty pending queue and a running status. It does not clear the queue's wait timers or guarantee that active underlying work stops. Use explicit lifecycle methods first:
176​
177```ts
178queue.stop()
179queue.abort()
180queue.reset()
181```
182​
183## React lifecycle
184​
185The adapter stops automatic processing and aborts active work when its owner is destroyed. Providing `onUnmount` replaces that default cleanup, so a custom callback must perform every required lifecycle action. When custom cleanup flushes work, remember that user callbacks can run while the component is being destroyed.
186​
187## Configuration and reactive state
188​
189The adapter subscribes only to the state returned by the selector argument. Without a selector, the adapter state is empty. Create the utility at the top level of a component or another hook and select only fields used by the view:
190​
191```ts
192const queue = useAsyncQueuer(processJob, { concurrency: 2 }, (state) => ({
193 size: state.size,
194 activeItems: state.activeItems,
195 status: state.status,
196}))
197​
198console.log(queue.state.size, queue.state.activeItems, queue.state.status)
199```
200​
201Option functions and lifecycle callbacks receive the underlying public utility instance. The `.store.state` reads inside those callbacks in the examples above are supported. Rendering code should read the selected adapter state shown here.
202​
203`concurrency` and `wait` may be values or functions that receive the queue instance. `setOptions()` merges new options, and `asyncQueuerOptions()` creates reusable, type-checked option objects.
204​
205`initialState` can restore selected queue state that your app has persisted. If it includes `items`, they take precedence over `initialItems`; `initialState.isRunning` likewise takes precedence over `started`. Restore only durable fields. Pending timers and active executions are not restored.
206​
207Common state includes:
208​
209- `items` and `size`: Pending work.
210- `activeItems`: Work currently tracked as active.
211- `isRunning`, `isIdle`, and `status`: Scheduler state.
212- `isFull` and `rejectionCount`: Pending capacity state.
213- `successCount`, `errorCount`, and `settleCount`: Execution outcomes.
214- `lastResult`: The most recent successful processing result.
215​
216Use `peekPendingItems()`, `peekActiveItems()`, and `peekAllItems()` for copied item arrays. See the [React API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.