👩‍🚒 Promifire

Promifire runs deferred tasks in sequence 🔥 or in parallel 💥 while keeping metadata associated with each result.

📦 Installation

npm install promifire

Promifire is an ES module and requires Node.js 18 or newer.

🔧 Usage

Pass functions to add(), not promises that have already started. A task may return either a value or a promise.

import Promifire from 'promifire';

const wait = (value, delay) => () => new Promise(resolve => {
    setTimeout(() => resolve(value), delay);
});

🔥 Sequence

Tasks start one at a time. The next task starts after the previous task and callback have completed.

const promifire = new Promifire();

promifire.add(wait(1, 1500), { id: 'slow' });
promifire.add(wait(3, 1000), { id: 'fast' });

const results = await promifire.sequence(async (response, data) => {
    console.log(response, data);
});

// 1 { id: 'slow' }
// 3 { id: 'fast' }
// results: [[1, { id: 'slow' }], [3, { id: 'fast' }]]

💥 Parallel

Set concurrency in the constructor to the maximum number of operations that may run at once. Each operation includes its task and callback. Omit it to start the entire queue together. Results always preserve insertion order.

const promifire = new Promifire({ concurrency: 2 });

promifire.add(wait(1, 1500), { id: 'slow' });
promifire.add(wait(3, 1000), { id: 'fast' });

const results = await promifire.parallel(async (response, data) => {
    console.log(response, data);
});

// 3 { id: 'fast' }
// 1 { id: 'slow' }
// results: [[1, { id: 'slow' }], [3, { id: 'fast' }]]

Live queue

Use enqueue() when tasks arrive over time and should start automatically as concurrency slots become available. It returns a promise for that task's response.

const queue = new Promifire({ concurrency: 2 });

const first = queue.enqueue(() => fetch('/users/1'));
const second = queue.enqueue(() => fetch('/users/2'));
const third = queue.enqueue(() => fetch('/users/3'));

const responses = await Promise.all([first, second, third]);
await queue.onIdle();

Metadata and an async callback are optional:

const response = await queue.enqueue(
    () => fetch('/users/1'),
    { id: 1 },
    async (result, data) => {
        console.log(result.status, data.id);
    }
);

The queue can be created paused or controlled while it is running:

const queue = new Promifire({ concurrency: 2, autoStart: false });

const job = queue.enqueue(() => fetch('/reports'));

console.log(queue.size);      // Waiting tasks
console.log(queue.pending);   // Running tasks
console.log(queue.isPaused);  // true

queue.start();
queue.pause();
queue.start();

await job;
await queue.onIdle();

pause() lets active operations finish and prevents queued operations from starting. start() resumes the queue and returns the Promifire instance. onIdle() resolves when no queued or active work remains.

clear() rejects every waiting task with QueueClearedError; active tasks continue:

import Promifire, { QueueClearedError } from 'promifire';

const queue = new Promifire({ autoStart: false });
const job = queue.enqueue(() => fetch('/reports'));

queue.clear();

try {
    await job;
} catch (error) {
    if (error instanceof QueueClearedError) {
        console.log('The queued task was cleared');
    }
}

An enqueued task rejection only rejects its own promise. Other queued tasks continue normally.

Timeouts

Set a timeout in milliseconds for every batch or queued operation. Timing begins when the task starts, not while it waits in the live queue, and includes its callback.

import Promifire, { TaskTimeoutError } from 'promifire';

const queue = new Promifire({
    concurrency: 2,
    timeout: 10_000
});

try {
    await queue.enqueue(() => fetch('/slow-report'));
} catch (error) {
    if (error instanceof TaskTimeoutError) {
        console.log(`Timed out after ${error.timeout} ms`);
    }
}

After a queued operation times out, its slot is released and the next task may start. A timeout rejects the Promifire operation but cannot stop underlying work by itself. Tasks that need cancellation must implement it separately, for example with AbortController.

An enqueued task can override the constructor timeout with a fourth argument:

await queue.enqueue(
    () => processMessage(args),
    args,
    null,
    { timeout: args.timeoutMs ?? 10_000 }
);

Omitting timeout inherits the constructor value. Passing { timeout: undefined } explicitly disables the timeout for that task.

Batch and error behavior

• add() returns the Promifire instance, so calls can be chained.
• sequence() and parallel() consume the tasks that were queued when the call began.
• Tasks added during a run remain queued for the next call.
• An empty queue resolves to [].
• Task and callback errors reject the returned promise.
• The constructor timeout applies to both batch tasks and live queue tasks.
• parallel() rejects as soon as one operation fails. Operations that already started continue, but pending operations do not start.
• Batch execution and the live queue use independent schedulers. Use separate Promifire instances if both modes need to run simultaneously under one combined concurrency limit.

Benchmarks

Run the deterministic stress suite and the local benchmark with:

npm test
npm run benchmark

The benchmark warms up each scenario and reports the median of five samples for native Promise.all, unlimited Promifire batches, concurrency-limited batches, and the live queue with and without timeout enforcement. Results depend on the machine and Node.js version.

🤝 Contributing

Bug reports and pull requests are welcome in the GitHub repository.

📄 License

MIT © Martin Clasen