Child Processes

import { spawn } from 'node:child_process';

/**
 * Run a command without a shell and collect bounded output.
 * Rejects when the process cannot start (ENOENT, EACCES), is aborted, or prints too much.
 */
export function run(command, args = [], { maxBytes = 1024 * 1024, signal, ...options } = {}) {
  return new Promise((resolve, reject) => {
    const child = spawn(command, args, { ...options, signal });
    const out = [];
    const err = [];
    let size = 0;

    const collect = (list) => (chunk) => {
      size += chunk.length;
      if (size > maxBytes) {
        child.kill();
        reject(new RangeError(`output of ${command} exceeded ${maxBytes} bytes`));
        return;
      }
      list.push(chunk);
    };
    child.stdout.on('data', collect(out));
    child.stderr.on('data', collect(err));

    child.once('error', reject); // spawn failure, kill failure, AbortError
    child.once('close', (code, sig) => {
      resolve({
        code,
        signal: sig,
        stdout: Buffer.concat(out).toString('utf8'),
        stderr: Buffer.concat(err).toString('utf8'),
      });
    });
  });
}

if (import.meta.main) {
  console.log(await run(process.execPath, ['-p', '6 * 7']));
  console.log(await run(process.execPath, ['-e', 'process.exit(3)']));
  await run('definitely-not-a-command').catch((err) => console.log(err.code, err.syscall, err.path));
  await run(process.execPath, ['-e', 'for (;;) process.stdout.write("x".repeat(1000))'], { maxBytes: 100_000 })
    .catch((err) => console.log(err.name, err.message));
}

{ code: 0, signal: null, stdout: '42\n', stderr: '' }
{ code: 3, signal: null, stdout: '', stderr: '' }
ENOENT spawn definitely-not-a-command definitely-not-a-command
RangeError output of /Users/<you>/.nvm/versions/node/v26.10.0/bin/node exceeded 100000 bytes

import { spawn } from 'node:child_process';
import { once } from 'node:events';

// DEP0190: args plus shell: the array is only joined with spaces, never escaped.
const child = spawn('echo', ['first', '&& echo', 'second'], { shell: true, stdio: ['ignore', 'pipe', 'inherit'] });
child.stdout.setEncoding('utf8').on('data', (d) => console.log(JSON.stringify(d)));
await once(child, 'close');

(node:50751) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
"first\nsecond\n"

import { exec, spawn } from 'node:child_process';

// Runs through cmd.exe: only for fixed, trusted file names and arguments.
exec('my.bat', (err, stdout, stderr) => { /* ... */ });

// Or start cmd.exe directly and pass the file as an argument.
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

// A script name with spaces must be quoted.
exec('"my script.cmd" a b', (err, stdout, stderr) => { /* ... */ });

import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { setTimeout as sleep } from 'node:timers/promises';

// sh -c starts a grandchild. kill() reaches only the shell; the grandchild survives.
const grandchildScript = `setInterval(() => {}, 1000); console.log(process.pid)`;
const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };

async function launch(options) {
  const child = spawn('sh', ['-c', `${JSON.stringify(process.execPath)} -e '${grandchildScript}' & wait`], { stdio: ['ignore', 'pipe', 'inherit'], ...options });
  const [chunk] = await once(child.stdout, 'data');
  return { child, grandchildPid: Number(chunk.toString()) };
}

// A. Plain kill(): the shell dies, the grandchild lives on.
{
  const { child, grandchildPid } = await launch({});
  child.kill();
  await once(child, 'exit');
  await sleep(200);
  console.log('kill()          grandchild alive:', alive(grandchildPid));
  process.kill(grandchildPid); // clean up the orphan
}

// B. detached: true makes the child a process-group leader; signal the whole group with a negative pid (POSIX only).
{
  const { child, grandchildPid } = await launch({ detached: true });
  process.kill(-child.pid, 'SIGTERM');
  await once(child, 'exit');
  await sleep(200);
  console.log('kill(-pid) group grandchild alive:', alive(grandchildPid));
}

