Make the spawned process cancelable

index.js

@@ -8,6 +8,7 @@ const npmRunPath = require('npm-run-path');
 const isStream = require('is-stream');
 const _getStream = require('get-stream');
 const pFinally = require('p-finally');
+const PCancelable = require('p-cancelable');
 const onExit = require('signal-exit');
 const errname = require('./lib/errname');
 const stdio = require('./lib/stdio');
@@ -234,7 +235,7 @@ module.exports = (command, args, options) => {
 		}, parsed.options.timeout);
 	}
 
-	const processDone = new Promise(resolve => {
+	const processDone = new PCancelable((resolve, reject, onCancel) => {
 		spawned.on('exit', (code, signal) => {
 			cleanup();
 			resolve({code, signal});
@@ -251,6 +252,10 @@ module.exports = (command, args, options) => {
 				resolve({error});
 			});
 		}
+
+		onCancel(() => {
+			spawned.kill();
+		});
 	});
 
 	function destroy() {
@@ -311,6 +316,7 @@ 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 = (reason = 'command was canceled') => processDone.cancel(reason);
 
 	// TOOD: Remove the `if`-guard when targeting Node.js 10
 	if (Promise.prototype.finally) {

package.json

@@ -41,6 +41,7 @@
 		"get-stream": "^4.0.0",
 		"is-stream": "^1.1.0",
 		"npm-run-path": "^2.0.0",
+		"p-cancelable": "^1.1.0",
 		"p-finally": "^1.0.0",
 		"signal-exit": "^3.0.0",
 		"strip-final-newline": "^2.0.0"

readme.md

@@ -51,6 +51,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

@@ -7,6 +7,7 @@ import getStream from 'get-stream';
 import isRunning from 'is-running';
 import delay from 'delay';
 import tempfile from 'tempfile';
+import {CancelError} from 'p-cancelable';
 import execa from '.';
 
 process.env.PATH = path.join(__dirname, 'fixtures') + path.delimiter + process.env.PATH;
@@ -569,3 +570,30 @@ if (Promise.prototype.finally) {
 		t.is(result.message, 'called');
 	});
 }
+
+test('cancel method kills the spawned process', t => {
+	const spawned = execa('ls');
+	spawned.catch(() => { }); // To handle the CancelError
+	spawned.cancel();
+	t.true(spawned.killed);
+});
+
+test('invoking cancel method throws CancelError', async t => {
+	const spawned = execa('ls');
+	spawned.cancel();
+	await t.throwsAsync(spawned, CancelError);
+});
+
+test('default CancelError message is "command was canceled"', async t => {
+	const spawned = execa('ls');
+	spawned.cancel();
+	const error = await t.throwsAsync(spawned);
+	t.is(error.message, 'command was canceled');
+});
+
+test('CancelError message is equal to reason argument passed to cancel method', async t => {
+	const spawned = execa('ls');
+	spawned.cancel('reason for canceling');
+	const error = await t.throwsAsync(spawned);
+	t.is(error.message, 'reason for canceling');
+});