js-queue
  1. Docs
  2. Patterns

Composition guide

Put the release point where truth lives.

The task knows whether work finished, failed, paused, or lost its connection. Let that task decide when the queue advances.

Async work

Release from finally.

When later work should proceed whether the operation succeeds or fails, place this.next() in the same cleanup boundary you already trust.

Promise

Keep the queue moving

queue.add(function(){
    sendMessage()
        .then(recordSuccess)
        .catch(recordFailure)
        .finally(()=>this.next());
});
Callback

Release after completion

queue.add(function(){
    writeFile(data,error=>{
        if(error) report(error);
        this.next();
    });
});
Do not use an arrow task when you need this.next().

Arrow callbacks inside the task are fine because they preserve the task's queue-bound this.

Stop gates

Queue now. Open later.

Set stop=true before producers add work. When the dependency is ready, clear the flag and call next() once.

const outbound=new Queue;
outbound.stop=true;

outbound.add(sendGreeting,sendPresence,requestHistory);

socket.addEventListener('open',()=>{
    outbound.stop=false;
    outbound.next();
});

socket.addEventListener('close',()=>{
    outbound.stop=true;
});
Pause

Preserve pending work

stop blocks next() without changing contents. Use it for recoverable conditions.

Cancel

Discard pending work

clear() removes everything except the currently executing task. Use it when queued intent is no longer valid.

Recovery

Keep remaining work available.

A synchronous task error is rethrown after running resets to false. Later tasks remain pending so the caller can clear, retry, or continue.

queue.autoRun=false;
queue.add(riskyTask,nextTask);

try{
    queue.next();
}catch(error){
    report(error);
    // choose one policy:
    queue.next();  // continue
    // queue.clear(); // cancel
}
Promise rejections are asynchronous.

The queue cannot catch them from the original next() call. Handle the promise inside the task and release deliberately.

See stop, resume, clear, and asynchronous release happen in a live queue.

Run examples