Add gracefulCancel option

[ehmicky]

Fixes #1106.

This adds an abortSignal option. The AbortSignal is shared with the subprocess, which retrieves it using getAbortSignal(). This enables graceful termination, since signals (like SIGTERM) handlers do not work on Windows.

This also adds error.isAborted, which is true when abortSignal was aborted.

[sindresorhus]

What happened to the gracefulCancelSignal naming? I think having both abortSignal and cancelSignal will be confusing.

[ehmicky]

I renamed it to abortSignal, but I can change it back to gracefulCancelSignal if you want?
I found getGracefulCancelSignal() and error.isGracefullyCanceled to be slightly verbose.
I was also considering other names like: haltSignal, stopSignal, disposeSignal.

Which name do you prefer? I'll update the PR then.

[sindresorhus]

Have you considered just using cancelSignal and add a gracefulExit option to indicate that it should be graceful?

[ehmicky]

Yes, that would work too. 👍 Using both signal termination and graceful termination does not seem to make much sense, so they are rather exclusive from each other. Would you prefer this?

However, the name should probably highlight that the subprocess will still fail (i.e. Execa promise is rejected), even if its exit is being handled. gracefulExit might give the impression the subprocess succeeds. Let's call it maybe gracefulCancel instead? (Since the other option is called cancelSignal.)

[sindresorhus]

Using both signal termination and graceful termination does not seem to make much sense, so they are rather exclusive from each other. Would you prefer this?

Yes

Let's call it maybe gracefulCancel instead?

👍

[ehmicky]

Fixed the PR. 👍

The API is now:

• gracefulCancel boolean option
• getCancelSignal() method
• error.isGracefullyCanceled boolean property

[sindresorhus]

Maybe mention that if you write your own scripts just for Unix platforms, a user could also just use SIGTERM, that this is specifically for cross-platform scripts that should also work on Windows.

[ehmicky]

I just added the following line:

This is cross-platform. If you do not need to support Windows, signal handlers can also be used.

It redirects to the following section:

On Unix, most signals (not SIGKILL) can be intercepted to perform a graceful exit.

process.on('SIGTERM', () => {
	cleanup();
	process.exit(1);
})

Unfortunately this usually does not work on Windows. The only signal that is somewhat cross-platform is SIGINT: on Windows, its handler is triggered when the user types CTRL-C in the terminal. However subprocess.kill('SIGINT') is only handled on Unix.

Execa provides the gracefulCancel option as a cross-platform alternative to signal handlers.

[sindresorhus]

I know you link to the "more info", but would be nice to just mention here that this method should only be called in a subprocess.

[ehmicky]

Added the following line:

This can only be called inside a subprocess.

[sindresorhus]

I would mention this in the "Features" section in the readme. "Cross-platform graceful termination".

[ehmicky]

Fixed 👍

I have added it in the Features section as part of the following bullet point:

• Improved Windows support: shebangs, PATHEXT, graceful termination, and more.

[sindresorhus]

Great work! I'm very happy with what we ended up with 👍