Promise-Queue

Common errors

• TypeError: PromiseQueue is not a constructor

  cause 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.

  cause 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 ...

  cause 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.

Warnings

• gotcha Forgetting 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.
• gotcha Tasks 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.
• gotcha The `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.

Install

• npm install sb-promise-queue npm
• yarn add sb-promise-queue yarn
• pnpm add sb-promise-queue pnpm

Imports

• PromiseQueue
  wrong:

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

  correct:

  import { PromiseQueue } from '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
  wrong:

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

  correct:

  import { type Options, PromiseQueue } 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.

Quickstart

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();