lib: Know when a process ended due to the child_process.spawn() timeout option #51561

doc/api/child_process.md

@@ -1785,6 +1785,29 @@ subprocess.stdout.on('data', (data) => {
 The `subprocess.stdout` property can be `null` or `undefined`
 if the child process could not be successfully spawned.
 
+### `subprocess.timedOut`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {boolean}
+
+The `subprocess.timedOut` property indicates whether the child process
+was killed due to the `timeout` option set in [`child_process.spawn()`][],
+[`child_process.exec()`][], [`child_process.execFile()`][], or
+[`child_process.fork()`][].
+
+```js
+const { spawn } = require('node:child_process');
+
+const subprocess = spawn('sleep', ['10'], { timeout: 100 });
+
+subprocess.on('exit', () => {
+  console.log(subprocess.timedOut); // true
+});
+```
+
 ### `subprocess.unref()`
 
 <!-- YAML

lib/child_process.js

@@ -764,6 +764,7 @@ function spawn(file, args, options) {
     let timeoutId = setTimeout(() => {
       if (timeoutId) {
         try {
+          child.timedOut = true;
           child.kill(killSignal);
         } catch (err) {
           child.emit('error', err);

lib/internal/child_process.js

@@ -263,6 +263,7 @@ function ChildProcess() {
   this.exitCode = null;
   this.killed = false;
   this.spawnfile = null;
+  this.timedOut = false;
 
   this._handle = new Process();
   this._handle[owner_symbol] = this;

test/parallel/test-child-process-spawn-timeout-kill-signal.js

@@ -35,6 +35,17 @@
   }), /ERR_OUT_OF_RANGE/);
 }
 
+{
+  // Verify timedOut flag is set true
+  const cp = spawn(process.execPath, [fixtures.path(aliveForeverFile)], {
+    timeout: 6,
+  });
+  strictEqual(cp.timedOut, false);
+  cp.on('exit', mustCall(() => {
+    strictEqual(cp.timedOut, true);
+  }));
+}
+
 {
   // Verify abort signal gets unregistered
   const controller = new AbortController();