Process, Signals & Exit Codes

import process, { argv, argv0, execArgv, execPath, cwd, pid, ppid, platform, arch, uptime, versions } from 'node:process';

console.log('argv      :', argv.slice(2));
console.log('argv[0] is execPath:', argv[0] === execPath, '| argv0:', argv0);
console.log('argv[1] is absolute:', argv[1].startsWith('/'), '| ends with', argv[1].split('/').at(-1));
console.log('execArgv  :', execArgv);
console.log('cwd       :', cwd().split('/').at(-1));
console.log('pid/ppid  :', typeof pid, typeof ppid, pid !== ppid);
console.log('platform  :', platform, arch);
console.log('node / v8 / uv:', versions.node.split('.')[0], versions.v8.split('.')[0], versions.uv);
console.log('uptime < 1s:', uptime() < 1);
console.log('release   :', process.release.name, process.release.lts ?? '(not LTS)');

argv      : [ 'one', '--two=3' ]
argv[0] is execPath: true | argv0: node
argv[1] is absolute: true | ends with info.js
execArgv  : [ '--no-warnings' ]
cwd       : proc
pid/ppid  : number number true
platform  : darwin arm64
node / v8 / uv: 26 14 1.52.1
uptime < 1s: true
release   : node (not LTS)

import { stdin, stdout, stderr } from 'node:process';

// Decide behaviour from where the streams point, not from guesses
console.log(JSON.stringify({
  stdinTTY: Boolean(stdin.isTTY),
  stdoutTTY: Boolean(stdout.isTTY),
  stderrTTY: Boolean(stderr.isTTY),
  fds: [stdin.fd, stdout.fd, stderr.fd],
}));

{"stdinTTY":false,"stdoutTTY":false,"stderrTTY":false,"fds":[0,1,2]}

import { chdir, cwd } from 'node:process';
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';

console.log('cwd             :', cwd().split('/').at(-1));
console.log('script directory:', import.meta.dirname.split('/').at(-1));

chdir('..');
console.log('after chdir("..") :', cwd().split('/').at(-1));

// Relative paths follow the cwd, so this file is no longer found...
try {
  readFileSync('./cwd.js', 'utf8');
} catch (err) {
  console.log('relative read     :', err.code);
}
// ...while a path anchored to the module still is.
console.log('anchored read     :', readFileSync(resolve(import.meta.dirname, 'cwd.js'), 'utf8').length > 0);

cwd             : proc
script directory: proc
after chdir("..") : bookshelf
relative read     : ENOENT
anchored read     : true

import { env, loadEnvFile } from 'node:process';
import { spawnSync } from 'node:child_process';

// 1. Values are always strings
env.RETRIES = 3;
env.DEBUG_SQL = false;
console.log(typeof env.RETRIES, JSON.stringify(env.RETRIES), JSON.stringify(env.DEBUG_SQL));
console.log('"false" is truthy:', Boolean(env.DEBUG_SQL));

// 2. Missing keys are undefined; use delete, never assign undefined
env.TOKEN_HINT = undefined;
console.log('assigned undefined ->', JSON.stringify(env.TOKEN_HINT));
delete env.TOKEN_HINT;
console.log('after delete       ->', env.TOKEN_HINT, '| in:', 'TOKEN_HINT' in env);

// 3. Parse deliberately, with a default
const port = Number.parseInt(env.PORT ?? '3000', 10);
const verbose = env.VERBOSE === '1' || env.VERBOSE === 'true';
console.log({ port, verbose });

// 4. Changes are visible to children, never to the parent shell
env.BOOKSHELF_MODE = 'child-sees-this';
const child = spawnSync(process.execPath, ['-p', 'process.env.BOOKSHELF_MODE'], { encoding: 'utf8' });
console.log('child printed:', child.stdout.trim());

// 5. Pass an explicit environment to a child instead of mutating your own
const clean = spawnSync(process.execPath, ['-p', '[process.env.ONLY_THIS, process.env.HOME].join()'], {
  encoding: 'utf8',
  env: { PATH: env.PATH, ONLY_THIS: '1' },
});
console.log('clean child sees ONLY_THIS,HOME ->', clean.stdout.trim());

