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

Queuer

Class: Queuer<TValue>

Defined in: queuer.ts:160

A flexible queue that processes items with configurable wait times, expiration, and priority.

Features:

  • Automatic or manual processing of items
  • FIFO (First In First Out), LIFO (Last In First Out), or double-ended queue behavior
  • Priority-based ordering when getPriority is provided
  • Item expiration and removal of stale items
  • Callbacks for queue state changes, execution, rejection, and expiration

Running behavior:

  • start(): Begins automatically processing items in the queue (defaults to running)
  • stop(): Pauses processing but maintains queue state
  • wait: Configurable delay between processing items
  • onItemsChange/onExecute: Callbacks for monitoring queue state

Manual processing is also supported when automatic processing is disabled:

  • execute(): Processes the next item using the provided function
  • getNextItem(): Removes and returns the next item without processing

Queue behavior defaults to FIFO:

  • addItem(item): Adds to the back of the queue
  • Items processed from the front of the queue

Priority queue:

  • Provide a getPriority function; higher values are processed first

Stack (LIFO):

  • addItem(item, 'back'): Adds to the back
  • getNextItem('back'): Removes from the back

Double-ended queue:

  • addItem(item, position): Adds to specified position ('front'/'back')
  • getNextItem(position): Removes from specified position

Item expiration:

  • expirationDuration: Maximum time items can stay in the queue
  • getIsExpired: Function to override default expiration
  • onExpire: Callback for expired items

Example usage:

ts
// Auto-processing queue with wait time
const autoQueue = new Queuer<number>((n) => console.log(n), {
  started: true, // Begin processing immediately
  wait: 1000, // Wait 1s between items
  onExecute: (item) => console.log(`Processed ${item}`)
});
autoQueue.addItem(1); // Will process after 1s
autoQueue.addItem(2); // Will process 1s after first item

// Manual processing queue
const manualQueue = new Queuer<number>((n) => console.log(n), {
  started: false
});
manualQueue.addItem(1); // [1]
manualQueue.addItem(2); // [1, 2]
manualQueue.execute(); // logs 1, queue is [2]
manualQueue.getNextItem(); // returns 2, queue is empty
// Auto-processing queue with wait time
const autoQueue = new Queuer<number>((n) => console.log(n), {
  started: true, // Begin processing immediately
  wait: 1000, // Wait 1s between items
  onExecute: (item) => console.log(`Processed ${item}`)
});
autoQueue.addItem(1); // Will process after 1s
autoQueue.addItem(2); // Will process 1s after first item

// Manual processing queue
const manualQueue = new Queuer<number>((n) => console.log(n), {
  started: false
});
manualQueue.addItem(1); // [1]
manualQueue.addItem(2); // [1, 2]
manualQueue.execute(); // logs 1, queue is [2]
manualQueue.getNextItem(); // returns 2, queue is empty

Type Parameters

• TValue

Constructors

new Queuer()

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

Defined in: queuer.ts:171

Parameters

fn

(item) => void

initialOptions

QueuerOptions<TValue> = {}

Returns

Queuer<TValue>

Methods

addItem()

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

Defined in: queuer.ts:343

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.

Returns true if the item was added, false if the queue is full.

Example usage:

ts
queuer.addItem('task');
queuer.addItem('task2', 'front');
queuer.addItem('task');
queuer.addItem('task2', 'front');

Parameters

item

TValue

position

QueuePosition = ...

runOnUpdate

boolean = true

Returns

boolean


clear()

ts
clear(): void
clear(): void

Defined in: queuer.ts:313

Removes all pending items from the queue. Does not affect items being processed.

Returns

void


execute()

ts
execute(position?): undefined | TValue
execute(position?): undefined | TValue

Defined in: queuer.ts:431

Removes and returns the next item from the queue and processes it using the provided function.

Example usage:

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

Parameters

position?

QueuePosition

Returns

undefined | TValue


getExecutionCount()

ts
getExecutionCount(): number
getExecutionCount(): number

Defined in: queuer.ts:490

Returns the number of items that have been processed and removed from the queue.

Returns

number


getExpirationCount()

ts
getExpirationCount(): number
getExpirationCount(): number

Defined in: queuer.ts:504

Returns the number of items that have expired and been removed from the queue.

Returns

number


getIsEmpty()

ts
getIsEmpty(): boolean
getIsEmpty(): boolean

Defined in: queuer.ts:462

Returns true if the queue is empty (no pending items).

Returns

boolean


getIsFull()

ts
getIsFull(): boolean
getIsFull(): boolean

Defined in: queuer.ts:469

Returns true if the queue is full (reached maxSize).

Returns

boolean


getIsIdle()

ts
getIsIdle(): boolean
getIsIdle(): boolean

Defined in: queuer.ts:518

Returns true if the queuer is running but has no items to process.

Returns

boolean


getIsRunning()

ts
getIsRunning(): boolean
getIsRunning(): boolean

Defined in: queuer.ts:511

Returns true if the queuer is currently running (processing items).

Returns

boolean


getNextItem()

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

Defined in: queuer.ts:401

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

Example usage:

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

Parameters

position

QueuePosition = ...

Returns

undefined | TValue


getOptions()

ts
getOptions(): Required<QueuerOptions<TValue>>
getOptions(): Required<QueuerOptions<TValue>>

Defined in: queuer.ts:195

Returns the current queuer options, including defaults and any overrides.

Returns

Required<QueuerOptions<TValue>>


getRejectionCount()

ts
getRejectionCount(): number
getRejectionCount(): number

Defined in: queuer.ts:497

Returns the number of items that have been rejected from being added to the queue.

Returns

number


getSize()

ts
getSize(): number
getSize(): number

Defined in: queuer.ts:476

Returns the number of pending items in the queue.

Returns

number


getWait()

ts
getWait(): number
getWait(): number

Defined in: queuer.ts:203

Returns the current wait time (in milliseconds) between processing items. If a function is provided, it is called with the queuer instance.

Returns

number


peekAllItems()

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

Defined in: queuer.ts:483

Returns a copy of all items in the queue.

Returns

TValue[]


peekNextItem()

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

Defined in: queuer.ts:450

Returns the next item in the queue without removing it.

Example usage:

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

Parameters

position

QueuePosition = ...

Returns

undefined | TValue


reset()

ts
reset(withInitialItems?): void
reset(withInitialItems?): void

Defined in: queuer.ts:322

Resets the queuer to its initial state. Optionally repopulates with initial items. Does not affect callbacks or options.

Parameters

withInitialItems?

boolean

Returns

void


setOptions()

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

Defined in: queuer.ts:188

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

Parameters

newOptions

Partial<QueuerOptions<TValue>>

Returns

void


start()

ts
start(): void
start(): void

Defined in: queuer.ts:301

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

Returns

void


stop()

ts
stop(): void
stop(): void

Defined in: queuer.ts:292

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.