📄 tanstack/pacer/latest/docs/reference/classes/AsyncQueuer

File: AsyncQueuer.md | Updated: 11/15/2025

Source: https://tanstack.com/pacer/latest/docs/reference/classes/AsyncQueuer



TanStack

Pacer v0v0

Search...

+ K

Auto

Log In

TanStack StartRC

Docs Examples GitHub Contributors

TanStack Router

Docs Examples GitHub Contributors

TanStack Query

Docs Examples GitHub Contributors

TanStack Table

Docs Examples Github Contributors

TanStack Formnew

Docs Examples Github Contributors

TanStack DBbeta

Docs Github Contributors

TanStack Virtual

Docs Examples Github Contributors

TanStack Paceralpha

Docs Examples Github Contributors

TanStack Storealpha

Docs Examples Github Contributors

TanStack Devtoolsalpha

Docs Github Contributors

More Libraries

Maintainers Partners Support Learn StatsBETA Discord Merch Blog GitHub Ethos Brand Guide

Documentation

Framework

React logo

React

Version

Latest

Search...

+ K

Menu

Getting Started

Guides

API Reference

Debouncer API Reference

Throttler API Reference

Rate Limiter API Reference

Queue API Reference

Batcher API Reference

Debouncer Examples

Throttler Examples

Rate Limiter Examples

Queue Examples

Batcher Examples

TanStack Query Examples

Framework

React logo

React

Version

Latest

Menu

Getting Started

Guides

API Reference

Debouncer API Reference

Throttler API Reference

Rate Limiter API Reference

Queue API Reference

Batcher API Reference

Debouncer Examples

Throttler Examples

Rate Limiter Examples

Queue Examples

Batcher Examples

TanStack Query Examples

On this page

AsyncQueuer

Copy Markdown

Class: AsyncQueuer<TValue>
==========================

Defined in: async-queuer.ts:315

A flexible asynchronous queue for processing tasks with configurable concurrency, priority, and expiration.

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

  • 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 Queuer 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.

Key Features:

  • Priority queue support via the getPriority option
  • Configurable concurrency limit
  • Callbacks for task success, error, completion, and queue state changes
  • FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
  • Pause and resume processing
  • Item expiration to remove stale items from the queue

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 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 asyncQueuer.store.state when using the class directly
  • When using framework adapters (React/Solid), state is accessed from asyncQueuer.state

Example usage:

ts

const asyncQueuer = new AsyncQueuer<string>(async (item) => {
  // process item
  return item.toUpperCase();
}, {
  concurrency: 2,
  onSuccess: (result) => {
    console.log(result);
  }
});

asyncQueuer.addItem('hello');
asyncQueuer.start();


const asyncQueuer = new AsyncQueuer<string>(async (item) => {
  // process item
  return item.toUpperCase();
}, {
  concurrency: 2,
  onSuccess: (result) => {
    console.log(result);
  }
});

asyncQueuer.addItem('hello');
asyncQueuer.start();

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

TValue

Constructors
------------ ### Constructor

ts

new AsyncQueuer<TValue>(fn, initialOptions): AsyncQueuer<TValue>;


new AsyncQueuer<TValue>(fn, initialOptions): AsyncQueuer<TValue>;

Defined in: async-queuer.ts:327

#### Parameters ##### fn

(item) => Promise<any>

##### initialOptions

AsyncQueuerOptions <TValue> = {}

#### Returns

AsyncQueuer<TValue>

Properties
---------- ### asyncRetryers

ts

asyncRetryers: Map<number, AsyncRetryer<(item) => Promise<any>>>;


asyncRetryers: Map<number, AsyncRetryer<(item) => Promise<any>>>;

Defined in: async-queuer.ts:321

### fn()

ts

fn: (item) => Promise<any>;


fn: (item) => Promise<any>;

Defined in: async-queuer.ts:328

#### Parameters ##### item

TValue

#### Returns

Promise<any>

### key

ts

key: string | undefined;


key: string | undefined;

Defined in: async-queuer.ts:319

### options

ts

options: AsyncQueuerOptions<TValue>;


options: AsyncQueuerOptions<TValue>;

Defined in: async-queuer.ts:320

### store

ts

readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;


readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;

Defined in: async-queuer.ts:316

Methods
------- ### abort()

ts

abort(): void;


abort(): void;

Defined in: async-queuer.ts:831

Aborts all ongoing executions with the internal abort controllers. Does NOT clear out the items.

#### Returns

void

### addItem()

ts

addItem(
   item, 
   position, 
   runOnItemsChange): boolean;


addItem(
   item, 
   position, 
   runOnItemsChange): boolean;

Defined in: async-queuer.ts:469

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

ts

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


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

### clear()

ts

clear(): void;


clear(): void;

Defined in: async-queuer.ts:796

Removes all pending items from the queue. Does NOT affect active tasks.

#### Returns

void

### execute()

ts

execute(position?): Promise<any>;


