Registry / devops / async-await-queue

async-await-queue

library2.1.4jsnpmunverified

Zero-dependency promise-based priority queues for throttling, rate- and concurrency limiting of async tasks in Node.js and browsers. v2.1.4 (stable, actively maintained) provides O(log n) scheduling for numerous jobs with multiple priority levels. Distinguishes from other queues by full async/await compatibility, guaranteed order preservation, and never waking contexts that won't run. Suitable for rate-limiting API calls, controlling concurrent async loops, and parallelizing downloads. Ships TypeScript definitions and supports both ESM and CJS.

devops

npm install async-await-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ASYNC-AWAIT-QUEUE

async-await-queue

devopsjavascriptv2.1.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Queue

✓ import { Queue } from 'async-await-queue'

✗ import Queue from 'async-await-queue'

Named export only; default import will not work.

Queue

✓ const { Queue } = require('async-await-queue')

✗ const Queue = require('async-await-queue')

CJS destructure required; module.exports is an object.

Queue

✓ import type { Queue } from 'async-await-queue'

✗ import { Queue } from 'async-await-queue' // at runtime causes error if only type needed

Use import type for TypeScript type-only imports to avoid runtime overhead.

Shows creating a Queue with concurrency 2 and 100ms spacing, using wait/end for tasks, and flushing.

import { Queue } from 'async-await-queue'; const queue = new Queue(2, 100); // max 2 concurrent, min 100ms between starts async function limitedDownload(url: string): Promise<void> { const id = Symbol(); await queue.wait(id, 0); // priority 0 (higher = runs later) try { await fetch(url); } finally { queue.end(id); } } async function downloadAll(): Promise<void> { const urls = ['https://example.com', 'https://httpbin.org/get']; await Promise.all(urls.map(u => limitedDownload(u))); await queue.flush(); } downloadAll().catch(console.error);

Debug

Known issues

gotchaQueue.end() must be called exactly once per task, or the queue will stall. Uncaught exceptions in the task must be handled with .catch() before .finally() calling end().

fix

Always use .finally(() => queue.end(id)) or wrap in try/finally.

affects: >=1.0.0

gotchaPriority values: higher numeric priority runs later (lower runs first). This is counterintuitive compared to typical priority systems.

fix

Use negative values for higher priority: e.g., -1 runs before 0.

affects: >=1.0.0

breakingIn v1.x, the Queue constructor accepted (concurrency, delay) as (Number, Number). In v2.x, signature unchanged but internal behavior may differ; ensure upgrade path.

fix

Review changelog; v2 still uses same constructor. No code change needed but test thoroughly.

affects: >=2.0.0

gotchaNew style API Queue.run() introduced in v1.2 is safer but less flexible: it wraps the task in a promise and calls wait/end automatically, but does not support priority per task.

fix

Use run() for simple concurrency limiting; use wait/end for priority support.

affects: >=1.2.0

gotchaThe queue keeps references to Promise resolve() functions. This is unusual and can cause memory leaks if tasks are not ended.

fix

Always ensure every wait() is paired with an end() call, even on error.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: queue.wait is not a function

Attempting to use default import instead of named import: `import Queue from 'async-await-queue'`

fix

Use named import: `import { Queue } from 'async-await-queue'`

Error: Queue.end() called with unknown id

Calling end() with an id that was not provided to wait(), or calling end() twice

fix

Ensure each wait() call uses a unique Symbol or string, and end() is called exactly once per id.

UnhandledPromiseRejectionWarning: [object Undefined]

Async task inside queue.reject() (or similar) without catching rejection

fix

Add .catch() handler to the promise returned from the task, or use try/catch inside.

Upgrade

Version history

2.1.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mmomtchev/Queue ↗

packageasync-await-queue ↗

homepagehttps://github.com/mmomtchev/Queue ↗