Make the spawned process cancelable

index.js

@@ -143,7 +143,7 @@ function getStream(process, stream, {encoding, buffer, maxBuffer}) {
 function makeError(result, options) {
 	const {stdout, stderr, code, signal} = result;
 	let {error} = result;
-	const {joinedCommand, timedOut, parsed: {options: {timeout}}} = options;
+	const {joinedCommand, timedOut, canceled, parsed: {options: {timeout}}} = options;
 
 	const [exitCodeName, exitCode] = getCode(result, code);
 
@@ -152,7 +152,7 @@ function makeError(result, options) {
 		error = new Error(message);
 	}
 
-	const prefix = getErrorPrefix({timedOut, timeout, signal, exitCodeName, exitCode});
+	const prefix = getErrorPrefix({timedOut, timeout, signal, exitCode, exitCodeName, canceled});
 	error.message = `Command ${prefix}: ${error.message}`;
 
 	error.code = exitCode || exitCodeName;
@@ -164,6 +164,7 @@ function makeError(result, options) {
 	error.signal = signal || null;
 	error.cmd = joinedCommand;
 	error.timedOut = Boolean(timedOut);
+	error.canceled = canceled;
 
 	if ('all' in result) {
 		error.all = result.all;
@@ -184,11 +185,15 @@ function getCode({error = {}}, code) {
 	return [];
 }
 
-function getErrorPrefix({timedOut, timeout, signal, exitCodeName, exitCode}) {
+function getErrorPrefix({timedOut, timeout, signal, exitCodeName, exitCode, canceled}) {
 	if (timedOut) {
 		return `timed out after ${timeout} milliseconds`;
 	}
 
+	if (canceled) {
+		return 'was canceled';
+	}
+
 	if (signal) {
 		return `was killed with ${signal}`;
 	}
@@ -239,6 +244,7 @@ module.exports = (command, args, options) => {
 
 	let timeoutId = null;
 	let timedOut = false;
+	let canceled = false;
 
 	const cleanup = () => {
 		if (timeoutId) {
@@ -304,11 +310,12 @@ module.exports = (command, args, options) => {
 		result.stderr = results[2];
 		result.all = results[3];
 
-		if (result.error || result.code !== 0 || result.signal !== null) {
+		if (result.error || result.code !== 0 || result.signal !== null || canceled) {
 			const error = makeError(result, {
 				joinedCommand,
 				parsed,
-				timedOut
+				timedOut,
+				canceled
 			});
 
 			// TODO: missing some timeout logic for killed
@@ -334,7 +341,8 @@ module.exports = (command, args, options) => {
 			killed: false,
 			signal: null,
 			cmd: joinedCommand,
-			timedOut: false
+			timedOut: false,
+			canceled: false
 		};
 	}), destroy);
 
@@ -347,6 +355,15 @@ module.exports = (command, args, options) => {
 	// eslint-disable-next-line promise/prefer-await-to-then
 	spawned.then = (onFulfilled, onRejected) => handlePromise().then(onFulfilled, onRejected);
 	spawned.catch = onRejected => handlePromise().catch(onRejected);
+	spawned.cancel = function () {
+		if (spawned.killed) {
+			return;
+		}
+
+		if (spawned.kill()) {
+			canceled = true;
+		}
+	};
 
 	// TOOD: Remove the `if`-guard when targeting Node.js 10
 	if (Promise.prototype.finally) {

readme.md

@@ -52,6 +52,15 @@ const execa = require('execa');
 	const {stdout} = await execa.shell('echo unicorns');
 	//=> 'unicorns'
 
+	// Cancelling a spawned process
+	const spawned = execa("node");
+	spawned.cancel();
+	try {
+		await spawned;
+	} catch (error) {
+		console.log(spawned.killed); // true
+		console.log(error.canceled); // true
+	}
 
 	// Catching an error
 	try {
@@ -146,6 +155,13 @@ Execute a command synchronously through the system shell.
 
 Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
 
+### spawned.cancel()
+
+Cancel a process spawned using execa. Calling this method kills it.
+
+Throws an error with `error.canceled` equal to `true`, provided that the process gets canceled.
+Process would not get canceled if it has already exited or has been killed by `spawned.kill()`.
+
 ### options
 
 Type: `Object`

test.js

@@ -586,3 +586,57 @@ if (Promise.prototype.finally) {
 		t.is(result.message, 'called');
 	});
 }
+
+test('cancel method kills the spawned process', t => {
+	const spawned = execa('node');
+	spawned.cancel();
+	t.true(spawned.killed);
+});
+
+test('result.canceled is false when spawned.cancel isn\'t called', async t => {
+	const result = await execa('noop');
+	t.false(result.canceled);
+});
+
+test('calling cancel method throws an error with message "Command was canceled"', async t => {
+	const spawned = execa('noop');
+	spawned.cancel();
+	await t.throwsAsync(spawned, {message: /Command was canceled/});
+});
+
+test('error.canceled is true when cancel method is used', async t => {
+	const spawned = execa('noop');
+	spawned.cancel();
+	const error = await t.throwsAsync(spawned);
+	t.true(error.canceled);
+});
+
+test('error.canceled is false when kill method is used', async t => {
+	const spawned = execa('noop');
+	spawned.kill();
+	const error = await t.throwsAsync(spawned);
+	t.false(error.canceled);
+});
+
+test('calling cancel method twice should show the same behaviour as calling it once', async t => {
+	const spawned = execa('noop');
+	spawned.cancel();
+	spawned.cancel();
+	const error = await t.throwsAsync(spawned);
+	t.true(error.canceled);
+	t.true(spawned.killed);
+});
+
+test('calling cancel method on a successfuly completed process does not make result.cancel true', async t => {
+	const spawned = execa('noop');
+	const result = await spawned;
+	spawned.cancel();
+	t.false(result.canceled);
+});
+
+test('calling cancel method on a process which has been killed does not make error.canceled true', async t => {
+	const spawned = execa('noop');
+	spawned.kill();
+	const error = await t.throwsAsync(spawned);
+	t.false(error.canceled);
+});