Node.js worker threads let you run CPU-heavy tasks without blocking the event loop

// worker.ts — runs in a separate thread
import { workerData, parentPort } from 'worker_threads';

// This is the CPU-heavy work
function generateReport(data: ReportData): Buffer {
  // ... expensive PDF generation
  return pdfBuffer;
}

const result = generateReport(workerData);
parentPort!.postMessage({ result });

// main.ts — creates workers from the main thread
import { Worker } from 'worker_threads';
import path from 'path';

function runWorker(
  workerFile: string,
  data: unknown
): Promise {
  return new Promise((resolve, reject) => {
    const worker = new Worker(path.resolve(workerFile), {
      workerData: data,
    });

    worker.on('message', resolve);
    worker.on('error', reject);
    worker.on('exit', (code) => {
      if (code !== 0) {
        reject(new Error(`Worker exited with code ${code}`));
      }
    });
  });
}

// Usage in an Express/Fastify handler
app.post('/reports', async (req, res) => {
  // This does NOT block the event loop — returns immediately
  const pdfBuffer = await runWorker(
    './workers/report-worker.js',
    req.body
  );
  
  res.setHeader('Content-Type', 'application/pdf');
  res.send(pdfBuffer);
});

import { Worker } from 'worker_threads';
import path from 'path';

interface WorkerTask {
  resolve: (value: T) => void;
  reject: (reason: unknown) => void;
  data: unknown;
}

class WorkerPool {
  private workers: Worker[] = [];
  private freeWorkers: Worker[] = [];
  private queue: WorkerTask[] = [];

  constructor(
    private workerFile: string,
    private size: number = 4,
  ) {
    for (let i = 0; i < size; i++) {
      this.addWorker();
    }
  }

  private addWorker() {
    const worker = new Worker(path.resolve(this.workerFile));
    
    worker.on('message', (result: T) => {
      const task = this.currentTasks.get(worker);
      if (task) {
        this.currentTasks.delete(worker);
        task.resolve(result);
      }
      
      // Take next task from queue
      if (this.queue.length > 0) {
        const next = this.queue.shift()!;
        this.runTask(worker, next);
      } else {
        this.freeWorkers.push(worker);
      }
    });

    worker.on('error', (err) => {
      const task = this.currentTasks.get(worker);
      if (task) task.reject(err);
    });

    this.workers.push(worker);
    this.freeWorkers.push(worker);
  }

  private currentTasks = new Map>();

  private runTask(worker: Worker, task: WorkerTask) {
    this.currentTasks.set(worker, task);
    worker.postMessage(task.data);
  }

  run(data: unknown): Promise {
    return new Promise((resolve, reject) => {
      const task = { resolve, reject, data };
      
      if (this.freeWorkers.length > 0) {
        const worker = this.freeWorkers.pop()!;
        this.runTask(worker, task);
      } else {
        this.queue.push(task);
      }
    });
  }

  async terminate() {
    await Promise.all(this.workers.map(w => w.terminate()));
  }
}

// Create a pool of 4 report workers at startup
const reportPool = new WorkerPool('./workers/report-worker.js', 4);

// Concurrent PDF generation — all handled by the pool
const reports = await Promise.all([
  reportPool.run(report1Data),
  reportPool.run(report2Data),
  reportPool.run(report3Data),
]);

// For high-performance use cases, share memory between threads
// instead of copying data via postMessage

// main.ts
const sharedBuffer = new SharedArrayBuffer(4 * 1024 * 1024); // 4MB
const sharedArray = new Float64Array(sharedBuffer);

// Fill with data in the main thread
for (let i = 0; i < sharedArray.length; i++) {
  sharedArray[i] = Math.random();
}

// Pass the buffer reference (not a copy) to the worker
const worker = new Worker('./compute-worker.js', {
  workerData: { buffer: sharedBuffer, length: sharedArray.length }
});

// compute-worker.ts
import { workerData, parentPort } from 'worker_threads';

const array = new Float64Array(workerData.buffer);

// Both threads see the same memory — no data copying
let sum = 0;
for (let i = 0; i < workerData.length; i++) {
  sum += array[i];
}

parentPort!.postMessage({ sum });