Qpass

Qpass is a lightweight promise-job queue for JavaScript/TypeScript. It runs jobs in cycles with configurable parallelism (batchSize) and reports progress after each cycle.

Platform support

• Node.js ESM (import) via qpass
• Node.js CommonJS (require) via qpass
• Browser bundlers (Vite/Webpack/Rollup) via qpass
• Browser script tag/global build via dist/qpass.js

Version is sourced from package.json at build time, so you only update it in one place.

Install

npm install qpass

Quick start

import Qpass from "qpass";

const queue = new Qpass({
    batchSize: 3,
    onProgress: ({ batchToProcess, itemsToProcess, completed }) => {
        console.log({ batchToProcess, itemsToProcess, completed });
    },
});

const jobs = [
    () => Promise.resolve("A"),
    () => Promise.resolve("B"),
    () => Promise.resolve("C"),
    () => Promise.resolve("D"),
];

queue.add(jobs);

Import by platform

Node.js ESM

import Qpass from "qpass";

Node.js CommonJS

const Qpass = require("qpass").default;

Browser bundler

import Qpass from "qpass";

Browser script tag (global)

Use the global build from your package output or CDN:

<script src="https://cdn.jsdelivr.net/npm/qpass/dist/qpass.js"></script>
<script>
    const queue = new Qpass();
</script>

API

new Qpass(options?)

new Qpass({
    breakWhenError?: boolean;
    batchSize?: number; // >= 1, default: 1
    onProgress?: (progress: {
        batchToProcess: number;
        itemsToProcess: number;
        completed: any[];
    }) => void;
})

Options

• batchSize (default 1): number of jobs to run in parallel per cycle.
• breakWhenError (default false): when true, queued jobs are cleared after an error is seen.
• onProgress: called after each cycle finishes.

add(jobs)

add(jobs: (() => Promise<any>)[] | (() => Promise<any>)): string | string[]

• Adds one or many jobs to the queue.
• Starts processing automatically.
• Returns the generated job id for a single job, or an array of ids for multiple jobs.

remove(id)

remove(id: string | number): boolean

• Removes a pending queued job by its id.
• Returns true when a queued job is removed, or false if the id was not found.
• Does not stop jobs already in progress.

terminate()

terminate(): void

• Clears all queued (not-yet-started) jobs.
• Already running jobs continue until they settle.

Progress callback behavior

onProgress receives:

• completed: results (or errors) from the cycle that just finished.
• itemsToProcess: queued jobs still waiting to start.
• batchToProcess: Math.ceil(itemsToProcess / batchSize).

Notes:

• Progress is reported per cycle, not per individual job completion.
• If you call add repeatedly (for example, inside a loop), the first cycle may be smaller than batchSize because processing starts immediately.

Error handling

Continue on error (breakWhenError: false)

const queue = new Qpass({
    breakWhenError: false,
    batchSize: 2,
    onProgress: ({ completed }) => {
        console.log(
            completed.map((x) => (x instanceof Error ? `Error: ${x.message}` : x))
        );
    },
});

queue.add([
    () => Promise.resolve("ok-1"),
    () => Promise.reject(new Error("failed-2")),
    () => Promise.resolve("ok-3"),
]);

Stop queueing after error (breakWhenError: true)

const queue = new Qpass({
    breakWhenError: true,
    batchSize: 3,
    onProgress: ({ itemsToProcess, completed }) => {
        console.log({ itemsToProcess, completed });
    },
});

queue.add([
    () => Promise.resolve("ok-1"),
    () => Promise.reject(new Error("failed-2")),
    () => Promise.resolve("ok-3"),
    () => Promise.resolve("queued-but-may-be-cleared"),
]);

With breakWhenError: true, Qpass clears jobs still waiting in the queue after an error is observed. Jobs already running in the same cycle still settle.

Practical pattern: queue all jobs at once

If you want predictable itemsToProcess values in onProgress, build the job array first and call add once:

const jobs = [];

for (let i = 1; i <= 14; i++) {
    jobs.push(() => Promise.resolve(`Job ${i}`));
}

queue.add(jobs);

License

ISC