Registry / devops / promise-blocking-queue

promise-blocking-queue

library1.0.0jsnpmunverified

Memory-optimized promise-based queue with concurrency control (v1.0.0, latest stable, active development). Designed to prevent Out Of Memory errors when processing large datasets from streams by providing a blocking enqueue that pauses the producer until a slot is available. Unlike p-queue or Bluebird.map, this queue integrates with Node.js streams to control backpressure without buffering all items in memory. Ships TypeScript types, supports Node >=14, and includes priority queuing. Good for rate-limiting async operations on large data.

devops

npm install promise-blocking-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROMISE-BLOCKING-Q

promise-blocking-queue

devopsjavascriptv1.0.0

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.

BlockingQueue

✓ import { BlockingQueue } from 'promise-blocking-queue'

✗ const BlockingQueue = require('promise-blocking-queue')

Default export is not available. Must use named import. CJS require will work but only if destructured: const { BlockingQueue } = require('promise-blocking-queue').

IQueueItem

✓ import type { IQueueItem } from 'promise-blocking-queue'

✗ const IQueueItem = require('promise-blocking-queue').IQueueItem

TypeScript only. For type imports use 'import type' to avoid runtime overhead.

BlockingQueueOptions

✓ import type { BlockingQueueOptions } from 'promise-blocking-queue'

✗ import { BlockingQueueOptions } from 'promise-blocking-queue'

TypeScript interface, not a runtime value. Use 'import type' to avoid compilation issues.

Creates a blocking queue with concurrency 2, enqueues 5 async tasks that simulate work, and waits for idle.

import { BlockingQueue } from 'promise-blocking-queue'; const queue = new BlockingQueue({ concurrency: 2 }); async function main() { const tasks = [1, 2, 3, 4, 5]; for (const item of tasks) { // enqueue will block if concurrency is reached await queue.enqueue(async () => { console.log(`Processing ${item}`); await new Promise(resolve => setTimeout(resolve, 1000)); console.log(`Finished ${item}`); return item * 2; }); } // Wait for all tasks to complete await queue.onIdle(); console.log('All done'); } main().catch(console.error);

Debug

Known issues

gotchaenqueue() returns a promise that resolves with the return value of the task, but if you don't await enqueue(), the task will still be added to the queue and may run out of order.

fix

Always await queue.enqueue() unless you intentionally want to fire-and-forget. Use await Promise.all() for multiple enqueues if needed.

affects: >=1.0.0

gotchaThe queue does not automatically handle stream backpressure. You must manually check stream.write() return value and handle 'drain' event as shown in the README.

fix

When writing to a writable stream within a task, check if stream.write() returns false (indicating backpressure), then wait for 'drain' event before enqueuing more tasks.

affects: >=1.0.0

deprecatedThe `options.priority` is not yet implemented in v1.0.0. It's a placeholder for future release.

fix

Do not rely on priority ordering. All tasks are processed in FIFO order for now.

affects: 1.0.0

gotchaUsing `new BlockingQueue()` without `concurrency` option defaults to `Infinity`, which behaves like an unbounded queue with no concurrency control.

fix

Always specify `concurrency` as a positive integer to enforce rate limiting. Example: `new BlockingQueue({ concurrency: 2 })`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: BlockingQueue is not a constructor

Using default import instead of named import.

fix

Use import { BlockingQueue } from 'promise-blocking-queue' instead of import BlockingQueue from 'promise-blocking-queue'.

Cannot find module 'promise-blocking-queue'

Package not installed or typo in package name.

fix

Run npm install promise-blocking-queue and ensure no spelling mistakes.

Property 'onIdle' does not exist on type 'BlockingQueue'

Using TypeScript with older version that doesn't have this method, or mistake in typings.

fix

Update to latest version (1.0.0). If still issue, check TypeScript version >=4.0.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/PruvoNet/promise-blocking-queue ↗

packagepromise-blocking-queue ↗

homepagehttps://github.com/PruvoNet/promise-blocking-queue#readme ↗