string "3" "false"
"false" is truthy: true
assigned undefined -> "undefined"
after delete       -> undefined | in: false
{ port: 3000, verbose: false }
child printed: child-sees-this
clean child sees ONLY_THIS,HOME -> 1,

import { memoryUsage, availableMemory, constrainedMemory, cpuUsage, resourceUsage } from 'node:process';

const mb = (bytes) => Math.round(bytes / 1024 / 1024) + 0;
const delta = (a, b) => Object.fromEntries(Object.keys(a).map((k) => [k, mb(b[k] - a[k])]));

const s0 = memoryUsage();
const buffer = Buffer.alloc(64 * 1024 * 1024, 1);          // 64 MB outside the V8 heap
const s1 = memoryUsage();
const rows = Array.from({ length: 500_000 }, (_, i) => ({ id: i, title: `Book ${i}` }));
const s2 = memoryUsage();

console.log('64 MB Buffer, MB added    :', delta(s0, s1));
const { heapUsed, external } = delta(s1, s2);
console.log('500k small objects, MB   :', { heapUsed, external });
console.log('rss() matches memoryUsage().rss:', Math.abs(memoryUsage.rss() - memoryUsage().rss) < 32 * 1024 * 1024);

console.log('availableMemory() is a number  :', typeof availableMemory() === 'number');
console.log('constrainedMemory() (0: no OS limit):', typeof constrainedMemory());
console.log('cpuUsage() keys                :', Object.keys(cpuUsage()).join(', '), '(microseconds)');
console.log('resourceUsage() has maxRSS     :', 'maxRSS' in resourceUsage());
console.log(buffer.length === 64 * 1024 * 1024, rows.length);   // keep both reachable

64 MB Buffer, MB added    : { rss: 64, heapTotal: 0, heapUsed: 0, external: 64, arrayBuffers: 64 }
500k small objects, MB   : { heapUsed: 39, external: 0 }
rss() matches memoryUsage().rss: true
availableMemory() is a number  : true
constrainedMemory() (0: no OS limit): number
cpuUsage() keys                : user, system (microseconds)
resourceUsage() has maxRSS     : true
true 500000

import { spawnSync } from 'node:child_process';
import { execPath } from 'node:process';

const cases = [
  ['script ends normally',                   ['-e', '1']],
  ['uncaught exception',                     ['-e', 'throw new Error("boom")']],
  ['unhandled rejection',                    ['-e', 'Promise.reject(new Error("boom"))']],
  ['process.exitCode = 9',                   ['-e', 'process.exitCode = 9']],
  ['process.exit(42)',                       ['-e', 'process.exit(42)']],
  ['exitCode = 9, then exit(42)',            ['-e', 'process.exitCode = 9; process.exit(42)']],
  ['exitCode = 9, then exit()',              ['-e', 'process.exitCode = 9; process.exit()']],
  ['unsettled top-level await',              ['--input-type=module', '-e', 'await new Promise(() => {})']],
  ['unsettled TLA, exitCode = 9',            ['--input-type=module', '-e', 'process.exitCode = 9; await new Promise(() => {})']],
  ['unknown node option',                    ['--no-such-option', '-e', '1']],
  ['syntax error',                           ['-e', 'let let']],
  ['killed by SIGKILL',                      ['-e', 'process.kill(process.pid, "SIGKILL")']],
  ['SIGTERM, default handler',               ['-e', 'process.kill(process.pid, "SIGTERM"); setTimeout(() => {}, 5000)']],
];

for (const [label, args] of cases) {
  const { status, signal } = spawnSync(execPath, args, { stdio: 'ignore' });
  console.log(label.padEnd(30), 'status =', String(status).padEnd(4), 'signal =', signal);
}

