When Node.js Worker Threads Help a Build Pipeline

A catalogue import can spend most of its time waiting for data, then spend another conspicuous stretch processing that data on one busy CPU core. Those are different delays. Adding workers to the first one may simply give the machine more elaborate ways to wait.
For the second, worker threads are worth investigating. They let us move JavaScript computation onto separate threads, provided the work is large enough to pay for getting it there.
Node's worker API became stable in Node 12.11, so it is already stable in the Node 12.13 release I'm discussing here. Older examples describing it as experimental need that version context. Stability doesn't, however, tell us whether our particular build will finish sooner.
Find the Expensive Stage First
Before changing the execution model, I want separate timings for fetching, parsing, transforming, and writing the catalogue. If the expensive stage is a network request, moving it into a worker won't persuade the other server to answer faster.
Workers are particularly interesting when the expensive stage is JavaScript computation: repeated transformations, analysis, or calculations over independent records. Node already has asynchronous I/O facilities, and some operations use libuv's internal worker pool. That pool is separate from the JavaScript workers we create ourselves. Increasing UV_THREADPOOL_SIZE doesn't create more of these workers.
My event loop guide explains why wrapping a long calculation in a promise doesn't make the calculation leave its current thread. Promise.all() coordinates promises; it doesn't divide an ordinary JavaScript loop between CPU cores.
There may also be a simpler improvement. Avoiding a repeated parse, caching an unchanged result, or removing unnecessary work can beat doing the same wasteful thing on two cores. I would check those before acquiring a queue to maintain.
Compare the Same Work in Different Places
For a useful experiment, give every mode identical inputs, validation, and output requirements. A synthetic catalogue is fine if we label it honestly and retain the generator. It lets us increase computation without changing the correctness test.
I would compare four arrangements:
- Run each transform synchronously on the main thread.
- Create a worker for each job, then terminate it.
- Reuse one worker for successive jobs.
- Reuse a small pool, with a fixed upper limit on workers.
The single reusable worker matters. It separates the benefit of avoiding startup from the benefit of parallel execution. Otherwise, a comparison can credit two cores for an improvement that mostly came from stopping the repeated construction of workers.
Keep the output in catalogue order even when jobs finish in a different order. Give each job an identifier, match its reply, and compare the complete ordered output with the synchronous reference. A faster build which attaches the wrong calculation to a product has rather missed the assignment.
Use at least two input shapes: small records with little data to copy, and larger records where moving bytes might become significant. Increase the work per record in each. The interesting result is where a reusable pool starts paying for itself, rather than one carefully chosen workload on which it looks wonderful.
Decide Who Owns the Input
A worker receives messages rather than a direct reference to the caller's ordinary JavaScript objects. The Node 12.13 worker documentation describes cloning and transferring data across that boundary.
Here is a deliberately small worker handler, saved as catalogue-worker.js:
const { parentPort } = require('worker_threads');
parentPort.on('message', ({ id, values }) => {
const total = values.reduce((sum, value) => sum + value, 0);
parentPort.postMessage({ id, total });
});The arithmetic is intentionally too trivial to justify a worker. It makes the message contract visible without hiding it behind a converter. A real comparison needs the actual expensive transform.
From the calling thread, we can explicitly transfer a privately owned buffer:
const values = new Uint32Array([10, 20, 30]);
worker.postMessage({ id: 17, values }, [values.buffer]);
// Prints 0: this thread no longer owns the buffer.
console.log(values.byteLength);Here, worker is the Worker instance created for that file, with response and failure handlers attached before submitting work. Omitting the transfer list clones the input instead. Transferring detaches the caller's buffer, including other views onto it. It isn't a free copy which leaves both sides with the original data.
I prefer a clear ownership rule at submission: once accepted, the caller must leave the input alone until the job settles. If a queued job transfers later, the caller must not mutate it in the meantime. If admission is rejected, the caller should retain its input. Those details are much easier to establish before somebody adds a retry.
A Worker Limit Also Needs a Queue Limit
Two workers don't bound memory if the caller can submit a million jobs behind them. Limit waiting jobs and retained input bytes, and define what happens when either limit is reached. An explicit rejection lets the producer pause or reduce its batch size. An indefinitely growing array just postpones the conversation.
Measure queue time separately from computation. A job can execute quickly once assigned and still spend most of its life waiting for a worker. Record startup, time spent posting the message, completion latency, and total batch duration too. Time spent posting is useful evidence about synchronous dispatch cost; it isn't a complete measurement of every allocation or byte moving inside the runtime.
Run cold and warm comparisons. Include startup when the build creates a pool for one short stage; exclude earlier startup only when measuring work that genuinely reuses an existing pool. Record the Node version, hardware, pool size, input sizes, and repetitions alongside the observations. Other build processes competing for the same cores belong in the interpretation as well.
Every Accepted Job Needs an Ending
A worker can throw, exit before replying, or remain alive without answering. A promise waiting only for a successful message handles none of those cases. Even a zero exit code doesn't prove that the expected result arrived.
For a small build tool, I'd start with a conservative policy: a worker failure stops admission, rejects active and queued work, and terminates the remaining workers. Shutdown must also settle pending promises. A deadline prevents a worker which never replies from holding the build open indefinitely.
That policy can mean repeating useful work, but it is easier to reason about than automatic replacement and retry. A pure transform can be repeated with fresh input after reporting the failure. A job which has written a file or called another service needs a separate decision about repeating its side effects. Transferred data may be lost with the worker, so recovery needs an original source or a way to regenerate it.
Wrapping Up
My earlier look at build tools makes the case for keeping the build understandable. Worker threads fit that principle when a measured CPU stage earns the extra machinery.
Keep the synchronous reference. Compare identical output, include the costs the actual build will pay, and test worker loss before trusting the happy path. If a small reusable pool improves the whole stage enough to justify its ownership and failure rules, use it. If the transform is already cheap, leave it where it is.
Postscript
November 2026: I've added my worker‑pool lab with two synthetic catalogue shapes, cold and warm comparisons, and deliberate queue, transfer, and worker‑failure checks. I've tested it on Node 22.23.5 and 24.14.0; the download records the actual runtime, hardware, and measurement dates. It is a current companion to the Node 12 discussion above, not a preserved 2019 benchmark. On my retained run, tiny jobs favoured synchronous execution, whilst heavier repeated work benefited from two reusable workers. Run the comparison with your own transform before borrowing the conclusion.