From 54035dacc583dbd29166778e7c3a5afd1848e28e Mon Sep 17 00:00:00 2001
From: Erick Wendel <erick.workspace@gmail.com>
Date: Fri, 14 Nov 2025 17:56:08 -0300
Subject: [PATCH 1/6] util: add convertProcessSignalToExitCode utility

Add convertProcessSignalToExitCode() to convert signal names to POSIX
exit codes (128 + signal number). Exposed in public util API.

Refs: https://github.com/nodejs/node/pull/60720
---
 doc/api/util.md                               | 32 ++++++++
 lib/internal/util.js                          | 13 ++++
 lib/util.js                                   |  2 +
 .../test-util-convert-signal-to-exit-code.mjs | 76 +++++++++++++++++++
 4 files changed, 123 insertions(+)
 create mode 100644 test/parallel/test-util-convert-signal-to-exit-code.mjs

diff --git a/doc/api/util.md b/doc/api/util.md
index 9a02eb43c45b76..75ebe7130e93dd 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -89,6 +89,38 @@ callbackFunction((err, ret) => {
 });
 ```
 
+## `util.convertProcessSignalToExitCode(signalCode)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `signalCode` {string} A signal name (e.g., `'SIGTERM'`, `'SIGKILL'`).
+* Returns: {number|null} The exit code, or `null` if the signal is invalid.
+
+The `util.convertProcessSignalToExitCode()` method converts a signal name to its
+corresponding POSIX exit code. Following the POSIX standard, the exit code
+for a process terminated by a signal is calculated as `128 + signal number`.
+
+```mjs
+import { convertProcessSignalToExitCode } from 'node:util';
+
+console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
+console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
+console.log(convertProcessSignalToExitCode('INVALID')); // null
+```
+
+```cjs
+const { convertProcessSignalToExitCode } = require('node:util');
+
+console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
+console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
+console.log(convertProcessSignalToExitCode('INVALID')); // null
+```
+
+This is particularly useful when working with processes to determine
+the exit code based on the signal that terminated the process.
+
 ## `util.debuglog(section[, callback])`
 
 <!-- YAML
diff --git a/lib/internal/util.js b/lib/internal/util.js
index 1018cded979b24..c7fcd831ae6fce 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -393,6 +393,18 @@ function convertToValidSignal(signal) {
   throw new ERR_UNKNOWN_SIGNAL(signal);
 }
 
