util: process signal to exit code utility

[ErickWendel]

Description

Adds util.convertProcessSignalToExitCode() utility function to convert signal names (e.g., SIGTERM, SIGKILL) to their corresponding POSIX exit codes.

When a child process is terminated by a signal, the code parameter in the 'exit' and 'close' events is null. This utility allows users to convert the signal parameter to the POSIX standard exit code.

Example

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

const ls = spawn('ls', ['-lh', '/usr']);

ls.kill();

const [code, signal] = await once(ls, 'exit');
const exitCode = convertProcessSignalToExitCode(signal);
console.log(`signal ${signal}, POSIX exit code: ${exitCode}`);

// signal SIGTERM, POSIX exit code: 143

Note: While Windows doesn't natively support POSIX signals, Node.js provides a cross-platform abstraction that emulates signal behavior. This allows convertProcessSignalToExitCode() to work consistently across all platforms, returning the same POSIX exit codes on both Unix-like systems and Windows.

Refs

• child_process.exitCode is null after process exited #60285
• child_process: set exitCode when process is killed by signal #60720

[RafaelGSS]

We can use validateOneOf here. e.g: https://github.com/nodejs/node/blob/main/lib/util.js#L149

[addaleax]

I would remove the code samples and move the text to the bottom of the section – there's very little reason why somebody would want to do this, while information such as that stdio streams may still be open is much more directly relevant to what this event does

[addaleax]

I'd drop this paragraph. Saying "we don't change this API because changing it would be a breaking change" applies to virtually any API we have. Providing a single link to util.convertProcessSignalToExitCode() should be sufficient (it's not something that people are going to need a lot). (EDIT: and maybe it makes more sense to link to that from the .signalCode docs than from the .exitCode docs?)

[addaleax]

I think the really important thing we should mention is that subprocess.signalCode will be set, and we should link to that.

[addaleax]

Might also be worth linking back to .exitCode from here

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.53%. Comparing base (cbe0233) to head (51cfb9e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #60963   +/-   ##
=======================================
  Coverage   88.53%   88.53%           
=======================================
  Files         703      703           
  Lines      208413   208428   +15     
  Branches    40191    40198    +7     
=======================================
+ Hits       184521   184536   +15     
- Misses      15902    15909    +7     
+ Partials     7990     7983    -7     

Files with missing lines	Coverage Δ
lib/internal/util.js	96.81% <100.00%> (+0.43%)	⬆️
lib/util.js	97.97% <100.00%> (+<0.01%)	⬆️

... and 47 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.