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

AsyncQueuer.md

535 lines11.1 KB

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