Open History to see the last commit
1---
2id: AsyncQueuer
3title: AsyncQueuer
4---
5
6Defined in: [async-queuer.ts:315](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L315)
7
8A flexible asynchronous queue for processing tasks with configurable concurrency, priority, and expiration.
9
10Async vs Sync Versions:
11The async version provides advanced features over the sync Queuer:
12- Returns promises that can be awaited for task results
13- Built-in retry support via AsyncRetryer integration for each queued task
14- Abort support to cancel in-flight task executions
15- Comprehensive error handling with onError callbacks and throwOnError control
16- Detailed execution tracking (success/error/settle counts)
17- Concurrent execution support (process multiple items simultaneously)
18
19The sync Queuer is lighter weight and simpler when you don't need async features,
20return values, or execution control.
21
22What is Queuing?
23Queuing is a technique for managing and processing items sequentially or with controlled concurrency.
24Tasks are processed up to the configured concurrency limit. When a task completes,
25the next pending task is processed if the concurrency limit allows.
26
27Key Features:
28- Priority queue support via the getPriority option
29- Configurable concurrency limit
30- Callbacks for task success, error, completion, and queue state changes
31- FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
32- Pause and resume processing
33- Item expiration to remove stale items from the queue
34
35Error Handling:
36- If an `onError` handler is provided, it will be called with the error and queuer instance
37- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
38- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
39- Both onError and throwOnError can be used together; the handler will be called before any error is thrown
40- The error state can be checked using the AsyncQueuer instance
41
42State Management:
43- Uses TanStack Store for reactive state management
44- Use `initialState` to provide initial state values when creating the async queuer
45- Use `onSuccess` callback to react to successful task execution and implement custom logic
46- Use `onError` callback to react to task execution errors and implement custom error handling
47- Use `onSettled` callback to react to task execution completion (success or error) and implement custom logic
48- Use `onItemsChange` callback to react to items being added or removed from the queue
49- Use `onExpire` callback to react to items expiring and implement custom logic
50- Use `onReject` callback to react to items being rejected when the queue is full
51- The state includes error count, expiration count, rejection count, running status, and success/settle counts
52- State can be accessed via `asyncQueuer.store.state` when using the class directly
53- When using framework adapters (React/Solid), state is accessed from `asyncQueuer.state`
54
55Example usage:
56```ts
57const asyncQueuer = new AsyncQueuer<string>(async (item) => {
58 // process item
59 return item.toUpperCase();
60}, {
61 concurrency: 2,
62 onSuccess: (result) => {
63 console.log(result);
64 }
65});
66
67asyncQueuer.addItem('hello');
68asyncQueuer.start();
69```
70
71## Type Parameters
72
73### TValue
74
75`TValue`
76
77## Constructors
78
79### Constructor
80
81```ts
82new AsyncQueuer<TValue>(fn, initialOptions?): AsyncQueuer<TValue>;
83```
84
85Defined in: [async-queuer.ts:327](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L327)
86
87#### Parameters
88
89##### fn
90
91(`item`) => `Promise`\<`any`\>
92
93##### initialOptions?
94
95[`AsyncQueuerOptions`](../interfaces/AsyncQueuerOptions.md)\<`TValue`\> = `{}`
96
97#### Returns
98
99`AsyncQueuer`\<`TValue`\>
100
101## Properties
102
103### asyncRetryers
104
105```ts
106asyncRetryers: Map<number, AsyncRetryer<(item) => Promise<any>>>;
107```
108
109Defined in: [async-queuer.ts:321](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L321)
110
111***
112
113### fn
114
115```ts
116fn: (item) => Promise<any>;
117```
118
119Defined in: [async-queuer.ts:328](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L328)
120
121#### Parameters
122
123##### item
124
125`TValue`
126
127#### Returns
128
129`Promise`\<`any`\>
130
131***
132
133### key
134
135```ts
136key: string | undefined;
137```
138
139Defined in: [async-queuer.ts:319](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L319)
140
141***
142
143### options
144
145```ts
146options: AsyncQueuerOptions<TValue>;
147```
148
149Defined in: [async-queuer.ts:320](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L320)
150
151***
152
153### store
154
155```ts
156readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;
157```
158
159Defined in: [async-queuer.ts:316](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L316)
160
161## Methods
162
163### abort()
164
165```ts
166abort(): void;
167```
168
169Defined in: [async-queuer.ts:899](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L899)
170
171Aborts all ongoing executions with the internal abort controllers.
172Does NOT clear out the items.
173
174#### Returns
175
176`void`
177
178***
179
180### addItem()
181
182```ts
183addItem(
184 item,
185 position?,
186 runOnItemsChange?): boolean;
187```
188
189Defined in: [async-queuer.ts:490](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L490)
190
191Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
192Items can be inserted based on priority or at the front/back depending on configuration.
193`undefined` cannot be queued (it is the internal "no item" sentinel) and is always rejected.
194
195#### Parameters
196
197##### item
198
199`TValue`
200
201##### position?
202
203[`QueuePosition`](../type-aliases/QueuePosition.md) = `...`
204
205##### runOnItemsChange?
206
207`boolean` = `true`
208
209#### Returns
210
211`boolean`
212
213#### Example
214
215```ts
216queuer.addItem({ value: 'task', priority: 10 });
217queuer.addItem('task2', 'front');
218```
219
220***
221
222### clear()
223
224```ts
225clear(): void;
226```
227
228Defined in: [async-queuer.ts:864](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L864)
229
230Removes all pending items from the queue.
231Does NOT affect active tasks.
232
233#### Returns
234
235`void`
236
237***
238
239### execute()
240
241```ts
242execute(position?): Promise<any>;
243```
244
245Defined in: [async-queuer.ts:635](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L635)
246
247Removes and returns the next item from the queue and executes the task function with it.
248
249#### Parameters
250
251##### position?
252
253[`QueuePosition`](../type-aliases/QueuePosition.md)
254
255#### Returns
256
257`Promise`\<`any`\>
258
259#### Example
260
261```ts
262queuer.execute();
263// LIFO
264queuer.execute('back');
265```
266
267***
268
269### flush()
270
271```ts
272flush(numberOfItems?, position?): Promise<void>;
273```
274
275Defined in: [async-queuer.ts:689](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L689)
276
277Processes a specified number of items to execute immediately with no wait time
278If no numberOfItems is provided, all items will be processed
279
280#### Parameters
281
282##### numberOfItems?
283
284`number` = `...`
285
286##### position?
287
288[`QueuePosition`](../type-aliases/QueuePosition.md)
289
290#### Returns
291
292`Promise`\<`void`\>
293
294***
295
296### flushAsBatch()
297
298```ts
299flushAsBatch(batchFunction): Promise<void>;
300```
301
302Defined in: [async-queuer.ts:726](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L726)
303
304Processes all items in the queue as a batch using the provided function as an argument
305The queue is cleared after processing
306
307#### Parameters
308
309##### batchFunction
310
311(`items`) => `Promise`\<`any`\>
312
313#### Returns
314
315`Promise`\<`void`\>
316
317***
318
319### getAbortSignal()
320
321```ts
322getAbortSignal(executionCount?): AbortSignal | null;
323```
324
325Defined in: [async-queuer.ts:889](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L889)
326
327Returns the AbortSignal for a specific execution.
328If no executionCount is provided, returns the signal for the most recent execution.
329Returns null if no execution is found or not currently executing.
330
331#### Parameters
332
333##### executionCount?
334
335`number`
336
337Optional specific execution to get signal for
338
339#### Returns
340
341`AbortSignal` \| `null`
342
343#### Example
344
345```typescript
346const queuer = new AsyncQueuer(
347 async (item: string) => {
348 const signal = queuer.getAbortSignal()
349 if (signal) {
350 const response = await fetch(`/api/process/${item}`, { signal })
351 return response.json()
352 }
353 },
354 { concurrency: 2 }
355)
356```
357
358***
359
360### getNextItem()
361
362```ts
363getNextItem(position?): TValue | undefined;
364```
365
366Defined in: [async-queuer.ts:583](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L583)
367
368Removes and returns the next item from the queue without executing the task function.
369Use for manual queue management. Normally, use execute() to process items.
370
371#### Parameters
372
373##### position?
374
375[`QueuePosition`](../type-aliases/QueuePosition.md) = `...`
376
377#### Returns
378
379`TValue` \| `undefined`
380
381#### Example
382
383```ts
384// FIFO
385queuer.getNextItem();
386// LIFO
387queuer.getNextItem('back');
388```
389
390***
391
392### peekActiveItems()
393
394```ts
395peekActiveItems(): TValue[];
396```
397
398Defined in: [async-queuer.ts:826](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L826)
399
400Returns the items currently being processed (active tasks).
401
402#### Returns
403
404`TValue`[]
405
406***
407
408### peekAllItems()
409
410```ts
411peekAllItems(): TValue[];
412```
413
414Defined in: [async-queuer.ts:819](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L819)
415
416Returns a copy of all items in the queue, including active and pending items.
417
418#### Returns
419
420`TValue`[]
421
422***
423
424### peekNextItem()
425
426```ts
427peekNextItem(position?): TValue | undefined;
428```
429
430Defined in: [async-queuer.ts:809](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L809)
431
432Returns the next item in the queue without removing it.
433
434#### Parameters
435
436##### position?
437
438[`QueuePosition`](../type-aliases/QueuePosition.md) = `'front'`
439
440#### Returns
441
442`TValue` \| `undefined`
443
444#### Example
445
446```ts
447queuer.peekNextItem(); // front
448queuer.peekNextItem('back'); // back
449```
450
451***
452
453### peekPendingItems()
454
455```ts
456peekPendingItems(): TValue[];
457```
458
459Defined in: [async-queuer.ts:833](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L833)
460
461Returns the items waiting to be processed (pending tasks).
462
463#### Returns
464
465`TValue`[]
466
467***
468
469### reset()
470
471```ts
472reset(): void;
473```
474
475Defined in: [async-queuer.ts:910](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L910)
476
477Resets the queuer state to its default values
478
479#### Returns
480
481`void`
482
483***
484
485### setOptions()
486
487```ts
488setOptions(newOptions): void;
489```
490
491Defined in: [async-queuer.ts:372](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L372)
492
493Updates the queuer options. New options are merged with existing options.
494
495#### Parameters
496
497##### newOptions
498
499`Partial`\<[`AsyncQueuerOptions`](../interfaces/AsyncQueuerOptions.md)\<`TValue`\>\>
500
501#### Returns
502
503`void`
504
505***
506
507### start()
508
509```ts
510start(): void;
511```
512
513Defined in: [async-queuer.ts:840](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L840)
514
515Starts processing items in the queue. If already running, does nothing.
516
517#### Returns
518
519`void`
520
521***
522
523### stop()
524
525```ts
526stop(): void;
527```
528
529Defined in: [async-queuer.ts:850](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L850)
530
531Stops processing items in the queue. Does not clear the queue.
532
533#### Returns
534
535`void`