Class: Queuer\#

Defined in: queuer.ts:269

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

This synchronous version is lighter weight and often all you need - upgrade to AsyncQueuer when you need promises, retry support, abort capabilities, concurrent execution, or advanced error handling.

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 isRunning)

• 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

  State Management:

• Uses TanStack Store for reactive state management

• Use initialState to provide initial state values when creating the queuer

• Use onExecute callback to react to item execution 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 execution count, expiration count, rejection count, and isRunning status

• State can be accessed via queuer.store.state when using the class directly

• When using framework adapters (React/Solid), state is accessed from queuer.state

  Example usage:

// 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, queuer) => 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#

TValue

Constructors#

Constructor#

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

Defined in: queuer.ts:277

Parameters#

fn#

(item) => void

initialOptions#

QueuerOptions\<`TValue`\> = {}

Returns#

Queuer\<`TValue`\>

Properties#

fn()#

fn: (item) => void;

Defined in: queuer.ts:278

Parameters#

item#

TValue

Returns#

void

key#

key: string | undefined;

Defined in: queuer.ts:273

options#

options: QueuerOptions<TValue>;

Defined in: queuer.ts:274

store#

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

Defined in: queuer.ts:270

Methods#

addItem()#

addItem(
   item, 
   position, 
   runOnItemsChange): boolean;

Defined in: queuer.ts:403

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:

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

Parameters#

item#

TValue

position#

QueuePosition = ...

runOnItemsChange#

boolean = true

Returns#

boolean

clear()#

clear(): void;

Defined in: queuer.ts:685

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

Returns#

void

execute()#

execute(position?): TValue | undefined;

Defined in: queuer.ts:539

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

Example usage:

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

Parameters#

position?#

QueuePosition

Returns#

TValue | undefined

flush()#

flush(numberOfItems, position?): void;

Defined in: 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

flushAsBatch()#

flushAsBatch(batchFunction): void;

Defined in: queuer.ts:570

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) => void

Returns#

void

getNextItem()#

getNextItem(position): TValue | undefined;

Defined in: queuer.ts:487

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:

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

Parameters#

position#

QueuePosition = ...

Returns#

TValue | undefined

peekAllItems()#

peekAllItems(): TValue[];

Defined in: queuer.ts:653

Returns a copy of all items in the queue.

Returns#

TValue[]

peekNextItem()#

peekNextItem(position): TValue | undefined;

Defined in: queuer.ts:643

Returns the next item in the queue without removing it.

Example usage:

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

Parameters#

position#

QueuePosition = 'front'

Returns#

TValue | undefined

reset()#

reset(): void;

Defined in: queuer.ts:693

Resets the queuer state to its default values

Returns#

void

setOptions()#

setOptions(newOptions): void;

Defined in: queuer.ts:319

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

Parameters#

newOptions#

Partial\<[`QueuerOptions`](../interfaces/QueuerOptions.md)\<`TValue`\>>

Returns#

void

start()#

start(): void;

Defined in: queuer.ts:660

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

Returns#

void

stop()#

stop(): void;

Defined in: queuer.ts:670

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

Returns#

void