script ends normally           status = 0    signal = null
uncaught exception             status = 1    signal = null
unhandled rejection            status = 1    signal = null
process.exitCode = 9           status = 9    signal = null
process.exit(42)               status = 42   signal = null
exitCode = 9, then exit(42)    status = 42   signal = null
exitCode = 9, then exit()      status = 9    signal = null
unsettled top-level await      status = 13   signal = null
unsettled TLA, exitCode = 9    status = 9    signal = null
unknown node option            status = 9    signal = null
syntax error                   status = 1    signal = null
killed by SIGKILL              status = null signal = SIGKILL
SIGTERM, default handler       status = null signal = SIGTERM

import { spawnSync } from 'node:child_process';
import { execPath } from 'node:process';

const writer = (ending) => `
  process.stdout.write('x'.repeat(4 * 1024 * 1024));   // 4 MiB of output
  ${ending}
`;

for (const [label, ending] of [
  ['process.exit(1)      ', 'process.exit(1);'],
  ['process.exitCode = 1 ', 'process.exitCode = 1;'],
]) {
  const { stdout, status } = spawnSync(execPath, ['-e', writer(ending)], { maxBuffer: 16 * 1024 * 1024 });
  console.log(label, 'status', status, '| bytes received:', stdout.length);
}

process.exit(1)       status 1 | bytes received: 65536
process.exitCode = 1  status 1 | bytes received: 4194304

import process from 'node:process';
import { writeSync } from 'node:fs';

let rounds = 0;

process.on('beforeExit', (code) => {
  // Fires when the loop is empty. Scheduling work here keeps the process alive.
  console.log(`beforeExit #${rounds + 1}, code ${code}`);
  if (++rounds < 3) setTimeout(() => console.log(`  ...extra work ${rounds}`), 10);
});

process.on('exit', (code) => {
  // Synchronous only: the loop is finished, so this timer is abandoned.
  setTimeout(() => console.log('never printed'), 0);
  writeSync(1, `exit, code ${code}, exitCode property ${process.exitCode}\n`);
  process.exitCode = 5;            // the last word on the exit status
});

console.log('main script done');

main script done
beforeExit #1, code 0
  ...extra work 1
beforeExit #2, code 0
  ...extra work 2
beforeExit #3, code 0
exit, code 0, exitCode property undefined
status 5

import process from 'node:process';

process.on('beforeExit', () => console.log('beforeExit'));
process.on('exit', (code) => console.log('exit', code));

if (process.argv[2] === 'exit') process.exit(7);               // exit only
if (process.argv[2] === 'throw') throw new Error('boom');      // exit only, code 1
console.log('end of script');                                  // beforeExit then exit

node exit-events2.js          # end of script, then beforeExit, then exit 0
node exit-events2.js exit     # exit 7 (no beforeExit)
node exit-events2.js throw    # exit 1 (no beforeExit), after the error is printed

import process, { kill } from 'node:process';
import { constants } from 'node:os';

console.log('SIGINT / SIGTERM / SIGUSR2 numbers:', constants.signals.SIGINT, constants.signals.SIGTERM, constants.signals.SIGUSR2);

// A listener replaces the default action (here: terminate) for that signal.
process.on('SIGUSR2', (signal) => {
  console.log(`got ${signal}; reloading configuration instead of dying`);
});

// Send a signal to ourselves; process.kill() is really "send signal".
kill(process.pid, 'SIGUSR2');

