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,12 @@ 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) {
+			canceled = true;
+			spawned.kill();
+		}
+	};
 
 	// TOOD: Remove the `if`-guard when targeting Node.js 10
 	if (Promise.prototype.finally) {

readme.md

@@ -52,6 +52,12 @@ const execa = require('execa');
 	const {stdout} = await execa.shell('echo unicorns');
 	//=> 'unicorns'
 
+	// Cancelling a spawned process
+	const spawned = execa("echo unicorns");
+	spawned.catch(error => {
+		console.log(error.message);
+	}); // To handle the CancelError
+	spawned.cancel();
 
 	// Catching an error
 	try {

test.js

@@ -586,3 +586,42 @@ 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 spawned = execa('noop');
+	const result = await spawned;
+	t.false(result.canceled);
+});
+
+test('calling cancel method throws an error with message "Command was canceled"', async t => {
+	const spawned = execa('noop');
+	spawned.cancel();
+	const error = await t.throwsAsync(async () => {
+		await spawned;
+	});
+	t.regex(error.message, /Command\swas\scanceled/);
+});
+
+test('error.canceled is true when cancel method is used', async t => {
+	const spawned = execa('noop');
+	spawned.cancel();
+	const error = await t.throwsAsync(async () => {
+		await 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(async () => {
+		await spawned;
+	});
+	t.false(error.canceled);
+});