Skip to main content

Built and signed on GitHub Actions

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

This package works with Node.js, Deno, BrowsersIt is unknown whether this package works with Bun, Cloudflare Workers
JSR Score
100%
Published
3 months ago (0.12.0)

🦥 Carriageway

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

Usage

Add dependency from JSR: @dbushell/carriageway

Deno imports from mod.ts. Other runtimes import from index.min.js (Bun, Node, web browsers). Node requires --js-promise-withresolvers flag.

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.


MIT License | Copyright © 2024 David Bushell

Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @dbushell/carriageway

Import symbol

import * as mod from "@dbushell/carriageway";

Add Package

npx jsr add @dbushell/carriageway

Import symbol

import * as mod from "@dbushell/carriageway";

Add Package

yarn dlx jsr add @dbushell/carriageway

Import symbol

import * as mod from "@dbushell/carriageway";

Add Package

pnpm dlx jsr add @dbushell/carriageway

Import symbol

import * as mod from "@dbushell/carriageway";

Add Package

bunx jsr add @dbushell/carriageway

Import symbol

import * as mod from "@dbushell/carriageway";