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

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


// 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>;


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;


fn: (item) => void;

Defined in: queuer.ts:278

#### Parameters ##### item

TValue

#### Returns

void

### key

key: string | undefined;


key: string | undefined;

Defined in: queuer.ts:273

### options

options: QueuerOptions<TValue>;


options: QueuerOptions<TValue>;

Defined in: queuer.ts:274

### store

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


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

Defined in: queuer.ts:270

Methods
------- ### addItem()

addItem(
   item, 
   position, 
   runOnItemsChange): boolean;


addItem(
   item, 
   position, 
   runOnItemsChange): boolean;

Defined in: queuer.ts:399

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');


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

#### Parameters ##### item

TValue

##### position

QueuePosition = ...

##### runOnItemsChange

boolean = true

#### Returns

boolean

### clear()

clear(): void;


clear(): void;

Defined in: queuer.ts:681

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

#### Returns

void

### execute()

execute(position?): TValue | undefined;


execute(position?): TValue | undefined;

Defined in: queuer.ts:535

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

Example usage:

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


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

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

QueuePosition

#### Returns

TValue | undefined

### flush()

flush(numberOfItems, position?): void;


flush(numberOfItems, position?): void;

Defined in: queuer.ts:551

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 = ...

void

flushAsBatch(batchFunction): void;


flushAsBatch(batchFunction): void;

Defined in: queuer.ts:566

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;


getNextItem(position): TValue | undefined;

Defined in: queuer.ts:483

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');


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

#### Parameters ##### position

QueuePosition = ...

#### Returns

TValue | undefined

### peekAllItems()

peekAllItems(): TValue[];


peekAllItems(): TValue[];

Defined in: queuer.ts:649

Returns a copy of all items in the queue.

#### Returns

TValue[]

### peekNextItem()

peekNextItem(position): TValue | undefined;


peekNextItem(position): TValue | undefined;

Defined in: queuer.ts:639

Returns the next item in the queue without removing it.

Example usage:

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


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

#### Parameters ##### position

QueuePosition = 'front'

#### Returns

TValue | undefined

### reset()

reset(): void;


reset(): void;

Defined in: queuer.ts:689

Resets the queuer state to its default values

#### Returns

void

### setOptions()

setOptions(newOptions): void;


setOptions(newOptions): void;

Defined in: queuer.ts:315

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

#### Parameters ##### newOptions

Partial<QueuerOptions <TValue>>

#### Returns

void

### start()

start(): void;


start(): void;

Defined in: queuer.ts:656

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

#### Returns

void

### stop()

stop(): void;


stop(): void;

Defined in: queuer.ts:666

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

void

Partners Become a Partner

scarf analytics