Registry / http-networking / sb-promise-queue

sb-promise-queue

library2.1.1jsnpmunverified

sb-promise-queue is a lightweight JavaScript/TypeScript utility library designed to manage and control the concurrency of asynchronous operations using a promise-based queue. Its current stable version is 2.1.1. It allows developers to specify a maximum number of promises that can run simultaneously, preventing resource exhaustion or rate-limiting issues. Key differentiators include its minimalistic and intuitive API, built-in TypeScript type definitions for enhanced developer experience, and clear methods such as `add`, `onIdle`, and `waitTillIdle` for effective task flow management. This library is particularly useful for scenarios requiring controlled execution of potentially resource-intensive async tasks, like API calls or data processing, ensuring stability and performance. While a specific release cadence is not explicitly stated, as a focused utility, updates are generally driven by bug fixes or minor enhancements rather than frequent feature additions.

http-networking workflow

npm install sb-promise-queue

github ↗package ↗

INSTALL

IMPORT

SIG · SB-PROMISE-QUEUE

sb-promise-queue

http-networkingjavascriptv2.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

PromiseQueue

✓ import { PromiseQueue } from 'sb-promise-queue';

✗ const PromiseQueue = require('sb-promise-queue');

The library primarily uses named exports. For modern Node.js and TypeScript projects, ES module `import` syntax is recommended. Direct CommonJS `require` may not work as expected in an ES module context.

Options

✓ import { type Options, PromiseQueue } from 'sb-promise-queue';

✗ import { Options } from 'sb-promise-queue';

When importing types like `Options` in TypeScript, use `import type` for clarity and to ensure it's removed during compilation, preventing potential runtime issues in environments that don't support type imports natively.

PromiseQueue (CommonJS fallback)

✓ const { PromiseQueue } = require('sb-promise-queue');

For legacy CommonJS environments (e.g., older Node.js versions or specific build setups), named exports can be destructured from the `require` call. However, this is not the primary recommended import method for new projects.

Demonstrates initializing a `PromiseQueue` with a specified concurrency, adding multiple asynchronous tasks, and then waiting for all tasks to complete before proceeding, logging their start and end.

import { PromiseQueue } from 'sb-promise-queue'; async function runConcurrentTasks() { const queue = new PromiseQueue({ concurrency: 3 }); // Allow 3 tasks to run concurrently const taskCount = 10; const results: string[] = []; console.log(`Starting ${taskCount} tasks with concurrency ${queue.options.concurrency}...`); for (let i = 1; i <= taskCount; i++) { queue.add(async () => { console.log(` [Task ${i}] Started.`); // Simulate an async operation with varying duration await new Promise(resolve => setTimeout(resolve, Math.random() * 1000 + 500)); const result = `Task ${i} completed.`; console.log(` [Task ${i}] Finished.`); results.push(result); return result; }); } // Wait for all tasks in the queue to finish await queue.waitTillIdle(); console.log('All tasks finished!'); console.log('Results:', results); } runConcurrentTasks();

Debug

Known issues

gotchaForgetting to `await queue.waitTillIdle()` will cause your script or subsequent logic to execute before all queued asynchronous tasks have completed, potentially leading to incomplete operations or race conditions.

fix

Always ensure to `await queue.waitTillIdle()` when you need a guarantee that all tasks in the queue have finished their execution before proceeding with dependent code.

affects: >=1.0.0

gotchaTasks added to the queue via `add(callback)` execute the `callback` function. If the promise returned by `callback` rejects and this rejection is not handled internally within the callback, it will result in an unhandled promise rejection error that might not halt other tasks but will break your process if unhandled globally.

fix

Always wrap the asynchronous logic inside your `add` callback with `try...catch` blocks or attach a `.catch()` handler to any promises returned, ensuring robust error handling for individual tasks.

affects: >=1.0.0

gotchaThe `concurrency` option limits the number of *currently running* promises, not the total number of tasks that can be added to the queue. Adding an extremely large number of tasks (e.g., millions) to a queue with very low concurrency can lead to high memory consumption as all tasks await their turn.

fix

For scenarios involving an exceptionally high number of tasks, consider implementing a mechanism to batch your task additions to the queue, or monitor memory usage closely to prevent resource exhaustion.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: PromiseQueue is not a constructor

Attempting to use `new PromiseQueue()` without correctly importing it from the module, or when the `require` call in a CommonJS context did not properly destructure the named export.

fix

Ensure you are using the correct ES module named import: `import { PromiseQueue } from 'sb-promise-queue';`. If in a CommonJS environment, use `const { PromiseQueue } = require('sb-promise-queue');`.

UnhandledPromiseRejectionWarning: Unhandled promise rejection.

An asynchronous task (a promise) within a callback added to the queue rejected, and this rejection was not explicitly caught by a `.catch()` block or `try...catch` statement within that specific task's execution.

fix

Modify the `async` callback passed to `queue.add()` to include error handling. For example: `queue.add(async () => { try { await someAsyncOp(); } catch (error) { console.error('Task failed:', error); } });`

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'sb-promise-queue' imported from ...

The package `sb-promise-queue` is either not installed, or your project's module resolution settings (e.g., for ES modules vs. CommonJS) are incorrect.

fix

First, ensure the package is installed: `npm install sb-promise-queue`. If the error persists in an ES module environment (`"type": "module"` in `package.json`), verify your Node.js version supports ES modules or check for incorrect `tsconfig.json` module settings if using TypeScript.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/steelbrain/promise-queue ↗

packagehttps://www.npmjs.com/package/sb-promise-queue ↗