kill()          grandchild alive: true
kill(-pid) group grandchild alive: false

import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { convertProcessSignalToExitCode } from 'node:util';

// 'using' kills the child (SIGTERM) when the block exits, including on an exception.
let pid;
{
  using child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)']);
  pid = child.pid;
  await once(child, 'spawn');
}
await new Promise((resolve) => setTimeout(resolve, 200));
try { process.kill(pid, 0); console.log('still alive'); } catch { console.log('child was disposed'); }

// code is null when a signal ended the child: translate it the way a shell would (128 + signal number).
const killed = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)']);
await once(killed, 'spawn');
killed.kill('SIGTERM');
const [code, signal] = await once(killed, 'exit');
console.log({ code, signal, shellStyle: code ?? convertProcessSignalToExitCode(signal) });

child was disposed
{ code: null, signal: 'SIGTERM', shellStyle: 143 }

import { fork } from 'node:child_process';
import { once } from 'node:events';

async function roundTrip(value, serialization) {
  const child = fork(new URL('./echo-child.js', import.meta.url), { serialization });
  try {
    child.send(value);
    const [reply] = await once(child, 'message');
    return reply.received;
  } finally {
    child.disconnect();
    await once(child, 'exit');
  }
}

const sample = { n: NaN, undef: undefined, when: new Date(0), tags: new Set(['a']), map: new Map([[1, 2]]), big: 10n };

// JSON (the default) cannot carry BigInt at all and silently flattens the rest.
console.log('json    :', await roundTrip({ n: NaN, undef: undefined, when: new Date(0), tags: new Set(['a']) }, 'json'));
await roundTrip({ big: 10n }, 'json').catch((err) => console.log('json big:', err.name, err.message));
// 'advanced' uses the structured-clone family of types.
console.log('advanced:', await roundTrip(sample, 'advanced'));

json    : { n: null, when: '1970-01-01T00:00:00.000Z', tags: {} }
json big: TypeError Do not know how to serialize a BigInt
advanced: {
  n: NaN,
  undef: undefined,
  when: 1970-01-01T00:00:00.000Z,
  tags: Set(1) { 'a' },
  map: Map(1) { 1 => 2 },
  big: 10n
}

import { fork } from 'node:child_process';
import { once } from 'node:events';
import { createServer, connect } from 'node:net';

const server = createServer().listen(0, '127.0.0.1');
await once(server, 'listening');
const socket = connect(server.address().port, '127.0.0.1');
await once(socket, 'connect');

// Live objects (sockets, streams, request and response objects) are not messages.
const json = fork(new URL('./echo-child.js', import.meta.url));
json.send({ socket });
const [reply] = await once(json, 'message');
console.log('json    : the child received a plain object with', Object.keys(reply.received.socket).length, 'copied fields, not a socket');
json.disconnect();
await once(json, 'exit');

const advanced = fork(new URL('./echo-child.js', import.meta.url), { serialization: 'advanced' });
try {
  advanced.send({ socket });
} catch (err) {
  console.log('advanced:', err.name, '- could not be cloned:', err.message.trimEnd().endsWith('could not be cloned.'));
}
advanced.disconnect();
await once(advanced, 'exit');
socket.destroy();
server.close();

json    : the child received a plain object with 15 copied fields, not a socket
advanced: Error - could not be cloned: true

import { fork } from 'node:child_process';
import { once } from 'node:events';
import { setTimeout as sleep } from 'node:timers/promises';

const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };

// A child with a 'message' listener and an open channel does not exit by itself.
const lingering = fork(new URL('./sleepy-child.js', import.meta.url));
lingering.send('hello');
await once(lingering, 'message');
await sleep(500);
console.log('no disconnect  : still alive =', alive(lingering.pid), '| connected =', lingering.connected);

// Closing the channel lets the child exit by itself (its code has no other work).
lingering.disconnect();
await once(lingering, 'exit');
console.log('after disconnect: alive =', alive(lingering.pid));

// Deliberately has no 'disconnect' handler: it only exits when the channel closes and nothing else holds it open.
process.on('message', (msg) => process.send(`echo ${msg}`));