execute(position?): Promise<any>;

Defined in: async-queuer.ts:604

Removes and returns the next item from the queue and executes the task function with it.

#### Parameters ##### position?

QueuePosition

#### Returns

Promise<any>

#### Example

ts

queuer.execute();
// LIFO
queuer.execute('back');


queuer.execute();
// LIFO
queuer.execute('back');

### flush()

ts

flush(numberOfItems, position?): Promise<void>;


flush(numberOfItems, position?): Promise<void>;

Defined in: async-queuer.ts:652

Processes a specified number of items to execute immediately with no wait time If no numberOfItems is provided, all items will be processed

#### Parameters ##### numberOfItems

number = ...

##### position?

QueuePosition

#### Returns

Promise<void>

### flushAsBatch()

ts

flushAsBatch(batchFunction): Promise<void>;


flushAsBatch(batchFunction): Promise<void>;

Defined in: async-queuer.ts:666

Processes all items in the queue as a batch using the provided function as an argument The queue is cleared after processing

#### Parameters ##### batchFunction

(items) => Promise<any>

#### Returns

Promise<void>

### getAbortSignal()

ts

getAbortSignal(executeCount?): AbortSignal | null;


getAbortSignal(executeCount?): AbortSignal | null;

Defined in: async-queuer.ts:821

Returns the AbortSignal for a specific execution. If no executeCount is provided, returns the signal for the most recent execution. Returns null if no execution is found or not currently executing.

#### Parameters ##### executeCount?

number

Optional specific execution to get signal for

#### Returns

AbortSignal | null

#### Example

typescript

const queuer = new AsyncQueuer(
  async (item: string) => {
    const signal = queuer.getAbortSignal()
    if (signal) {
      const response = await fetch(`/api/process/${item}`, { signal })
      return response.json()
    }
  },
  { concurrency: 2 }
)


const queuer = new AsyncQueuer(
  async (item: string) => {
    const signal = queuer.getAbortSignal()
    if (signal) {
      const response = await fetch(`/api/process/${item}`, { signal })
      return response.json()
    }
  },
  { concurrency: 2 }
)

### getNextItem()

ts

getNextItem(position): TValue | undefined;


getNextItem(position): TValue | undefined;

Defined in: async-queuer.ts:552

Removes and returns the next item from the queue without executing the task function. Use for manual queue management. Normally, use execute() to process items.

#### Parameters ##### position

QueuePosition = ...

#### Returns

TValue | undefined

#### Example

ts

// FIFO
queuer.getNextItem();
// LIFO
queuer.getNextItem('back');


// FIFO
queuer.getNextItem();
// LIFO
queuer.getNextItem('back');

### peekActiveItems()

ts

peekActiveItems(): TValue[];


peekActiveItems(): TValue[];

Defined in: async-queuer.ts:758

Returns the items currently being processed (active tasks).

#### Returns

TValue[]

### peekAllItems()

ts

peekAllItems(): TValue[];


peekAllItems(): TValue[];

Defined in: async-queuer.ts:751

Returns a copy of all items in the queue, including active and pending items.

#### Returns

TValue[]

### peekNextItem()

ts

peekNextItem(position): TValue | undefined;


peekNextItem(position): TValue | undefined;

Defined in: async-queuer.ts:741

Returns the next item in the queue without removing it.

#### Parameters ##### position

QueuePosition = 'front'

#### Returns

TValue | undefined

#### Example

ts

queuer.peekNextItem(); // front
queuer.peekNextItem('back'); // back


queuer.peekNextItem(); // front
queuer.peekNextItem('back'); // back

### peekPendingItems()

ts

peekPendingItems(): TValue[];


peekPendingItems(): TValue[];

Defined in: async-queuer.ts:765

Returns the items waiting to be processed (pending tasks).

#### Returns

TValue[]

### reset()

ts

reset(): void;


reset(): void;

Defined in: async-queuer.ts:842

Resets the queuer state to its default values

#### Returns

void

### setOptions()

ts

setOptions(newOptions): void;


setOptions(newOptions): void;

Defined in: async-queuer.ts:366

Updates the queuer options. New options are merged with existing options.

#### Parameters ##### newOptions

Partial<AsyncQueuerOptions <TValue>>

#### Returns

void

### start()

ts

start(): void;


start(): void;

Defined in: async-queuer.ts:772

Starts processing items in the queue. If already running, does nothing.

#### Returns

void

### stop()

ts

stop(): void;


stop(): void;

Defined in: async-queuer.ts:782

Stops processing items in the queue. Does not clear the queue.

#### Returns

void

Edit on GitHub

Queuer

ReactQueuer

Partners Become a Partner

Code RabbitCode Rabbit CloudflareCloudflare AG GridAG Grid NetlifyNetlify NeonNeon WorkOSWorkOS ClerkClerk ConvexConvex ElectricElectric SentrySentry PrismaPrisma StrapiStrapi UnkeyUnkey

scarf analytics