Framework
Version
Debouncer API Reference
Throttler API Reference
Rate Limiter API Reference
Queue API Reference
Batcher API Reference

AsyncQueuer

Class: AsyncQueuer<TValue>

Defined in: async-queuer.ts:259

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

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
  • Task cancellation
  • Item expiration to remove stale items from the queue

Tasks are processed concurrently up to the configured concurrency limit. When a task completes, the next pending task is processed if the concurrency limit allows.

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

Constructors

new AsyncQueuer()

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

Defined in: async-queuer.ts:266

Parameters

fn

(item) => Promise<any>

initialOptions

AsyncQueuerOptions<TValue> = {}

Returns

AsyncQueuer<TValue>

Properties

options

ts
options: AsyncQueuerOptions<TValue>;
options: AsyncQueuerOptions<TValue>;

Defined in: async-queuer.ts:263


store

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

Defined in: async-queuer.ts:260

Methods

addItem()

ts
addItem(
   item, 
   position, 
   runOnItemsChange): boolean
addItem(
   item, 
   position, 
   runOnItemsChange): boolean

Defined in: async-queuer.ts:400

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:686

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:520

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?): void
flush(numberOfItems, position?): void

Defined in: async-queuer.ts:555

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

void


getNextItem()

ts
getNextItem(position): undefined | TValue
getNextItem(position): undefined | TValue

Defined in: async-queuer.ts:479

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

undefined | TValue

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:649

Returns the items currently being processed (active tasks).

Returns

TValue[]


peekAllItems()

ts
peekAllItems(): TValue[]
peekAllItems(): TValue[]

Defined in: async-queuer.ts:642

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

Returns

TValue[]


peekNextItem()

ts
peekNextItem(position): undefined | TValue
peekNextItem(position): undefined | TValue

Defined in: async-queuer.ts:632

Returns the next item in the queue without removing it.

Parameters

position

QueuePosition = 'front'

Returns

undefined | TValue

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:656

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

Returns

TValue[]


reset()

ts
reset(): void
reset(): void

Defined in: async-queuer.ts:694

Resets the queuer state to its default values

Returns

void


setOptions()

ts
setOptions(newOptions): void
setOptions(newOptions): void

Defined in: async-queuer.ts:298

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:663

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

Returns

void


stop()

ts
stop(): void
stop(): void

Defined in: async-queuer.ts:673

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

Returns

void

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.