no disconnect  : still alive = true | connected = true
after disconnect: alive = false

import { fork } from 'node:child_process';
import { once } from 'node:events';

const child = fork(new URL('./echo-child.js', import.meta.url));
let received = 0;
child.on('message', () => { received++; });

// send() returns false when the backlog of unsent messages is large: wait before sending more.
let sent = 0;
let paused = 0;
const payload = 'x'.repeat(64 * 1024);
for (let i = 0; i < 400; i++) {
  const ok = child.send(payload);
  sent++;
  if (!ok) {
    paused++;
    await new Promise((resolve) => setImmediate(resolve)); // let the channel drain (a real app waits on callbacks/replies)
  }
}
while (received < sent) await new Promise((resolve) => setTimeout(resolve, 10));
console.log({ sent, received, timesToldToSlowDown: paused > 0 });

child.disconnect();
await once(child, 'exit');

{ sent: 400, received: 400, timesToldToSlowDown: true }

import { fork } from 'node:child_process';
import { createServer, connect } from 'node:net';
import { once } from 'node:events';
import { writeFileSync, mkdtempSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

const dir = mkdtempSync(join(tmpdir(), 'cp-handle-'));
const childFile = join(dir, 'handler.js');
writeFileSync(childFile, `
process.on('message', (msg, socket) => {
  if (msg === 'socket') { socket.end('handled by child ' + process.pid + '\\n'); }
});
process.on('disconnect', () => process.exit(0));
`);

const child = fork(childFile);
const server = createServer({ pauseOnConnect: true }, (socket) => {
  // pauseOnConnect: nothing has been read yet, so no data is lost when the socket moves.
  child.send('socket', socket);
});
server.listen(0, '127.0.0.1');
await once(server, 'listening');

const client = connect(server.address().port, '127.0.0.1');
client.setEncoding('utf8');
console.log((await once(client, 'data'))[0].replace(/\d+/, '<pid>').trim());

server.close();
child.disconnect();
await once(child, 'exit');

handled by child <pid>

// CPU-heavy work in a separate process. Started with fork(); speaks a tiny request/response protocol.
function fib(n) {
  return n < 2 ? n : fib(n - 1) + fib(n - 2);
}

process.on('message', (msg) => {
  switch (msg.type) {
    case 'task':
      process.send({ type: 'result', id: msg.id, value: fib(msg.n), pid: process.pid });
      break;
    case 'crash': // used by the demonstration only
      process.exit(1);
      break;
  }
});

// With an IPC channel open and a 'message' listener, the process stays alive. When the parent
// goes away (even by crashing) the channel closes: exit instead of lingering as an orphan.
process.on('disconnect', () => process.exit(0));

import { fork } from 'node:child_process';
import { once } from 'node:events';
import { availableParallelism } from 'node:os';

const WORKER = new URL('./worker.js', import.meta.url);

/** A fixed-size pool of forked workers with a bounded queue, per-task timeouts and orderly shutdown. */
export class ProcessPool {
  #size;
  #maxQueue;
  #taskTimeoutMs;
  #workers = new Set(); // { child, busy: task | null }
  #queue = [];
  #nextId = 1;
  #closing = false;

  constructor({ size = Math.max(1, availableParallelism() - 1), maxQueue = 100, taskTimeoutMs = 5_000 } = {}) {
    this.#size = size;
    this.#maxQueue = maxQueue;
    this.#taskTimeoutMs = taskTimeoutMs;
    for (let i = 0; i < size; i++) this.#spawnWorker();
  }

  #spawnWorker() {
    const child = fork(WORKER, { serialization: 'json' });
    const worker = { child, task: null };
    this.#workers.add(worker);

    child.on('message', (msg) => {
      if (msg.type !== 'result' || !worker.task) return;
      const { task } = worker;
      worker.task = null;
      clearTimeout(task.timer);
      task.resolve(msg.value);
      this.#drain();
    });

    // 'exit' covers crashes and our own kills; 'error' covers failed spawns and failed send().
    child.on('error', () => {});
    child.on('exit', (code, signal) => {
      this.#workers.delete(worker);
      if (worker.task) {
        clearTimeout(worker.task.timer);
        worker.task.reject(new Error(`worker ${child.pid} ended (code ${code}, signal ${signal}) during a task`));
        worker.task = null;
      }
      if (!this.#closing) {
        this.#spawnWorker(); // replace it, keep the pool at full strength
        this.#drain();
      }
    });
    return worker;
  }

  #drain() {
    for (const worker of this.#workers) {
      if (this.#queue.length === 0) return;
      if (worker.task || !worker.child.connected) continue;
      const task = this.#queue.shift();
      worker.task = task;
      task.timer = setTimeout(() => {
        task.reject(new Error(`task ${task.id} timed out after ${this.#taskTimeoutMs} ms`));
        worker.task = null; // already rejected; the 'exit' handler must not reject twice
        worker.child.kill('SIGKILL'); // a stuck CPU loop cannot be asked politely
      }, this.#taskTimeoutMs);
      worker.child.send({ type: 'task', id: task.id, n: task.n }, (err) => {
        if (err) { clearTimeout(task.timer); worker.task = null; task.reject(err); }
      });
    }
  }

  run(n) {
    if (this.#closing) return Promise.reject(new Error('pool is closed'));
    if (this.#queue.length >= this.#maxQueue) return Promise.reject(new Error('queue is full'));
    return new Promise((resolve, reject) => {
      this.#queue.push({ id: this.#nextId++, n, resolve, reject, timer: null });
      this.#drain();
    });
  }

  get pids() { return [...this.#workers].map((w) => w.child.pid); }
  crashOne() { [...this.#workers][0].child.send({ type: 'crash' }); }

  /** Stop accepting work, then close every channel; escalate to SIGKILL after the grace period. */
  async close({ graceMs = 2_000 } = {}) {
    this.#closing = true;
    for (const task of this.#queue.splice(0)) task.reject(new Error('pool closed before the task started'));
    const exits = [...this.#workers].map(({ child }) => {
      if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
      const done = once(child, 'exit');
      child.disconnect(); // the worker's 'disconnect' handler makes it exit by itself
      const timer = setTimeout(() => child.kill('SIGKILL'), graceMs);
      return done.finally(() => clearTimeout(timer));
    });
    await Promise.all(exits);
  }
}

if (import.meta.main) {
  const pool = new ProcessPool({ size: 2, maxQueue: 3, taskTimeoutMs: 3_000 });
  try {
    console.log('workers:', pool.pids.length);

    // 2 running + 3 queued is the limit: the sixth task is refused immediately.
    const results = await Promise.allSettled([35, 35, 30, 30, 30, 30].map((n) => pool.run(n)));
    console.log(results.map((r) => (r.status === 'fulfilled' ? r.value : r.reason.message)));

    // A crash fails only the task that was running; the pool replaces the process.
    const before = pool.pids;
    pool.crashOne();
    await new Promise((resolve) => setTimeout(resolve, 300));
    console.log('replaced a crashed worker:', pool.pids.length === 2 && pool.pids.some((p) => !before.includes(p)));
    console.log('after crash:', await pool.run(20));
  } finally {
    await pool.close(); // always: otherwise the open IPC channels keep this process alive
  }
}

workers: 2
[ 9227465, 9227465, 832040, 832040, 832040, 'queue is full' ]
replaced a crashed worker: true
after crash: 6765

import { ProcessPool } from './pool.js';

// n = 50 would take far longer than the 400 ms budget: the worker is killed and replaced.
const pool = new ProcessPool({ size: 1, taskTimeoutMs: 400 });
try {
  const started = pool.pids[0];
  console.log(await pool.run(50).catch((err) => err.message));
  await new Promise((resolve) => setTimeout(resolve, 200));
  console.log('worker replaced:', pool.pids[0] !== started, '| next task:', await pool.run(10));
} finally {
  await pool.close();
}

task 1 timed out after 400 ms
worker replaced: true | next task: 55