// Signal 0 sends nothing; it only tests that a pid exists and is signalable.
const alive = (pid) => { try { kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
console.log('own pid alive    :', alive(process.pid));
console.log('pid 2**22+1 alive:', alive(2 ** 22 + 1));

setTimeout(() => console.log('still running'), 50);

SIGINT / SIGTERM / SIGUSR2 numbers: 2 15 31
own pid alive    : true
pid 2**22+1 alive: false
got SIGUSR2; reloading configuration instead of dying
still running

// Is a signal listener alone enough to keep the process alive?
process.on('SIGUSR2', () => console.log('listener ran'));
process.kill(process.pid, 'SIGUSR2');
console.log('end of script');

node signals2.js; echo "exit=$?"
# end of script
# exit=0        <- the listener never ran: the loop was empty, so the process ended first

import process from 'node:process';
import { once } from 'node:events';

/**
 * Run `cleanup` once, on the first of the given signals, then let the process
 * exit by itself with the conventional 128 + signal number status.
 */
export function onShutdown(cleanup, { signals = ['SIGINT', 'SIGTERM'], graceMs = 10_000 } = {}) {
  let started = false;

  const handler = async (signal) => {
    if (started) return;                         // ignore repeated signals
    started = true;
    console.log(`${signal} received, shutting down`);

    const watchdog = setTimeout(() => {          // last resort if cleanup hangs
      console.error('graceful shutdown timed out');
      process.exit(1);
    }, graceMs);
    watchdog.unref();                            // never keeps the process alive by itself

    try {
      await cleanup(signal);
      process.exitCode = 128 + signalNumber(signal);
    } catch (err) {
      console.error('cleanup failed:', err.message);
      process.exitCode = 1;
    }
  };

  for (const signal of signals) process.on(signal, handler);
  return () => { for (const signal of signals) process.off(signal, handler); };
}

function signalNumber(name) {
  return { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 }[name] ?? 0;
}

/** Stop accepting connections, close idle ones, force-close the rest after a deadline. */
export async function closeServer(server, forceAfterMs = 2_000) {
  const closed = once(server, 'close');
  server.close();                                // stop accepting; closes idle keep-alive sockets
  const timer = setTimeout(() => server.closeAllConnections(), forceAfterMs);
  timer.unref();
  await closed;
  clearTimeout(timer);
}

import http from 'node:http';
import { once } from 'node:events';
import { onShutdown, closeServer } from './shutdown.js';

const books = [];

const server = http.createServer(async (req, res) => {
  try {
    if (req.method === 'POST' && req.url === '/books') {
      let body = '';
      for await (const chunk of req) body += chunk;  // waits until the client finishes the body
      books.push(JSON.parse(body));
      res.writeHead(201, { 'content-type': 'application/json' }).end(body);
      return;
    }
    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(books));
  } catch (err) {
    // A request cut off by closeAllConnections() must not crash the process.
    console.log('request aborted:', err.code ?? err.message);
  }
});

server.listen(0, '127.0.0.1');
await once(server, 'listening');
console.log('listening', server.address().port);

onShutdown(async () => {
  await closeServer(server, 500);                // a busy connection would otherwise block close() forever
  console.log('server closed');
});

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

const child = spawn(execPath, ['serve.js'], { stdio: ['ignore', 'pipe', 'inherit'] });
child.stdout.setEncoding('utf8');

const { promise: portReady, resolve } = Promise.withResolvers();
child.stdout.on('data', (chunk) => {
  process.stdout.write(`  child: ${chunk}`);
  const match = chunk.match(/listening (\d+)/);
  if (match) resolve(Number(match[1]));
});
const port = await portReady;

// A request whose body never finishes keeps its connection busy, so close() alone would wait forever.
const stalled = http.request({ host: '127.0.0.1', port, path: '/books', method: 'POST' });
stalled.on('error', (err) => console.log('stalled client sees:', err.code));
stalled.write('{"title": "Unfinished');
await once(stalled, 'socket');
console.log('request in flight, sending SIGTERM');

child.kill('SIGTERM');
const [code, signal] = await once(child, 'exit');
console.log('child exit code =', code, '| signal =', signal);

  child: listening 54237
request in flight, sending SIGTERM
  child: SIGTERM received, shutting down
server closed
stalled client sees: ECONNRESET
child exit code = 143 | signal = null

import process from 'node:process';
import { writeSync } from 'node:fs';

const mode = process.argv[2];

// Observe without changing behaviour: the process still crashes with code 1.
process.on('uncaughtExceptionMonitor', (err, origin) => {
  writeSync(2, `[monitor] ${origin}: ${err.message}\n`);
});

if (mode === 'handler' || mode === 'handler-sets-code') {
  process.on('uncaughtException', (err, origin) => {
    writeSync(2, `[handler] ${origin}: ${err.message}\n`);   // synchronous logging only
    if (mode === 'handler-sets-code') process.exitCode = 70;  // otherwise the exit status becomes 0
  });
}

if (mode === 'rejection-handler') {
  process.on('unhandledRejection', (reason) => {
    writeSync(2, `[rejection] ${reason.message}\n`);
    throw reason;                       // turn it into an uncaught exception: crash loudly
  });
}

setTimeout(() => writeSync(2, 'timer still ran\n'), 20);

if (mode === 'rejection' || mode === 'rejection-handler') Promise.reject(new Error('lost promise'));
else throw new Error('sync failure');

import { spawnSync } from 'node:child_process';
import { execPath } from 'node:process';

const run = (flags, mode) => {
  const { status, stderr } = spawnSync(execPath, [...flags, 'last-resort.js', mode], { encoding: 'utf8' });
  const seen = stderr.split('\n').filter((l) => /^\[|timer/.test(l)).map((l) => l.split(':')[0]);
  const warned = stderr.includes('UnhandledPromiseRejectionWarning');
  console.log(`${[...flags, mode].join(' ').padEnd(50)} status ${status}  ${seen.join(' ')}${warned ? ' (warning printed)' : ''}`);
};

run([], 'plain');
run([], 'handler');
run([], 'handler-sets-code');
run([], 'rejection');
run([], 'rejection-handler');
run(['--unhandled-rejections=warn'], 'rejection');
run(['--unhandled-rejections=warn-with-error-code'], 'rejection');
run(['--unhandled-rejections=strict'], 'rejection');

plain                                              status 1  [monitor] unhandledRejection
handler                                            status 0  [monitor] unhandledRejection [handler] unhandledRejection timer still ran
handler-sets-code                                  status 70  [monitor] unhandledRejection [handler] unhandledRejection timer still ran
rejection                                          status 1  [monitor] unhandledRejection
rejection-handler                                  status 1  [rejection] lost promise [monitor] uncaughtException
--unhandled-rejections=warn rejection              status 0  timer still ran (warning printed)
--unhandled-rejections=warn-with-error-code rejection status 1  timer still ran (warning printed)
--unhandled-rejections=strict rejection            status 1  [monitor] unhandledRejection

import { createRequire } from 'node:module';

// 1. Synchronous access to built-ins from an ES module, no import needed
const fs = process.getBuiltinModule('node:fs');
console.log('node:fs readFileSync  :', typeof fs.readFileSync);
console.log('bare id also works    :', process.getBuiltinModule('fs') === fs);
console.log('unknown id            :', process.getBuiltinModule('left-pad'));
console.log('"test" needs a prefix :', process.getBuiltinModule('test'), typeof process.getBuiltinModule('node:test'));

// 2. Portable code: works in Node.js and in runtimes without a `process` global
const isNode = typeof globalThis.process?.getBuiltinModule === 'function';
const { hostname } = isNode ? globalThis.process.getBuiltinModule('node:os') : { hostname: () => 'unknown' };
console.log('portable hostname call:', typeof hostname());

// 3. It returns the real built-in even if code tampers with require.cache
const require = createRequire(import.meta.url);
require.cache[require.resolve('path')] = { exports: { sep: 'patched' } };
console.log('require("path").sep   :', require('path').sep);
console.log('getBuiltinModule sep  :', process.getBuiltinModule('path').sep);

node:fs readFileSync  : function
bare id also works    : true
unknown id            : undefined
"test" needs a prefix : undefined function
portable hostname call: string
require("path").sep   : patched
getBuiltinModule sep  : /

import { features } from 'node:process';

// Only the useful, non-deprecated entries
console.log({
  inspector: features.inspector,
  require_module: features.require_module,   // require(esm) support
  typescript: features.typescript,           // 'strip' unless --no-strip-types
  tls: features.tls,
  cached_builtins: features.cached_builtins,
  debug: features.debug,
});

{
  inspector: true,
  require_module: true,
  typescript: 'strip',
  tls: true,
  cached_builtins: true,
  debug: false
}