@henrygd/queue

Tiny async queue with concurrency control. Like p-limit or fastq, but smaller and faster. See comparisons and benchmarks below.

Works with:

Usage

Create a queue with the newQueue function. Then add async functions - or promise returning functions - to your queue with the add method.

You can use queue.done() to wait for the queue to be empty.

import { newQueue } from '@henrygd/queue'

// create a new queue with a concurrency of 2
const queue = newQueue(2)

const pokemon = ['ditto', 'hitmonlee', 'pidgeot', 'poliwhirl', 'golem', 'charizard']

for (const name of pokemon) {
    queue.add(async () => {
        const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${name}`)
        const json = await res.json()
        console.log(`${json.name}: ${json.height * 10}cm | ${json.weight / 10}kg`)
    })
}

console.log('running')
await queue.done()
console.log('done')

The return value of queue.add is the same as the return value of the supplied function.

const res = await queue.add(() => fetch('https://pokeapi.co/api/v2/pokemon'))
console.log(res.ok, res.status, res.headers)

[!TIP] If you need support for Node's AsyncLocalStorage, import @henrygd/queue/async-storage instead.

Queue interface

/** Add an async function / promise wrapper to the queue */
queue.add<T>(promiseFunction: () => PromiseLike<T>): Promise<T>
/** Returns a promise that resolves when the queue is empty */
queue.done(): Promise<void>
/** Empties the queue (active promises are not cancelled) */
queue.clear(): void
/** Returns the number of promises currently running */
queue.active(): number
/** Returns the total number of promises in the queue */
queue.size(): number

Comparisons and benchmarks

Note on benchmarks

Each operation tests how quickly the queue can resolve 1,000 (browser) or 5,000 (all others) async functions. The function just increments a counter.[^benchmark]

All libraries run the exact same test, so p-limit and promise-queue, which lack a promise that resolves when the queue is empty, are not penalized by having to use Promise.all.

Browser benchmark

This test was run in Chromium. Chrome and Edge are the same. Firefox and Safari are slower and closer, with @henrygd/queue edging out promise-queue, then a small gap to fastq.

You can run or tweak for yourself here: https://jsbm.dev/8FxNa8pSMHCX2

Node.js benchmarks

p-limit is very slow because it uses AsyncResource.bind on every run, which is much faster in Bun than in Node or Deno.

Ryzen 7 6800H | 32GB RAM | Node.js 22.3.0

Ryzen 5 4500U | 8GB RAM | Node.js 22.3.0

Deno benchmarks

Ryzen 7 6800H | 32GB RAM | Deno 1.44.4

Bun benchmarks

Ryzen 7 6800H | 32GB RAM | Bun 1.1.16

Ryzen 5 4500U | 8GB RAM | Bun 1.1.16

Cloudflare Workers benchmark

Uses oha to make 1,000 requests to each worker. Measures creation time in addition to throughput, as a new queue is made for each request.

This was run locally using Wrangler on a Ryzen 7 6800H laptop. Wrangler uses the same workerd runtime as workers deployed to Cloudflare, so the relative difference should be accurate. Here's the repository for this benchmark.

Worth noting that promise-queue shot up by nearly 300 req/s after I made the tests uniform and removed its use of Promise.all to wait for the queue to be done. I ended up adding a check in every function, which is a bit convoluted but works. Much easier when you have the option to use a promise like queue.done().

Real world examples

henrygd/optimize - Uses @henrygd/queue to parallelize image optimization jobs.

License

MIT license

[^benchmark]: In reality, you may not be running so many jobs at once, and your jobs will take much longer to resolve. So performance will depend more on the jobs themselves.