Using Node.js Worker Threads in a Type-Safe Way

1. Why untyped worker communication is dangerous

The worker_threads module communicates through postMessage() and the message event, both typed as any in Node's type definitions, because the module itself has no way to know what structure an application uses for its messages. Without additional typing, you lose every compile-time guarantee at this boundary, a typo in a message field name only surfaces at runtime, often in production.

What makes this especially tricky: because the main thread and worker run in separate V8 isolates, there is no shared type checking between the two sides, unlike normal function calls within the same process. A discriminated union type contract imported by both sides is the most reliable way to close that gap.

2. Defining a shared message contract

The key to type-safe worker communication is a jointly imported file with discriminated union types for every possible message in both directions. Each message gets a type field as a discriminator, so both sides can handle all cases exhaustively via a switch statement, and the compiler warns whenever a new message type was forgotten somewhere.

This contract file is imported both by the main-thread code and by the worker script, which guarantees both sides use exactly the same type definition instead of accidentally drifting apart, as can happen with two separately maintained interfaces.

// worker-protocol.ts -- imported by BOTH main.ts AND worker.ts
export type WorkerRequest =
  | { type: "hash"; id: number; input: string }
  | { type: "shutdown" };

export type WorkerResponse =
  | { type: "hash-result"; id: number; hash: string }
  | { type: "error"; id: number; message: string };

3. Building a typed worker wrapper

Instead of using raw postMessage() calls at every call site, it pays off to build a thin wrapper around Worker that is generic over the message type and internally casts on("message") to the discriminator type. That keeps caller code fully type-safe without every site having to repeat the cast.

This wrapper is also the right place to implement a promise-based request-response pattern: every outgoing message gets a unique ID, and an internal map from ID to promise resolver resolves the matching promise once the response with the same ID arrives.

import { Worker } from "node:worker_threads";
import type { WorkerRequest, WorkerResponse } from "./worker-protocol";

class TypedWorker {
  private worker: Worker;
  private pending = new Map<number, (r: WorkerResponse) => void>();

  constructor(scriptPath: string) {
    this.worker = new Worker(scriptPath);
    this.worker.on("message", (msg: WorkerResponse) => {
      if (msg.type === "hash-result" || msg.type === "error") {
        this.pending.get(msg.id)?.(msg);
        this.pending.delete(msg.id);
      }
    });
  }

  send(req: WorkerRequest): void {
    this.worker.postMessage(req);
  }

  request(req: Extract<WorkerRequest, { id: number }>): Promise<WorkerResponse> {
    return new Promise((resolve) => {
      this.pending.set(req.id, resolve);
      this.worker.postMessage(req);
    });
  }
}

4. Typing the worker script with the same contract

On the worker side, the script imports the same WorkerRequest and WorkerResponse types and handles incoming messages with an exhaustive switch. A never check in the default branch ensures the compiler throws an error as soon as the contract is extended with a new message type the worker does not yet handle.

This pattern makes protocol extensions safe: whoever adds a new variant to the union immediately gets compile errors at every spot the new case is not yet handled, instead of a message type silently ignored at runtime.

import { parentPort } from "node:worker_threads";
import type { WorkerRequest, WorkerResponse } from "./worker-protocol";
import { createHash } from "node:crypto";

parentPort?.on("message", (req: WorkerRequest) => {
  switch (req.type) {
    case "hash": {
      const hash = createHash("sha256").update(req.input).digest("hex");
      const response: WorkerResponse = { type: "hash-result", id: req.id, hash };
      parentPort?.postMessage(response);
      break;
    }
    case "shutdown":
      process.exit(0);
    default: {
      const _exhaustive: never = req;
      throw new Error(`Unknown message type: ${JSON.stringify(_exhaustive)}`);
    }
  }
});

5. A generic worker pool for parallel processing

For recurring CPU-intensive tasks, a worker pool pays off: it manages a fixed number of worker threads and distributes incoming tasks to idle workers, instead of spawning a new thread per task. Creating a worker thread costs several milliseconds, which quickly becomes a bottleneck with many small tasks.

A generic pool, parameterized over request and response types, can be reused across different worker scripts as long as each script follows the same discriminated-union contract approach. Round-robin or least-busy task distribution stays independent of the concrete message type.

import { Worker } from "node:worker_threads";

class WorkerPool<Req extends { id: number }, Res extends { id: number }> {
  private workers: Worker[] = [];
  private nextIndex = 0;

  constructor(scriptPath: string, size: number) {
    for (let i = 0; i < size; i++) {
      this.workers.push(new Worker(scriptPath));
    }
  }

  submit(req: Req): Promise<Res> {
    const worker = this.workers[this.nextIndex];
    this.nextIndex = (this.nextIndex + 1) % this.workers.length;
    return new Promise((resolve) => {
      const handler = (msg: Res) => {
        if (msg.id === req.id) {
          worker.off("message", handler);
          resolve(msg);
        }
      };
      worker.on("message", handler);
      worker.postMessage(req);
    });
  }
}

6. SharedArrayBuffer for memory-heavy data exchange

For large numeric datasets, postMessage() is inefficient, because Node uses the structured clone algorithm, which copies the data instead of sharing it. SharedArrayBuffer combined with typed arrays like Float64Array allows true shared memory access between the main thread and a worker, with no copying.

TypeScript only types SharedArrayBuffer structurally, real type safety comes from both sides using the same typed array view over the same buffer. With concurrent write access from multiple threads, Atomics operations are needed to avoid race conditions, and TypeScript cannot enforce that synchronization, only the shape of the data.

// Main thread: create the buffer and hand it to the worker
const sab = new SharedArrayBuffer(8 * 1024);
const view = new Float64Array(sab);
worker.postMessage({ type: "compute", buffer: sab });

// Worker: the same memory region, no copy
parentPort?.on("message", (msg: { type: "compute"; buffer: SharedArrayBuffer }) => {
  const workerView = new Float64Array(msg.buffer);
  Atomics.add(workerView, 0, 1); // safe atomic write
});

7. Passing errors across the thread boundary in a type-safe way

Errors thrown inside a worker do not automatically cross the thread boundary as an Error instance, the worker object's error event delivers a serialized object that is not guaranteed to contain every property of the original error class. For structured error handling it is better to have the worker explicitly return errors as a typed response message instead of throwing them.

A separate ErrorResponse type in the protocol, with fields for an error message, an error code, and optionally a stack trace string, makes error handling in the main thread just as type-safe as success responses, instead of relying on the generic, weakly typed error event.

8. Worker lifecycle: startup, termination and resource cleanup

Worker threads have to be explicitly terminated with worker.terminate(), otherwise the open thread keeps the Node process alive even when the main application is logically done. In a worker pool it matters to cleanly terminate all workers on application shutdown, ideally through a central shutdown handler.

For production use it also pays off to add a health check mechanism that detects a stuck worker, for example via a timeout on pending requests, and restarts the affected worker instead of letting a single broken thread block the entire pool.

9. When worker threads pay off over other approaches

Worker Threads suit CPU-bound work like hashing, image processing, or complex computations, not I/O-bound tasks that the normal event loop already handles concurrently and efficiently. For I/O-heavy concurrency, plain promises are usually enough, worker threads there only add unnecessary overhead from thread creation and serialization.

With a jointly imported discriminated message contract, a typed wrapper, and a generic pool, the thread boundary can be treated as if it were a normal, type-safe function interface, which structurally eliminates the most common source of bugs in worker thread code: undocumented message formats.

10. Summary

11. FAQ: Worker Threads