📄 tanstack/pacer/latest/docs/reference/functions/asyncQueue

function asyncQueue<TValue>(fn, initialOptions): (item, position, runOnItemsChange) => boolean;


function asyncQueue<TValue>(fn, initialOptions): (item, position, runOnItemsChange) => boolean;

Defined in: async-queuer.ts:914

Creates a new AsyncQueuer instance and returns a bound addItem function for adding tasks. The queuer is started automatically and ready to process items.

Async vs Sync Versions: The async version provides advanced features over the sync queue function:

Returns promises that can be awaited for task results
Built-in retry support via AsyncRetryer integration for each queued task
Abort support to cancel in-flight task executions
Comprehensive error handling with onError callbacks and throwOnError control
Detailed execution tracking (success/error/settle counts)
Concurrent execution support (process multiple items simultaneously)

The sync queue function is lighter weight and simpler when you don't need async features, return values, or execution control.

What is Queuing? Queuing is a technique for managing and processing items sequentially or with controlled concurrency. Tasks are processed up to the configured concurrency limit. When a task completes, the next pending task is processed if the concurrency limit allows.

Configuration Options:

concurrency: Maximum number of concurrent tasks (default: 1)
wait: Time to wait between processing items (default: 0)
maxSize: Maximum number of items allowed in the queue (default: Infinity)
getPriority: Function to determine item priority
addItemsTo: Default position to add items ('back' or 'front', default: 'back')
getItemsFrom: Default position to get items ('front' or 'back', default: 'front')
expirationDuration: Maximum time items can stay in queue
started: Whether to start processing immediately (default: true)
asyncRetryerOptions: Configure retry behavior for task executions

Error Handling:

If an onError handler is provided, it will be called with the error and queuer instance
If throwOnError is true (default when no onError handler is provided), the error will be thrown
If throwOnError is false (default when onError handler is provided), the error will be swallowed
Both onError and throwOnError can be used together; the handler will be called before any error is thrown
The error state can be checked using the underlying AsyncQueuer instance

State Management:

Uses TanStack Store for reactive state management
Use initialState to provide initial state values when creating the async queuer
Use onSuccess callback to react to successful task execution and implement custom logic
Use onError callback to react to task execution errors and implement custom error handling
Use onSettled callback to react to task execution completion (success or error) and implement custom logic
Use onItemsChange callback to react to items being added or removed from the queue
Use onExpire callback to react to items expiring and implement custom logic
Use onReject callback to react to items being rejected when the queue is full
The state includes error count, expiration count, rejection count, running status, and success/settle counts
State can be accessed via the underlying AsyncQueuer instance's store.state property
When using framework adapters (React/Solid), state is accessed from the hook's state property

Type Parameters
--------------- ### TValue

TValue

Parameters
---------- ### fn

(value) => Promise<any>

### initialOptions

AsyncQueuerOptions <TValue>

Returns
-------

(
   item, 
   position, 
   runOnItemsChange): boolean;


(
   item, 
   position, 
   runOnItemsChange): boolean;

Adds an item to the queue. If the queue is full, the item is rejected and onReject is called. Items can be inserted based on priority or at the front/back depending on configuration.

### Parameters #### item

TValue

#### position

QueuePosition = ...

#### runOnItemsChange

boolean = true

### Returns

boolean

### Example

queuer.addItem({ value: 'task', priority: 10 });
queuer.addItem('task2', 'front');


queuer.addItem({ value: 'task', priority: 10 });
queuer.addItem('task2', 'front');

Example
-------

const enqueue = asyncQueue<string>(async (item) => {
  return item.toUpperCase();
}, {
  concurrency: 2,
  wait: 100,
  onSuccess: (result) => console.log('Processed:', result)
});

enqueue('hello');


const enqueue = asyncQueue<string>(async (item) => {
  return item.toUpperCase();
}, {
  concurrency: 2,
  wait: 100,
  onSuccess: (result) => console.log('Processed:', result)
});

enqueue('hello');

Edit on GitHub

queue

Queuer

Partners Become a Partner

scarf analytics