Rename signal option to cancelSignal (#880)

Author: ehmicky

docs/scripts.md

@@ -46,7 +46,7 @@ Execa's scripting API mostly consists of only two methods: [`` $`command` ``](..
 
 [No special binary](#main-binary) is recommended, no [global variable](#global-variables) is injected: scripts are regular Node.js files.
 
-Execa is a thin wrapper around the core Node.js [`child_process` module](https://nodejs.org/api/child_process.html). Unlike zx, it lets you use [any of its native features](#background-processes): [`pid`](#pid), [IPC](https://nodejs.org/api/child_process.html#subprocesssendmessage-sendhandle-options-callback), [`unref()`](https://nodejs.org/api/child_process.html#subprocessunref), [`detached`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), [`uid`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), [`gid`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), [`signal`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), etc.
+Execa is a thin wrapper around the core Node.js [`child_process` module](https://nodejs.org/api/child_process.html). Unlike zx, it lets you use [any of its native features](#background-processes): [`pid`](#pid), [IPC](https://nodejs.org/api/child_process.html#subprocesssendmessage-sendhandle-options-callback), [`unref()`](https://nodejs.org/api/child_process.html#subprocessunref), [`detached`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), [`uid`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), [`gid`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), [`cancelSignal`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options), etc.
 
 ### Modularity
 

index.d.ts

@@ -499,7 +499,7 @@ type CommonOptions<IsSync extends boolean = boolean> = {
 
 	/**
 	Signal used to terminate the child process when:
-	- using the `signal`, `timeout`, `maxBuffer` or `cleanup` option
+	- using the `cancelSignal`, `timeout`, `maxBuffer` or `cleanup` option
 	- calling [`subprocess.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal) with no arguments
 
 	This can be either a name (like `"SIGTERM"`) or a number (like `9`).
@@ -514,7 +514,7 @@ type CommonOptions<IsSync extends boolean = boolean> = {
 	The grace period is 5 seconds by default. This feature can be disabled with `false`.
 
 	This works when the child process is terminated by either:
-	- the `signal`, `timeout`, `maxBuffer` or `cleanup` option
+	- the `cancelSignal`, `timeout`, `maxBuffer` or `cleanup` option
 	- calling [`subprocess.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal) with no arguments
 
 	This does not work when the child process is terminated by either:
@@ -613,7 +613,7 @@ type CommonOptions<IsSync extends boolean = boolean> = {
 	import {execa} from 'execa';
 
 	const abortController = new AbortController();
-	const subprocess = execa('node', [], {signal: abortController.signal});
+	const subprocess = execa('node', [], {cancelSignal: abortController.signal});
 
 	setTimeout(() => {
 		abortController.abort();
@@ -627,7 +627,7 @@ type CommonOptions<IsSync extends boolean = boolean> = {
 	}
 	```
 	*/
-	readonly signal?: IfAsync<IsSync, AbortSignal>;
+	readonly cancelSignal?: IfAsync<IsSync, AbortSignal>;
 };
 
 export type Options = CommonOptions<false>;
@@ -664,7 +664,7 @@ type ExecaCommonReturnValue<IsSync extends boolean = boolean, OptionsType extend
 	/**
 	The numeric exit code of the process that was run.
 
-	This is `undefined` when the process could not be spawned or was terminated by a [signal](#signal-1).
+	This is `undefined` when the process could not be spawned or was terminated by a [signal](#signal).
 	*/
 	exitCode?: number;
 
@@ -728,7 +728,7 @@ type ExecaCommonReturnValue<IsSync extends boolean = boolean, OptionsType extend
 	cwd: string;
 
 	/**
-	Whether the process was canceled using the [`signal`](https://github.com/sindresorhus/execa#signal-1) option.
+	Whether the process was canceled using the `cancelSignal` option.
 	*/
 	isCanceled: boolean;
 
@@ -1028,7 +1028,7 @@ export function execa<OptionsType extends Options = {}>(
 /**
 Same as `execa()` but synchronous.
 
-Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `signal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 
@@ -1129,7 +1129,7 @@ export function execaCommand<OptionsType extends Options = {}>(
 /**
 Same as `execaCommand()` but synchronous.
 
-Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `signal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 
@@ -1187,7 +1187,7 @@ type Execa$<OptionsType extends CommonOptions = {}> = {
 	/**
 	Same as $\`command\` but synchronous.
 
-	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `signal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 	Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 
@@ -1241,7 +1241,7 @@ type Execa$<OptionsType extends CommonOptions = {}> = {
 	/**
 	Same as $\`command\` but synchronous.
 
-	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `signal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 	Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 

index.test-d.ts

@@ -1434,8 +1434,8 @@ execa('unicorns', {forceKillAfterDelay: undefined});
 execaSync('unicorns', {forceKillAfterDelay: undefined});
 expectError(execa('unicorns', {forceKillAfterDelay: 'true'}));
 expectError(execaSync('unicorns', {forceKillAfterDelay: 'true'}));
-execa('unicorns', {signal: new AbortController().signal});
-expectError(execaSync('unicorns', {signal: new AbortController().signal}));
+execa('unicorns', {cancelSignal: new AbortController().signal});
+expectError(execaSync('unicorns', {cancelSignal: new AbortController().signal}));
 execa('unicorns', {windowsVerbatimArguments: true});
 execaSync('unicorns', {windowsVerbatimArguments: true});
 execa('unicorns', {windowsHide: false});

lib/async.js

@@ -32,7 +32,13 @@ const handleAsyncArguments = (rawFile, rawArgs, rawOptions) => {
 };
 
 // Prevent passing the `timeout` option directly to `child_process.spawn()`
-const handleAsyncOptions = ({timeout, ...options}) => ({...options, timeoutDuration: timeout});
+const handleAsyncOptions = ({timeout, signal, cancelSignal, ...options}) => {
+	if (signal !== undefined) {
+		throw new TypeError('The "signal" option has been renamed to "cancelSignal" instead.');
+	}
+
+	return {...options, timeoutDuration: timeout, signal: cancelSignal};
+};
 
 const spawnProcessAsync = ({file, args, options, command, escapedCommand, stdioStreamsGroups}) => {
 	let spawned;

lib/stream/exit.js

@@ -1,7 +1,7 @@
 import {once} from 'node:events';
 
 // If `error` is emitted before `spawn`, `exit` will never be emitted.
-// However, `error` might be emitted after `spawn`, e.g. with the `signal` option.
+// However, `error` might be emitted after `spawn`, e.g. with the `cancelSignal` option.
 // In that case, `exit` will still be emitted.
 // Since the `exit` event contains the signal name, we want to make sure we are listening for it.
 // This function also takes into account the following unlikely cases:

readme.md

@@ -315,7 +315,7 @@ This is the preferred method when executing Node.js files.
 
 Same as [`execa()`](#execacommandcommand-options), [`execaCommand()`](#execacommand-command-options), [$\`command\`](#command) but synchronous.
 
-Cannot use the following options: [`all`](#all-2), [`cleanup`](#cleanup), [`buffer`](#buffer), [`detached`](#detached), [`ipc`](#ipc), [`serialization`](#serialization), [`signal`](#signal) and [`lines`](#lines). Also, the [`stdin`](#stdin), [`stdout`](#stdout-1), [`stderr`](#stderr-1), [`stdio`](#stdio-1) and [`input`](#input) options cannot be an array, an iterable or a web stream. Node.js streams [must have a file descriptor](#redirect-a-nodejs-stream-fromto-stdinstdoutstderr) unless the `input` option is used.
+Cannot use the following options: [`all`](#all-2), [`cleanup`](#cleanup), [`buffer`](#buffer), [`detached`](#detached), [`ipc`](#ipc), [`serialization`](#serialization), [`cancelSignal`](#cancelsignal) and [`lines`](#lines). Also, the [`stdin`](#stdin), [`stdout`](#stdout-1), [`stderr`](#stderr-1), [`stdio`](#stdio-1) and [`input`](#input) options cannot be an array, an iterable or a web stream. Node.js streams [must have a file descriptor](#redirect-a-nodejs-stream-fromto-stdinstdoutstderr) unless the `input` option is used.
 
 Returns or throws a [`childProcessResult`](#childProcessResult). The [`childProcess`](#childprocess) is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), [`.pipe()`](#pipefile-arguments-options) and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 
@@ -525,7 +525,7 @@ Whether the process timed out.
 
 Type: `boolean`
 
-Whether the process was canceled using the [`signal`](#signal-1) option.
+Whether the process was canceled using the [`cancelSignal`](#cancelsignal) option.
 
 #### isTerminated
 
@@ -541,7 +541,7 @@ Type: `number | undefined`
 
 The numeric exit code of the process that was run.
 
-This is `undefined` when the process could not be spawned or was terminated by a [signal](#signal-1).
+This is `undefined` when the process could not be spawned or was terminated by a [signal](#signal).
 
 #### signal
 
@@ -850,7 +850,7 @@ Default: `0`
 
 If `timeout` is greater than `0`, the child process will be [terminated](#killsignal) if it runs for longer than that amount of milliseconds.
 
-#### signal
+#### cancelSignal
 
 Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
 
@@ -868,7 +868,7 @@ If the child process is terminated but does not exit, forcefully exit it by send
 The grace period is 5 seconds by default. This feature can be disabled with `false`.
 
 This works when the child process is terminated by either:
-- the [`signal`](#signal-1), [`timeout`](#timeout), [`maxBuffer`](#maxbuffer) or [`cleanup`](#cleanup) option
+- the [`cancelSignal`](#cancelsignal), [`timeout`](#timeout), [`maxBuffer`](#maxbuffer) or [`cleanup`](#cleanup) option
 - calling [`subprocess.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal) with no arguments
 
 This does not work when the child process is terminated by either:
@@ -884,7 +884,7 @@ Type: `string | number`\
 Default: `SIGTERM`
 
 Signal used to terminate the child process when:
-- using the [`signal`](#signal-1), [`timeout`](#timeout), [`maxBuffer`](#maxbuffer) or [`cleanup`](#cleanup) option
+- using the [`cancelSignal`](#cancelsignal), [`timeout`](#timeout), [`maxBuffer`](#maxbuffer) or [`cleanup`](#cleanup) option
 - calling [`subprocess.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal) with no arguments
 
 This can be either a name (like `"SIGTERM"`) or a number (like `9`).
@@ -973,7 +973,7 @@ console.log(await pRetry(run, {retries: 5}));
 import {execa} from 'execa';
 
 const abortController = new AbortController();
-const subprocess = execa('node', [], {signal: abortController.signal});
+const subprocess = execa('node', [], {cancelSignal: abortController.signal});
 
 setTimeout(() => {
 	abortController.abort();

test/exit/signal.js renamed to test/exit/cancel.js

@@ -29,23 +29,23 @@ test('result.isCanceled is false when abort isn\'t called in sync mode (failure)
 
 test('error.isCanceled is true when abort is used', async t => {
 	const abortController = new AbortController();
-	const subprocess = execa('noop.js', {signal: abortController.signal});
+	const subprocess = execa('noop.js', {cancelSignal: abortController.signal});
 	abortController.abort();
 	const {isCanceled} = await t.throwsAsync(subprocess);
 	t.true(isCanceled);
 });
 
 test('error.isCanceled is false when kill method is used', async t => {
 	const abortController = new AbortController();
-	const subprocess = execa('noop.js', {signal: abortController.signal});
+	const subprocess = execa('noop.js', {cancelSignal: abortController.signal});
 	subprocess.kill();
 	const {isCanceled} = await t.throwsAsync(subprocess);
 	t.false(isCanceled);
 });
 
 test('calling abort is considered a signal termination', async t => {
 	const abortController = new AbortController();
-	const subprocess = execa('forever.js', {signal: abortController.signal});
+	const subprocess = execa('forever.js', {cancelSignal: abortController.signal});
 	await once(subprocess, 'spawn');
 	abortController.abort();
 	const {isTerminated, signal} = await t.throwsAsync(subprocess);
@@ -55,14 +55,14 @@ test('calling abort is considered a signal termination', async t => {
 
 test('calling abort throws an error with message "Command was canceled"', async t => {
 	const abortController = new AbortController();
-	const subprocess = execa('noop.js', {signal: abortController.signal});
+	const subprocess = execa('noop.js', {cancelSignal: abortController.signal});
 	abortController.abort();
 	await t.throwsAsync(subprocess, {message: /Command was canceled/});
 });
 
 test('calling abort twice should show the same behaviour as calling it once', async t => {
 	const abortController = new AbortController();
-	const subprocess = execa('noop.js', {signal: abortController.signal});
+	const subprocess = execa('noop.js', {cancelSignal: abortController.signal});
 	abortController.abort();
 	abortController.abort();
 	const {isCanceled} = await t.throwsAsync(subprocess);
@@ -71,8 +71,15 @@ test('calling abort twice should show the same behaviour as calling it once', as
 
 test('calling abort on a successfully completed process does not make result.isCanceled true', async t => {
 	const abortController = new AbortController();
-	const subprocess = execa('noop.js', {signal: abortController.signal});
+	const subprocess = execa('noop.js', {cancelSignal: abortController.signal});
 	const result = await subprocess;
 	abortController.abort();
 	t.false(result.isCanceled);
 });
+
+test('Throws when using the former "signal" option name', t => {
+	const abortController = new AbortController();
+	t.throws(() => {
+		execa('noop.js', {signal: abortController.signal});
+	}, {message: /renamed to "cancelSignal"/});
+});

test/exit/kill.js

@@ -98,7 +98,7 @@ if (isWindows) {
 
 	test('`forceKillAfterDelay` works with the "signal" option', async t => {
 		const abortController = new AbortController();
-		const subprocess = spawnNoKillableSimple({signal: abortController.signal});
+		const subprocess = spawnNoKillableSimple({cancelSignal: abortController.signal});
 		await once(subprocess, 'spawn');
 		abortController.abort();
 		const {isTerminated, signal, isCanceled} = await t.throwsAsync(subprocess);
@@ -280,7 +280,7 @@ test('child process errors are handled after spawn', async t => {
 
 test('child process double errors are handled after spawn', async t => {
 	const abortController = new AbortController();
-	const subprocess = execa('forever.js', {signal: abortController.signal});
+	const subprocess = execa('forever.js', {cancelSignal: abortController.signal});
 	await once(subprocess, 'spawn');
 	const error = new Error('test');
 	subprocess.emit('error', error);