Add .node() method

index.d.ts

@@ -185,14 +185,29 @@ declare namespace execa {
 		readonly input?: string | Buffer | ReadableStream;
 	}
 
-	interface SyncOptions<EncodingType = string>
-		extends CommonOptions<EncodingType> {
+	interface SyncOptions<EncodingType = string> extends CommonOptions<EncodingType> {
 		/**
 		Write some input to the `stdin` of your binary.
 		*/
 		readonly input?: string | Buffer;
 	}
 
+	interface NodeOptions<EncodingType = string> extends CommonOptions<EncodingType> {
+		/**
+		 Executable used to create the child process.
+
+		 @default process.execPath
+		 */
+		readonly execPath?: string;
+
+		/**
+		 List of string arguments passed to the executable.
+
+		 @default process.execArgv
+		 */
+		readonly execArgv?: string[];
+	}
+
 	interface ExecaReturnBase<StdoutStderrType> {
 		/**
 		The command that was run.
@@ -420,6 +435,26 @@ declare const execa: {
 	*/
 	commandSync(command: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
 	commandSync(command: string, options?: execa.SyncOptions<null>): execa.ExecaSyncReturnValue<Buffer>;
+
+	/**
+	 Run a file through a forked process.
+
+	 @param file - The program/script to execute.
+	 @param arguments - Arguments to pass to `file` on execution.
+	 @returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
+	 */
+	node(
+		file: string,
+		arguments?: readonly string[],
+		options?: execa.Options
+	): execa.ExecaChildProcess;
+	node(
+		file: string,
+		arguments?: readonly string[],
+		options?: execa.Options<null>
+	): execa.ExecaChildProcess<Buffer>;
+	node(file: string, options?: execa.Options): execa.ExecaChildProcess;
+	node(file: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
 };
 
 export = execa;

index.js

@@ -475,3 +475,30 @@ module.exports.commandSync = (command, options) => {
 	const [file, ...args] = parseCommand(command);
 	return execa.sync(file, args, options);
 };
+
+module.exports.node = (filePath, args, options) => {
+	if (args && !Array.isArray(args) && typeof args === 'object') {
+		options = args;
+		args = [];
+	}
+
+	const stdioOption = stdio.node(options);
+	options = options || {};
+
+	return execa(
+		options.execPath || process.execPath,
+		[
+			...(options.execArgv || process.execArgv),
+			filePath,
+			...(Array.isArray(args) ? args : [])
+		],
+		{
+			...options,
+			stdin: undefined,
+			stdout: undefined,
+			stderr: undefined,
+			stdio: stdioOption,
+			shell: false
+		}
+	);
+};

index.test-d.ts

@@ -167,3 +167,16 @@ expectType<ExecaSyncReturnValue<string>>(execa.commandSync('unicorns', {encoding
 expectType<ExecaSyncReturnValue<Buffer>>(execa.commandSync('unicorns', {encoding: null}));
 expectType<ExecaSyncReturnValue<string>>(execa.commandSync('unicorns foo', {encoding: 'utf8'}));
 expectType<ExecaSyncReturnValue<Buffer>>(execa.commandSync('unicorns foo', {encoding: null}));
+
+expectType<ExecaChildProcess<string>>(execa.node('unicorns'));
+expectType<ExecaReturnValue<string>>(await execa.node('unicorns'));
+expectType<ExecaReturnValue<string>>(
+	await execa.node('unicorns', {encoding: 'utf8'})
+);
+expectType<ExecaReturnValue<Buffer>>(await execa.node('unicorns', {encoding: null}));
+expectType<ExecaReturnValue<string>>(
+	await execa.node('unicorns', ['foo'], {encoding: 'utf8'})
+);
+expectType<ExecaReturnValue<Buffer>>(
+	await execa.node('unicorns', ['foo'], {encoding: null})
+);

lib/stdio.js

@@ -3,7 +3,7 @@ const alias = ['stdin', 'stdout', 'stderr'];
 
 const hasAlias = opts => alias.some(x => Boolean(opts[x]));
 
-module.exports = opts => {
+const stdio = opts => {
 	if (!opts) {
 		return;
 	}
@@ -39,3 +39,23 @@ module.exports = opts => {
 
 	return result;
 };
+
+module.exports = stdio;
+
+module.exports.node = opts => {
+	const defaultOption = 'pipe';
+
+	let stdioOption = stdio(opts || {stdio: defaultOption});
+
+	if (typeof stdioOption === 'string') {
+		stdioOption = [...new Array(3)].fill(stdioOption);
+	} else if (Array.isArray(stdioOption)) {
+		stdioOption = stdioOption.map((channel = defaultOption) => channel);
+	}
+
+	if (!stdioOption.includes('ipc')) {
+		stdioOption.push('ipc');
+	}
+
+	return stdioOption;
+};

readme.md

@@ -180,6 +180,15 @@ Same as [`execa.command()`](#execacommand-command-options) but synchronous.
 
 Returns or throws a [`childProcessResult`](#childProcessResult).
 
+### execa.node(file, [arguments], [options])
+
+Run a file through a forked process.
+
+Same as `execa('node', [file, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
+  - the `execPath` and `execArgv` options can be used
+  - the [`shell`](#shell) option cannot be used 
+  - an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
+
 ### childProcessResult
 
 Type: `object`
@@ -432,6 +441,19 @@ Default: `false`
 
 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`.
 
+#### execPath *(for `.node()` only)*
+
+Type: `string`<br>
+Default: [`process.execPath`](https://nodejs.org/api/process.html#process_process_execpath)
+
+Node.js executable used to create the child process.
+
+#### execArgv *(for `.node()` only)*
+
+Type: `string[]`<br>
+Default: [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv)
+
+List of string arguments passed to the Node.js executable.
 
 ## Tips
 

test/fixtures/detach

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+
+const execa = require('../../');
+
+const subprocess = execa('node', ['./test/fixtures/forever'], {detached: true});
+console.log(subprocess.pid);
+process.exit();

test/fixtures/echo

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+console.log(process.argv.slice(2).join('\n'));

test/fixtures/hello.sh

@@ -0,0 +1 @@
+echo Hello World

test/fixtures/send

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+process.on('message', message => {
+	if (message === 'ping') {
+		process.send('pong');
+	} else {
+		throw new Error('Receive wrong message');
+	}
+});

fixtures/sub-process → test/fixtures/sub-process

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 'use strict';
-const execa = require('..');
+const execa = require('../../');
 
 const cleanup = process.argv[2] === 'true';
 const detached = process.argv[3] === 'true';
-const subprocess = execa('node', ['./fixtures/forever'], {cleanup, detached});
+const subprocess = execa('node', ['./test/fixtures/forever'], {cleanup, detached});
 process.send(subprocess.pid);

fixtures/sub-process-exit → test/fixtures/sub-process-exit

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
-const execa = require('..');
+const execa = require('../../');
 
 const cleanup = process.argv[2] === 'true';
 const detached = process.argv[3] === 'true';
-execa('node', ['./fixtures/noop'], {cleanup, detached});
+execa('node', ['./test/fixtures/noop'], {cleanup, detached});

test/node.js

@@ -0,0 +1,46 @@
+import test from 'ava';
+import pEvent from 'p-event';
+import path from 'path';
+import execa from '..';
+
+process.env.PATH = path.join(__dirname, 'fixtures') + path.delimiter + process.env.PATH;
+
+test('node()', async t => {
+	const {exitCode} = await execa.node('test/fixtures/noop');
+	t.is(exitCode, 0);
+});
+
+test('node pipe stdout', async t => {
+	const {stdout} = await execa.node('test/fixtures/noop', ['foo'], {
+		stdout: 'pipe'
+	});
+
+	t.is(stdout, 'foo');
+});
+
+test('node correctly use execPath', async t => {
+	const {stdout} = await execa.node(process.platform === 'win32' ? 'hello.cmd' : 'hello.sh', {
+		stdout: 'pipe',
+		execPath: process.platform === 'win32' ? 'cmd.exe' : 'bash',
+		execArgv: process.platform === 'win32' ? ['/c'] : []
+	});
+
+	t.is(stdout, 'Hello World');
+});
+
+test('node pass on execArgv', async t => {
+	const {stdout} = await execa.node('console.log("foo")', {
+		stdout: 'pipe',
+		execArgv: ['-e']
+	});
+
+	t.is(stdout, 'foo');
+});
+
+test('node\'s forked script has a communication channel', async t => {
+	const subprocess = execa.node('test/fixtures/send');
+	subprocess.send('ping');
+
+	const message = await pEvent(subprocess, 'message');
+	t.is(message, 'pong');
+});

test/stdio.js

@@ -4,46 +4,69 @@ import stdio from '../lib/stdio';
 
 util.inspect.styles.name = 'magenta';
 
-function macro(t, input, expected) {
-	if (expected instanceof Error) {
-		t.throws(() => stdio(input), expected.message);
-		return;
-	}
-
-	const result = stdio(input);
-
-	if (typeof expected === 'object' && expected !== null) {
-		t.deepEqual(result, expected);
-	} else {
-		t.is(result, expected);
-	}
+function createMacro(func) {
+	const macro = (t, input, expected) => {
+		if (expected instanceof Error) {
+			t.throws(() => {
+				stdio(input);
+			}, expected.message);
+			return;
+		}
+
+		const result = func(input);
+
+		if (typeof expected === 'object' && expected !== null) {
+			t.deepEqual(result, expected);
+		} else {
+			t.is(result, expected);
+		}
+	};
+
+	macro.title = (providedTitle, input) => `${func.name} ${(providedTitle || util.inspect(input, {colors: true}))}`;
+
+	return macro;
 }
 
-macro.title = (providedTitle, input) => providedTitle || util.inspect(input, {colors: true});
-
-test(macro, undefined, undefined);
-
-test(macro, {stdio: 'inherit'}, 'inherit');
-test(macro, {stdio: 'pipe'}, 'pipe');
-test(macro, {stdio: 'ignore'}, 'ignore');
-test(macro, {stdio: [0, 1, 2]}, [0, 1, 2]);
-
-test(macro, {}, [undefined, undefined, undefined]);
-test(macro, {stdio: []}, [undefined, undefined, undefined]);
-test(macro, {stdin: 'pipe'}, ['pipe', undefined, undefined]);
-test(macro, {stdout: 'ignore'}, [undefined, 'ignore', undefined]);
-test(macro, {stderr: 'inherit'}, [undefined, undefined, 'inherit']);
-test(macro, {stdin: 'pipe', stdout: 'ignore', stderr: 'inherit'}, ['pipe', 'ignore', 'inherit']);
-test(macro, {stdin: 'pipe', stdout: 'ignore'}, ['pipe', 'ignore', undefined]);
-test(macro, {stdin: 'pipe', stderr: 'inherit'}, ['pipe', undefined, 'inherit']);
-test(macro, {stdout: 'ignore', stderr: 'inherit'}, [undefined, 'ignore', 'inherit']);
-test(macro, {stdin: 0, stdout: 1, stderr: 2}, [0, 1, 2]);
-test(macro, {stdin: 0, stdout: 1}, [0, 1, undefined]);
-test(macro, {stdin: 0, stderr: 2}, [0, undefined, 2]);
-test(macro, {stdout: 1, stderr: 2}, [undefined, 1, 2]);
-
-test(macro, {stdio: {foo: 'bar'}}, new TypeError('Expected `stdio` to be of type `string` or `Array`, got `object`'));
-
-test(macro, {stdin: 'inherit', stdio: 'pipe'}, new Error('It\'s not possible to provide `stdio` in combination with one of `stdin`, `stdout`, `stderr`'));
-test(macro, {stdin: 'inherit', stdio: ['pipe']}, new Error('It\'s not possible to provide `stdio` in combination with one of `stdin`, `stdout`, `stderr`'));
-test(macro, {stdin: 'inherit', stdio: [undefined, 'pipe']}, new Error('It\'s not possible to provide `stdio` in combination with one of `stdin`, `stdout`, `stderr`'));
+const stdioMacro = createMacro(stdio);
+
+test(stdioMacro, undefined, undefined);
+test(stdioMacro, null, undefined);
+
+test(stdioMacro, {stdio: 'inherit'}, 'inherit');
+test(stdioMacro, {stdio: 'pipe'}, 'pipe');
+test(stdioMacro, {stdio: 'ignore'}, 'ignore');
+test(stdioMacro, {stdio: [0, 1, 2]}, [0, 1, 2]);
+
+test(stdioMacro, {}, [undefined, undefined, undefined]);
+test(stdioMacro, {stdio: []}, [undefined, undefined, undefined]);
+test(stdioMacro, {stdin: 'pipe'}, ['pipe', undefined, undefined]);
+test(stdioMacro, {stdout: 'ignore'}, [undefined, 'ignore', undefined]);
+test(stdioMacro, {stderr: 'inherit'}, [undefined, undefined, 'inherit']);
+test(stdioMacro, {stdin: 'pipe', stdout: 'ignore', stderr: 'inherit'}, ['pipe', 'ignore', 'inherit']);
+test(stdioMacro, {stdin: 'pipe', stdout: 'ignore'}, ['pipe', 'ignore', undefined]);
+test(stdioMacro, {stdin: 'pipe', stderr: 'inherit'}, ['pipe', undefined, 'inherit']);
+test(stdioMacro, {stdout: 'ignore', stderr: 'inherit'}, [undefined, 'ignore', 'inherit']);
+test(stdioMacro, {stdin: 0, stdout: 1, stderr: 2}, [0, 1, 2]);
+test(stdioMacro, {stdin: 0, stdout: 1}, [0, 1, undefined]);
+test(stdioMacro, {stdin: 0, stderr: 2}, [0, undefined, 2]);
+test(stdioMacro, {stdout: 1, stderr: 2}, [undefined, 1, 2]);
+
+test(stdioMacro, {stdio: {foo: 'bar'}}, new TypeError('Expected `stdio` to be of type `string` or `Array`, got `object`'));
+
+test(stdioMacro, {stdin: 'inherit', stdio: 'pipe'}, new Error('It\'s not possible to provide `stdio` in combination with one of `stdin`, `stdout`, `stderr`'));
+test(stdioMacro, {stdin: 'inherit', stdio: ['pipe']}, new Error('It\'s not possible to provide `stdio` in combination with one of `stdin`, `stdout`, `stderr`'));
+test(stdioMacro, {stdin: 'inherit', stdio: [undefined, 'pipe']}, new Error('It\'s not possible to provide `stdio` in combination with one of `stdin`, `stdout`, `stderr`'));
+
+const forkMacro = createMacro(stdio.node);
+
+test(forkMacro, undefined, ['pipe', 'pipe', 'pipe', 'ipc']);
+test(forkMacro, {stdio: 'ignore'}, ['ignore', 'ignore', 'ignore', 'ipc']);
+test(forkMacro, {stdio: [0, 1, 2]}, [0, 1, 2, 'ipc']);
+test(forkMacro, {stdio: [0, 1, 2, 3]}, [0, 1, 2, 3, 'ipc']);
+test(forkMacro, {stdio: [0, 1, 2, 'ipc']}, [0, 1, 2, 'ipc']);
+
+test(forkMacro, {stdout: 'ignore'}, ['pipe', 'ignore', 'pipe', 'ipc']);
+test(forkMacro, {stdout: 'ignore', stderr: 'ignore'}, ['pipe', 'ignore', 'ignore', 'ipc']);
+
+test(forkMacro, {stdio: {foo: 'bar'}}, new TypeError('Expected `stdio` to be of type `string` or `Array`, got `object`'));
+test(forkMacro, {stdin: 'inherit', stdio: 'pipe'}, new Error('It\'s not possible to provide `stdio` in combination with one of `stdin`, `stdout`, `stderr`'));