Support AbortController

index.d.ts

@@ -204,6 +204,26 @@ export interface CommonOptions<EncodingType> {
 	*/
 	readonly killSignal?: string | number;
 
+	/**
+	You can abort the spawned process using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+
+	*Requires Node.js 16 or later.*
+
+	@example
+	```
+	import {execa} from 'execa';
+
+	const abortController = new AbortController();
+	const subprocess = execa('node', [], {signal: abortController.signal});
+
+	abortController.abort();
+
+	console.log(subprocess.killed);
+	//=> true
+	```
+	*/
+	readonly signal?: AbortSignal;
+
 	/**
 	If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`.
 

index.js

@@ -109,6 +109,12 @@ export function execa(file, args, options) {
 	spawned.kill = spawnedKill.bind(null, spawned.kill.bind(spawned));
 	spawned.cancel = spawnedCancel.bind(null, spawned, context);
 
+	if (parsed.options.signal) {
+		parsed.options.signal.addEventListener('abort', () => {
+			spawned.cancel();
+		}, {once: true});
+	}
+
 	const handlePromise = async () => {
 		const [{error, exitCode, signal, timedOut}, stdoutResult, stderrResult, allResult] = await getSpawnedResult(spawned, parsed.options, processDone);
 		const stdout = handleOutput(parsed.options, stdoutResult);

readme.md

@@ -80,6 +80,8 @@ try {
 
 ### Cancelling a spawned process
 
+#### Use `cancel` method
+
 ```js
 import {execa} from 'execa';
 
@@ -97,6 +99,20 @@ try {
 }
 ```
 
+#### Use `AbortController`
+
+```js
+import {execa} from 'execa';
+
+const abortController = new AbortController();
+const subprocess = execa('node', [], {signal: abortController.signal});
+
+abortController.abort();
+
+console.log(subprocess.killed);
+//=> true
+```
+
 ### Catching an error with the sync method
 
 ```js
@@ -542,6 +558,16 @@ Default: `SIGTERM`
 
 Signal value to be used when the spawned process will be killed.
 
+#### signal
+
+Type: `object (AbortSignal)`
+
+You can abort the spawned process using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+
+See [this Example](#use-abortcontroller).
+
+*Requires Node.js 16 or later.*
+
 #### windowsVerbatimArguments
 
 Type: `boolean`\

test/kill.js

@@ -262,3 +262,48 @@ test('calling cancel method on a process which has been killed does not make err
 	const {isCanceled} = await t.throwsAsync(subprocess);
 	t.false(isCanceled);
 });
+
+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});
+	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});
+	abortController.abort();
+	abortController.abort();
+	const {isCanceled} = await t.throwsAsync(subprocess);
+	t.true(isCanceled);
+	t.true(subprocess.killed);
+});
+
+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 {isCanceled} = await subprocess;
+	abortController.abort();
+	t.false(isCanceled);
+});
+
+test('calling cancel after abort should show the same behaviour as only calling cancel', async t => {
+	const abortController = new AbortController();
+	const subprocess = execa('noop.js', [], {signal: abortController.signal});
+	abortController.abort();
+	subprocess.cancel();
+	const {isCanceled} = await t.throwsAsync(subprocess);
+	t.true(isCanceled);
+	t.true(subprocess.killed);
+});
+
+test('calling abort after cancel should show the same behaviour as only calling cancel', async t => {
+	const abortController = new AbortController();
+	const subprocess = execa('noop.js', [], {signal: abortController.signal});
+	subprocess.cancel();
+	abortController.abort();
+	const {isCanceled} = await t.throwsAsync(subprocess);
+	t.true(isCanceled);
+	t.true(subprocess.killed);
+});