Add inputFile option (#542)

Author: ehmicky

docs/scripts.md

@@ -635,7 +635,7 @@ await cat
 
 ```js
 // Execa
-await $({input: fs.createReadStream('file.txt')})`cat`
+await $({inputFile: 'file.txt'})`cat`
 ```
 
 ### Silent stderr

index.d.ts

@@ -258,15 +258,33 @@ export type CommonOptions<EncodingType> = {
 export type Options<EncodingType = string> = {
 	/**
 	Write some input to the `stdin` of your binary.
+
+	If the input is a file, use the `inputFile` option instead.
 	*/
 	readonly input?: string | Buffer | ReadableStream;
+
+	/**
+	Use a file as input to the the `stdin` of your binary.
+
+	If the input is not a file, use the `input` option instead.
+	*/
+	readonly inputFile?: string;
 } & CommonOptions<EncodingType>;
 
 export type SyncOptions<EncodingType = string> = {
 	/**
 	Write some input to the `stdin` of your binary.
+
+	If the input is a file, use the `inputFile` option instead.
 	*/
 	readonly input?: string | Buffer;
+
+	/**
+	Use a file as input to the the `stdin` of your binary.
+
+	If the input is not a file, use the `input` option instead.
+	*/
+	readonly inputFile?: string;
 } & CommonOptions<EncodingType>;
 
 export type NodeOptions<EncodingType = string> = {

index.js

@@ -10,7 +10,7 @@ import {makeError} from './lib/error.js';
 import {normalizeStdio, normalizeStdioNode} from './lib/stdio.js';
 import {spawnedKill, spawnedCancel, setupTimeout, validateTimeout, setExitHandler} from './lib/kill.js';
 import {addPipeMethods} from './lib/pipe.js';
-import {handleInput, getSpawnedResult, makeAllStream, validateInputSync} from './lib/stream.js';
+import {handleInput, getSpawnedResult, makeAllStream, handleInputSync} from './lib/stream.js';
 import {mergePromise, getSpawnedPromise} from './lib/promise.js';
 import {joinCommand, parseCommand, parseTemplates, getEscapedCommand} from './lib/command.js';
 import {logCommand, verboseDefault} from './lib/verbose.js';
@@ -159,7 +159,7 @@ export function execa(file, args, options) {
 
 	const handlePromiseOnce = onetime(handlePromise);
 
-	handleInput(spawned, parsed.options.input);
+	handleInput(spawned, parsed.options);
 
 	spawned.all = makeAllStream(spawned, parsed.options);
 
@@ -174,11 +174,11 @@ export function execaSync(file, args, options) {
 	const escapedCommand = getEscapedCommand(file, args);
 	logCommand(escapedCommand, parsed.options);
 
-	validateInputSync(parsed.options);
+	const input = handleInputSync(parsed.options);
 
 	let result;
 	try {
-		result = childProcess.spawnSync(parsed.file, parsed.args, parsed.options);
+		result = childProcess.spawnSync(parsed.file, parsed.args, {...parsed.options, input});
 	} catch (error) {
 		throw makeError({
 			error,

index.test-d.ts

@@ -134,6 +134,7 @@ execa('unicorns', {buffer: false});
 execa('unicorns', {input: ''});
 execa('unicorns', {input: Buffer.from('')});
 execa('unicorns', {input: process.stdin});
+execa('unicorns', {inputFile: ''});
 execa('unicorns', {stdin: 'pipe'});
 execa('unicorns', {stdin: 'overlapped'});
 execa('unicorns', {stdin: 'ipc'});

lib/stream.js

@@ -1,9 +1,47 @@
+import {createReadStream, readFileSync} from 'node:fs';
 import {isStream} from 'is-stream';
 import getStream from 'get-stream';
 import mergeStream from 'merge-stream';
 
-// `input` option
-export const handleInput = (spawned, input) => {
+const validateInputOptions = input => {
+	if (input !== undefined) {
+		throw new TypeError('The `input` and `inputFile` options cannot be both set.');
+	}
+};
+
+const getInputSync = ({input, inputFile}) => {
+	if (typeof inputFile !== 'string') {
+		return input;
+	}
+
+	validateInputOptions(input);
+	return readFileSync(inputFile);
+};
+
+// `input` and `inputFile` option in sync mode
+export const handleInputSync = options => {
+	const input = getInputSync(options);
+
+	if (isStream(input)) {
+		throw new TypeError('The `input` option cannot be a stream in sync mode');
+	}
+
+	return input;
+};
+
+const getInput = ({input, inputFile}) => {
+	if (typeof inputFile !== 'string') {
+		return input;
+	}
+
+	validateInputOptions(input);
+	return createReadStream(inputFile);
+};
+
+// `input` and `inputFile` option in async mode
+export const handleInput = (spawned, options) => {
+	const input = getInput(options);
+
 	if (input === undefined) {
 		return;
 	}
@@ -79,9 +117,3 @@ export const getSpawnedResult = async ({stdout, stderr, all}, {encoding, buffer,
 		]);
 	}
 };
-
-export const validateInputSync = ({input}) => {
-	if (isStream(input)) {
-		throw new TypeError('The `input` option cannot be a stream in sync mode');
-	}
-};

readme.md

@@ -128,7 +128,7 @@ await execa('echo', ['unicorns'], {all:true}).pipeAll('all.txt');
 import {execa} from 'execa';
 
 // Similar to `cat < stdin.txt` in Bash
-const {stdout} = await execa('cat', {input:fs.createReadStream('stdin.txt')});
+const {stdout} = await execa('cat', {inputFile:'stdin.txt'});
 console.log(stdout);
 //=> 'unicorns'
 ```
@@ -497,6 +497,16 @@ Type: `string | Buffer | stream.Readable`
 Write some input to the `stdin` of your binary.\
 Streams are not allowed when using the synchronous methods.
 
+If the input is a file, use the [`inputFile` option](#inputfile) instead.
+
+#### inputFile
+
+Type: `string`
+
+Use a file as input to the the `stdin` of your binary.
+
+If the input is not a file, use the [`input` option](#input) instead.
+
 #### stdin
 
 Type: `string | number | Stream | undefined`\

test/stream.js

@@ -71,6 +71,19 @@ test('input can be a Stream', async t => {
 	t.is(stdout, 'howdy');
 });
 
+test('inputFile can be set', async t => {
+	const inputFile = tempfile();
+	fs.writeFileSync(inputFile, 'howdy');
+	const {stdout} = await execa('stdin.js', {inputFile});
+	t.is(stdout, 'howdy');
+});
+
+test('inputFile and input cannot be both set', t => {
+	t.throws(() => execa('stdin.js', {inputFile: '', input: ''}), {
+		message: /cannot be both set/,
+	});
+});
+
 test('you can write to child.stdin', async t => {
 	const subprocess = execa('stdin.js');
 	subprocess.stdin.end('unicorns');
@@ -105,6 +118,19 @@ test('helpful error trying to provide an input stream in sync mode', t => {
 	);
 });
 
+test('inputFile can be set - sync', t => {
+	const inputFile = tempfile();
+	fs.writeFileSync(inputFile, 'howdy');
+	const {stdout} = execaSync('stdin.js', {inputFile});
+	t.is(stdout, 'howdy');
+});
+
+test('inputFile and input cannot be both set - sync', t => {
+	t.throws(() => execaSync('stdin.js', {inputFile: '', input: ''}), {
+		message: /cannot be both set/,
+	});
+});
+
 test('maxBuffer affects stdout', async t => {
 	await t.notThrowsAsync(execa('max-buffer.js', ['stdout', '10'], {maxBuffer: 10}));
 	const {stdout, all} = await t.throwsAsync(execa('max-buffer.js', ['stdout', '11'], {maxBuffer: 10, all: true}), {message: /max-buffer.js stdout/});