+function convertProcessSignalToExitCode(signalCode) {
+  validateString(signalCode, 'signalCode');
+
+  const signalNumber = signals[signalCode];
+  if (signalNumber === undefined) {
+    return null;
+  }
+
+  // POSIX standard: exit code for signal termination is 128 + signal number.
+  return 128 + signalNumber;
+}
+
 function getConstructorOf(obj) {
   while (obj) {
     const descriptor = ObjectGetOwnPropertyDescriptor(obj, 'constructor');
@@ -956,6 +968,7 @@ module.exports = {
   assignFunctionName,
   cachedResult,
   constructSharedArrayBuffer,
+  convertProcessSignalToExitCode,
   convertToValidSignal,
   createClassWrapper,
   decorateErrorStack,
diff --git a/lib/util.js b/lib/util.js
index 7c75615e5c70da..0baa747acd23d9 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -84,6 +84,7 @@ const { getOptionValue } = require('internal/options');
 const binding = internalBinding('util');
 
 const {
+  convertProcessSignalToExitCode,
   deprecate: internalDeprecate,
   getLazy,
   getSystemErrorMap,
@@ -472,6 +473,7 @@ module.exports = {
                              'The `util._extend` API is deprecated. Please use Object.assign() instead.',
                              'DEP0060'),
   callbackify,
+  convertProcessSignalToExitCode,
   debug: debuglog,
   debuglog,
   deprecate,
diff --git a/test/parallel/test-util-convert-signal-to-exit-code.mjs b/test/parallel/test-util-convert-signal-to-exit-code.mjs
new file mode 100644
index 00000000000000..dab5a8838eb90e
--- /dev/null
+++ b/test/parallel/test-util-convert-signal-to-exit-code.mjs
@@ -0,0 +1,76 @@
+import { mustCall, mustNotCall, isWindows } from '../common/index.mjs';
+import assert from 'assert';
+import { convertProcessSignalToExitCode } from 'util';
+import { spawn } from 'child_process';
+import os from 'os';
+
+// Test valid signal names
+{
+  // SIGTERM = 15, so 128 + 15 = 143
+  assert.strictEqual(convertProcessSignalToExitCode('SIGTERM'), 143);
+
+  // SIGKILL = 9, so 128 + 9 = 137
+  assert.strictEqual(convertProcessSignalToExitCode('SIGKILL'), 137);
+
+  // SIGINT = 2, so 128 + 2 = 130
+  assert.strictEqual(convertProcessSignalToExitCode('SIGINT'), 130);
+
+  // SIGHUP = 1, so 128 + 1 = 129
+  assert.strictEqual(convertProcessSignalToExitCode('SIGHUP'), 129);
+
+  // SIGABRT = 6, so 128 + 6 = 134
+  assert.strictEqual(convertProcessSignalToExitCode('SIGABRT'), 134);
+}
+
+// Test invalid signal names return null
+{
+  assert.strictEqual(convertProcessSignalToExitCode('INVALID'), null);
+  assert.strictEqual(convertProcessSignalToExitCode(''), null);
+  assert.strictEqual(convertProcessSignalToExitCode('SIG'), null);
+}
+
+// Test invalid argument types
+{
+  [
+    undefined,
+    null,
+    123,
+    true,
+    false,
+    {},
+    [],
+    Symbol('test'),
+    () => {},
+  ].forEach((value) => {
+    assert.throws(
+      () => convertProcessSignalToExitCode(value),
+      {
+        code: 'ERR_INVALID_ARG_TYPE',
+        name: 'TypeError',
+      }
+    );
+  });
+}
+
+// Test with actual child process termination
+{
+  const cat = spawn(isWindows ? 'cmd' : 'cat');
+  cat.stdout.on('end', mustCall());
+  cat.stderr.on('data', mustNotCall());
+  cat.stderr.on('end', mustCall());
+
+  cat.on('exit', mustCall((code, signal) => {
+    assert.strictEqual(code, null);
+    assert.strictEqual(signal, 'SIGTERM');
+    assert.strictEqual(cat.signalCode, 'SIGTERM');
+
+    // Verify the utility function returns correct exit code
+    const exitCode = convertProcessSignalToExitCode(signal);
+    assert.strictEqual(exitCode, 143);
+  }));
+
+  assert.strictEqual(cat.signalCode, null);
+  assert.strictEqual(cat.killed, false);
+  cat[Symbol.dispose]();
+  assert.strictEqual(cat.killed, true);
+}

From 42dbd61fc1c18727fb6284b1113bf920df23ff2e Mon Sep 17 00:00:00 2001
From: Erick Wendel <erick.workspace@gmail.com>
Date: Fri, 5 Dec 2025 12:50:57 -0300
Subject: [PATCH 2/6] doc: document convertProcessSignalToExitCode usage

Document util.convertProcessSignalToExitCode() in child_process module
to help users convert signal names to POSIX exit codes when a child
process is terminated by a signal.

Refs: https://github.com/nodejs/node/issues/60285
---
 doc/api/child_process.md | 47 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index ba7cc2af6bfb14..9e38ebd74428d3 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -1547,6 +1547,42 @@ exited, `code` is the final exit code of the process, otherwise `null`. If the
 process terminated due to receipt of a signal, `signal` is the string name of
 the signal, otherwise `null`. One of the two will always be non-`null`.
 
+When `code` is `null` due to signal termination, you can use
+[`util.convertProcessSignalToExitCode()`][] to convert the signal to a POSIX
+exit code.
+
+```cjs
+const { spawn } = require('node:child_process');
+const { convertProcessSignalToExitCode } = require('node:util');
+
+const ls = spawn('ls', ['-lh', '/usr']);
+
+ls.kill();
+
+ls.on('exit', (code, signal) => {
+  const exitCode = convertProcessSignalToExitCode(signal);
+  console.log(`signal ${signal}, POSIX exit code: ${exitCode}`);
+});
+
+// signal SIGTERM, POSIX exit code: 143
+```
+
+```mjs
+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
+```
+
 When the `'exit'` event is triggered, child process stdio streams might still be
 open.
 
@@ -1671,6 +1707,16 @@ within the child process to close the IPC channel as well.
 The `subprocess.exitCode` property indicates the exit code of the child process.
 If the child process is still running, the field will be `null`.
 
+When the child process is terminated by a signal, `subprocess.exitCode` will be
+`null`. To get the corresponding POSIX exit code, use
+[`util.convertProcessSignalToExitCode(subprocess.signalCode)`][`util.convertProcessSignalToExitCode()`].
+
+**Note:** The `child_process` module does not automatically set `exitCode` when
+a process is terminated by a signal to avoid breaking changes in existing code
+that may depend on `exitCode` being `null` in such cases. The
+[`util.convertProcessSignalToExitCode()`][] utility function is provided to
+allow applications to opt-in to this conversion when needed.
+
 ### `subprocess.kill([signal])`
 
 <!-- YAML
@@ -2393,6 +2439,7 @@ or [`child_process.fork()`][].
 [`subprocess.stdin`]: #subprocessstdin
 [`subprocess.stdio`]: #subprocessstdio
 [`subprocess.stdout`]: #subprocessstdout
+[`util.convertProcessSignalToExitCode()`]: util.md#utilconvertprocesssignaltoexitcodesignalcode
 [`util.promisify()`]: util.md#utilpromisifyoriginal
 [synchronous counterparts]: #synchronous-process-creation
 [v8.serdes]: v8.md#serialization-api

From 51cfb9e6ec630b5ed48a6b4aee82865ff5c721f9 Mon Sep 17 00:00:00 2001
From: Erick Wendel <erick.workspace@gmail.com>
Date: Fri, 5 Dec 2025 13:07:30 -0300
Subject: [PATCH 3/6] fixup! util: add convertProcessSignalToExitCode utility

---
 test/parallel/test-util-convert-signal-to-exit-code.mjs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/test/parallel/test-util-convert-signal-to-exit-code.mjs b/test/parallel/test-util-convert-signal-to-exit-code.mjs
index dab5a8838eb90e..26b1e4fe722eb8 100644
--- a/test/parallel/test-util-convert-signal-to-exit-code.mjs
+++ b/test/parallel/test-util-convert-signal-to-exit-code.mjs
@@ -2,7 +2,6 @@ import { mustCall, mustNotCall, isWindows } from '../common/index.mjs';
 import assert from 'assert';
 import { convertProcessSignalToExitCode } from 'util';
 import { spawn } from 'child_process';
-import os from 'os';
 
 // Test valid signal names
 {

From b107877fd54f1203ed5d7500e6538600903cc978 Mon Sep 17 00:00:00 2001
From: Erick Wendel <erick.workspace@gmail.com>
Date: Mon, 8 Dec 2025 11:39:37 -0300
Subject: [PATCH 4/6] fixup! util: add convertProcessSignalToExitCode utility

---
 lib/internal/util.js                             | 13 +++++++------
 .../test-util-convert-signal-to-exit-code.mjs    | 16 ++++------------
 2 files changed, 11 insertions(+), 18 deletions(-)

diff --git a/lib/internal/util.js b/lib/internal/util.js
index c7fcd831ae6fce..9739422d08284a 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -16,6 +16,7 @@ const {
   ObjectGetOwnPropertyDescriptor,
   ObjectGetOwnPropertyDescriptors,
   ObjectGetPrototypeOf,
+  ObjectKeys,
   ObjectPrototypeHasOwnProperty,
   ObjectSetPrototypeOf,
   ObjectValues,
@@ -106,6 +107,7 @@ function isError(e) {
 const codesWarned = new SafeSet();
 
 let validateString;
+let validateOneOf;
 
 function getDeprecationWarningEmitter(
   code, msg, deprecated, useEmitSync,
@@ -394,15 +396,14 @@ function convertToValidSignal(signal) {
 }
 
 function convertProcessSignalToExitCode(signalCode) {
-  validateString(signalCode, 'signalCode');
+  // Lazy-load to avoid a circular dependency.
+  if (validateOneOf === undefined)
+    ({ validateOneOf } = require('internal/validators'));
 
-  const signalNumber = signals[signalCode];
-  if (signalNumber === undefined) {
-    return null;
-  }
+  validateOneOf(signalCode, 'signalCode', ObjectKeys(signals));
 
   // POSIX standard: exit code for signal termination is 128 + signal number.
-  return 128 + signalNumber;
+  return 128 + signals[signalCode];
 }
 
 function getConstructorOf(obj) {
diff --git a/test/parallel/test-util-convert-signal-to-exit-code.mjs b/test/parallel/test-util-convert-signal-to-exit-code.mjs
index 26b1e4fe722eb8..1158112ef4f636 100644
--- a/test/parallel/test-util-convert-signal-to-exit-code.mjs
+++ b/test/parallel/test-util-convert-signal-to-exit-code.mjs
@@ -3,7 +3,6 @@ import assert from 'assert';
 import { convertProcessSignalToExitCode } from 'util';
 import { spawn } from 'child_process';
 
-// Test valid signal names
 {
   // SIGTERM = 15, so 128 + 15 = 143
   assert.strictEqual(convertProcessSignalToExitCode('SIGTERM'), 143);
@@ -21,16 +20,11 @@ import { spawn } from 'child_process';
   assert.strictEqual(convertProcessSignalToExitCode('SIGABRT'), 134);
 }
 
-// Test invalid signal names return null
-{
-  assert.strictEqual(convertProcessSignalToExitCode('INVALID'), null);
-  assert.strictEqual(convertProcessSignalToExitCode(''), null);
-  assert.strictEqual(convertProcessSignalToExitCode('SIG'), null);
-}
-
-// Test invalid argument types
 {
   [
+    'INVALID',
+    '',
+    'SIG',
     undefined,
     null,
     123,
@@ -44,14 +38,13 @@ import { spawn } from 'child_process';
     assert.throws(
       () => convertProcessSignalToExitCode(value),
       {
-        code: 'ERR_INVALID_ARG_TYPE',
+        code: 'ERR_INVALID_ARG_VALUE',
         name: 'TypeError',
       }
     );
   });
 }
 
-// Test with actual child process termination
 {
   const cat = spawn(isWindows ? 'cmd' : 'cat');
   cat.stdout.on('end', mustCall());
@@ -63,7 +56,6 @@ import { spawn } from 'child_process';
     assert.strictEqual(signal, 'SIGTERM');
     assert.strictEqual(cat.signalCode, 'SIGTERM');
 
-    // Verify the utility function returns correct exit code
     const exitCode = convertProcessSignalToExitCode(signal);
     assert.strictEqual(exitCode, 143);
   }));

From 8337df16c00a12b6f1c09a260a1135be769435f6 Mon Sep 17 00:00:00 2001
From: Erick Wendel <erick.workspace@gmail.com>
Date: Mon, 8 Dec 2025 11:59:26 -0300
Subject: [PATCH 5/6] fixup! doc: document convertProcessSignalToExitCode usage

---
 doc/api/child_process.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index 9e38ebd74428d3..33144160208d95 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -1711,12 +1711,6 @@ When the child process is terminated by a signal, `subprocess.exitCode` will be
 `null`. To get the corresponding POSIX exit code, use
 [`util.convertProcessSignalToExitCode(subprocess.signalCode)`][`util.convertProcessSignalToExitCode()`].
 
-**Note:** The `child_process` module does not automatically set `exitCode` when
-a process is terminated by a signal to avoid breaking changes in existing code
-that may depend on `exitCode` being `null` in such cases. The
-[`util.convertProcessSignalToExitCode()`][] utility function is provided to
-allow applications to opt-in to this conversion when needed.
-
 ### `subprocess.kill([signal])`
 
 <!-- YAML

From ccf99c9574efd3391cab9ab79ff67071664a9a1f Mon Sep 17 00:00:00 2001
From: Erick Wendel <erick.workspace@gmail.com>
Date: Mon, 8 Dec 2025 20:28:20 -0300
Subject: [PATCH 6/6] fixup! doc: document convertProcessSignalToExitCode usage

---
 doc/api/child_process.md | 49 ++++++++++------------------------------
 1 file changed, 12 insertions(+), 37 deletions(-)

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index 33144160208d95..e3273446c3e517 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -1547,42 +1547,6 @@ exited, `code` is the final exit code of the process, otherwise `null`. If the
 process terminated due to receipt of a signal, `signal` is the string name of
 the signal, otherwise `null`. One of the two will always be non-`null`.
 
-When `code` is `null` due to signal termination, you can use
-[`util.convertProcessSignalToExitCode()`][] to convert the signal to a POSIX
-exit code.
-
-```cjs
-const { spawn } = require('node:child_process');
-const { convertProcessSignalToExitCode } = require('node:util');
-
-const ls = spawn('ls', ['-lh', '/usr']);
-
-ls.kill();
-
-ls.on('exit', (code, signal) => {
-  const exitCode = convertProcessSignalToExitCode(signal);
-  console.log(`signal ${signal}, POSIX exit code: ${exitCode}`);
-});
-
-// signal SIGTERM, POSIX exit code: 143
-```
-
-```mjs
-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
-```
-
 When the `'exit'` event is triggered, child process stdio streams might still be
 open.
 
@@ -1593,6 +1557,10 @@ re-raise the handled signal.
 
 See waitpid(2).
 
+When `code` is `null` due to signal termination, you can use
+[`util.convertProcessSignalToExitCode()`][] to convert the signal to a POSIX
+exit code.
+
 ### Event: `'message'`
 
 <!-- YAML
@@ -1708,7 +1676,8 @@ The `subprocess.exitCode` property indicates the exit code of the child process.
 If the child process is still running, the field will be `null`.
 
 When the child process is terminated by a signal, `subprocess.exitCode` will be
-`null`. To get the corresponding POSIX exit code, use
+`null` and [`subprocess.signalCode`][] will be set. To get the corresponding
+POSIX exit code, use
 [`util.convertProcessSignalToExitCode(subprocess.signalCode)`][`util.convertProcessSignalToExitCode()`].
 
 ### `subprocess.kill([signal])`
@@ -2147,6 +2116,10 @@ connection to the child.
 The `subprocess.signalCode` property indicates the signal received by
 the child process if any, else `null`.
 
+When the child process is terminated by a signal, [`subprocess.exitCode`][] will be `null`.
+To get the corresponding POSIX exit code, use
+[`util.convertProcessSignalToExitCode(subprocess.signalCode)`][`util.convertProcessSignalToExitCode()`].
+
 ### `subprocess.spawnargs`
 
 * Type: {Array}
@@ -2427,8 +2400,10 @@ or [`child_process.fork()`][].
 [`stdio`]: #optionsstdio
 [`subprocess.connected`]: #subprocessconnected
 [`subprocess.disconnect()`]: #subprocessdisconnect
+[`subprocess.exitCode`]: #subprocessexitcode
 [`subprocess.kill()`]: #subprocesskillsignal
 [`subprocess.send()`]: #subprocesssendmessage-sendhandle-options-callback
+[`subprocess.signalCode`]: #subprocesssignalcode
 [`subprocess.stderr`]: #subprocessstderr
 [`subprocess.stdin`]: #subprocessstdin
 [`subprocess.stdio`]: #subprocessstdio