Know when a process ended due to the `child_process.spawn()` `timeout` option

[ehmicky]

What is the problem this feature will solve?

When a process ends due to the timeout option of child_process.spawn(), there is no way to know whether that termination was due to the timeout. A SIGTERM is sent to the process, but that's pretty much it.

import {spawn} from 'node:child_process'

const childProcess = spawn('node', ['-e', 'setTimeout(() => {}, 1e7)'], {
  timeout: 2e3, 
  stdio: 'inherit', // no stdout/stderr
})
childProcess.on('exit', (exitCode, signal) => {
  console.log({exitCode, signal}) // { exitCode: null, signal: 'SIGTERM' }
})

This makes debugging harder. Some users might be left wondering why the process ended if they don't pay attention to the timeout option.

What is the feature you are proposing to solve the problem?

Having a way to know whether the process ended due to the timeout option. Any implementation would work. Some potential ideas:

• timeout event on childProcess
• third boolean argument timedOut passed to the exit event
• emit an error event with error.code: 'ETIMEDOUT' on childProcess. This is a breaking change since many users are currently listening for error events, so would probably not be a good idea.
• childProcess.timedOut = true
• childProcess.timedOut() returning a boolean

What alternatives have you considered?

One could possibly set a manual timeout like the following.

let timedOut = false
setTimeout(() => {
  timedOut = true
}, 2e3)

However, it defeats some of the convenience of the timeout option, since that one might as well call childProcess.kill() themselves then. Also, it is slightly unreliable since an unrelated SIGTERM could theoretically have been sent at the exact same time.

[aduh95]

Another alternative is to pass an AbortSIgnal:

import {spawn} from 'node:child_process'

const signal = AbortSignal.timeout(2e3)
const childProcess = spawn('node', ['-e', 'setTimeout(() => {}, 1e7)'], {
  signal, 
  stdio: 'inherit', // no stdout/stderr
})
childProcess.on('error', (err) => {
  console.log({err, didTimeout: signal.aborted}) // { err: [AbortError], didTimeout: true }
});
childProcess.on('exit', (exitCode, killSignal) => {
  console.log({exitCode, killSignal, didTimeout: signal.aborted}) // { exitCode: null, killSignal: 'SIGTERM', didTimeout: true }
})

[FranciscoMateusVG]

Setting childProcess.timedOut = true is an easy and convenient implementation. We could go with AbortSignal, but just checking a flag keeps things really simple. Opened a PR implementing it!

 import { spawn } from 'node:child_process';

const childProcess = spawn('node', ['-e', 'setTimeout(() => {}, 1e7)'], {
 timeout: 2e3,
  stdio: 'inherit', // no stdout/stderr
});

childProcess.on('exit', (exitCode, signal) => {
  console.log(childProcess.timedOut); // true
  console.log({ exitCode, signal }); // { exitCode: null, signal: 'SIGTERM' }
 });

[github-actions]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Mark issue so that it is never considered stale label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.

[ehmicky]

There is a PR at #51608, waiting for a review.

[github-actions]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Mark issue so that it is never considered stale label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.

[sindresorhus]

Please keep this open.