🦥 Carriageway

Run async and promise-returning functions with limited concurrency and optional rate limiting.

Usage

Deno imports from mod.ts. Other runtimes import from index.min.js (Bun, Node, web browsers).

Create a new queue:

const queue = new Queue();

Append an item with a callback function:

queue.append('task', (name) => {
  console.log(`${name} complete`);
});

append returns a deferred promise that resolves the callback when the queued item is run. The item is passed to the callback as the first parameter.

queue
  .append('task', (name) => `${name} complete`)
  .then((message) => console.log(message));

Callbacks can be functions, async functions, or promise-returning functions.

Items can be anything; primitive types, objects, instances, etc.

queue.append({wait: 1000}, async ({wait}) => {
  await new Promise((resolve) => setTimeout(resolve, wait));
  console.log(`waited ${wait}ms`);
});

Other feature examples:

See the examples directory for full usage.

Options

The Queue constructor accepts an options object. Options can also be changed with the instance setter methods.

const queue = new Queue({ concurrency: 5 });
queue.concurrency = 10;

concurrency

Maximum number of active items running at once (default: 1).

throttle

Minimum number of milliseconds between start of each item (default: 0).

API

append(item, callback)

Add an item and callback to the end of the queue.

prepend(item, callback)

Add an item and callback to the start of the queue.

has(item)

Returns true if item is queued (active or waiting).

get(item)

Returns the deferred promise for the item.

clear()

Empty the queue of waiting items. Deferred promises are rejected with a QueueError. Pending items are not cleared.

Notes

Inspired by plimit, p-throttle, and p-queue.