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 statewait: Configurable delay between processing itemsonItemsChange/onExecute: Callbacks for monitoring queue state
Manual processing is also supported when automatic processing is disabled:
execute(): Processes the next item using the provided functiongetNextItem(): 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
getPriorityfunction; higher values are processed first
Stack (LIFO):
addItem(item, 'back'): Adds to the backgetNextItem('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 queuegetIsExpired: Function to override default expirationonExpire: Callback for expired items
State Management:
- Uses TanStack Store for reactive state management
- Use
initialStateto provide initial state values when creating the queuer - Use
onExecutecallback to react to item execution and implement custom logic - Use
onItemsChangecallback to react to items being added or removed from the queue - Use
onExpirecallback to react to items expiring and implement custom logic - Use
onRejectcallback 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.statewhen 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:404
Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
undefined cannot be queued (it is the internal "no item" sentinel) and is always rejected.
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:696
Removes all pending items from the queue. Does not affect items being processed.
Returns#
void
execute()#
execute(position?): TValue | undefined;
Defined in: queuer.ts:550
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?#
Returns#
TValue | undefined
flush()#
flush(numberOfItems?, position?): void;
Defined in: queuer.ts:566
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?#
Returns#
void
flushAsBatch()#
flushAsBatch(batchFunction): void;
Defined in: queuer.ts:581
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:498
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:664
Returns a copy of all items in the queue.
Returns#
TValue[]
peekNextItem()#
peekNextItem(position?): TValue | undefined;
Defined in: queuer.ts:654
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:704
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<TValue>>
Returns#
void
start()#
start(): void;
Defined in: queuer.ts:671
Starts processing items in the queue. If already isRunning, does nothing.
Returns#
void
stop()#
stop(): void;
Defined in: queuer.ts:681
Stops processing items in the queue. Does not clear the queue.
Returns#
void