Generalize {value, input} to any direction-ambiguous stdio value (#1249)

Author: sindresorhus

docs/api.md

@@ -916,14 +916,14 @@ More info on [available values](output.md), [streaming](streams.md) and [transfo
 ### options.stdio
 
 _TypeScript:_ [`Options['stdio']`](typescript.md) or [`SyncOptions['stdio']`](typescript.md)\
-_Type:_ `string | Array<string | number | stream.Readable | stream.Writable | ReadableStream | WritableStream | TransformStream | URL | {file: string} | Uint8Array | Iterable<string> | Iterable<Uint8Array> | Iterable<unknown> | AsyncIterable<string | Uint8Array | unknown> | GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown> | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream} | {value: 'pipe'; input?: boolean}>` (or a tuple of those types)\
+_Type:_ `string | Array<string | number | stream.Readable | stream.Writable | ReadableStream | WritableStream | TransformStream | URL | {file: string} | Uint8Array | Iterable<string> | Iterable<Uint8Array> | Iterable<unknown> | AsyncIterable<string | Uint8Array | unknown> | GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown> | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream} | {value: 'pipe' | 'inherit' | number | URL | {file: string} | GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown> | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}; input?: boolean}>` (or a tuple of those types)\
 _Default:_ `pipe`
 
 Like the [`stdin`](#optionsstdin), [`stdout`](#optionsstdout) and [`stderr`](#optionsstderr) options but for all [file descriptors](https://en.wikipedia.org/wiki/File_descriptor) at once. For example, `{stdio: ['ignore', 'pipe', 'pipe']}` is the same as `{stdin: 'ignore', stdout: 'pipe', stderr: 'pipe'}`.
 
 A single string can be used [as a shortcut](output.md#shortcut).
 
-The array can have more than 3 items, to create [additional file descriptors](output.md#additional-file-descriptors) beyond [`stdin`](#optionsstdin)/[`stdout`](#optionsstdout)/[`stderr`](#optionsstderr). Passing `'pipe'` to an additional file descriptor defaults it to output. To use it for [input](input.md#additional-file-descriptors) instead, pass `{value: 'pipe', input: true}`.
+The array can have more than 3 items, to create [additional file descriptors](output.md#additional-file-descriptors) beyond [`stdin`](#optionsstdin)/[`stdout`](#optionsstdout)/[`stderr`](#optionsstderr). Some values have an ambiguous direction on an additional file descriptor (like `'pipe'`, `'inherit'`, a file or a transform), so they default to output. To use one for [input](input.md#additional-file-descriptors) instead, wrap it as `{value, input: true}`.
 
 More info on [available values](output.md), [streaming](streams.md) and [transforms](transform.md).
 

docs/input.md

@@ -135,7 +135,7 @@ await execa({
 })`npm run build`;
 ```
 
-When passing `'pipe'` to an additional file descriptor, Execa cannot tell whether it is meant for input or output, so it defaults to output. To use it for input instead, such as when [streaming](streams.md#different-file-descriptor) to it, pass `{value: 'pipe', input: true}`.
+Some values have an ambiguous direction on an additional file descriptor: Execa cannot tell whether they are meant for input or output, so they default to output. This applies to `'pipe'`, `'inherit'`, [files](output.md#file-output) and [transforms](transform.md). To use one for input instead, such as when [streaming](streams.md#different-file-descriptor) to it, wrap it as `{value, input: true}`.
 
 ```js
 import {pipeline} from 'node:stream/promises';

lib/stdio/direction.js

@@ -22,7 +22,18 @@ export const getStreamDirection = (stdioItems, fdNumber, optionName) => {
 
 // `direction` is set when the user explicitly requests it, e.g. `{value: 'pipe', input: true}`.
 // It takes precedence over guessing, but not over the fixed direction of `stdin`/`stdout`/`stderr`.
-const getStdioItemDirection = ({type, value, direction}, fdNumber) => KNOWN_DIRECTIONS[fdNumber] ?? direction ?? guessStreamDirection[type](value);
+const getStdioItemDirection = (stdioItem, fdNumber) => KNOWN_DIRECTIONS[fdNumber] ?? getRequestedDirection(stdioItem);
+
+// The explicitly requested `direction` must not contradict a value that is intrinsically the other direction.
+// For example, `{value: writableStream, input: true}` is invalid since a writable value can only be an output.
+const getRequestedDirection = ({type, value, direction, optionName}) => {
+	const guessedDirection = guessStreamDirection[type](value);
+	if (direction === 'input' && guessedDirection === 'output') {
+		throw new TypeError(`The \`${optionName}\` option is invalid: \`input: true\` cannot be used with a writable value, which is always an output.`);
+	}
+
+	return direction ?? guessedDirection;
+};
 
 // `stdin`/`stdout`/`stderr` have a known direction
 const KNOWN_DIRECTIONS = ['input', 'output', 'output'];

lib/stdio/handle.js

@@ -5,7 +5,7 @@ import {
 	getStdioItemType,
 	isRegularUrl,
 	isUnknownStdioString,
-	isPipeInputObject,
+	isStdioValueObject,
 	checkBooleanOption,
 	FILE_TYPES,
 } from './type.js';
@@ -85,8 +85,8 @@ const isInheritedStdinOnly = stdioItems => stdioItems.length === 1
 	&& stdioItems[0].value === 'inherit';
 
 const initializeStdioItem = (value, optionName) => {
-	if (isPipeInputObject(value)) {
-		return initializePipeInputItem(value, optionName);
+	if (isStdioValueObject(value)) {
+		return initializeStdioValueObject(value, optionName);
 	}
 
 	return {
@@ -96,12 +96,12 @@ const initializeStdioItem = (value, optionName) => {
 	};
 };
 
-// The `{value: 'pipe', input: true}` object form is a native pipe, plus an explicit input direction.
-const initializePipeInputItem = ({value, input}, optionName) => {
+// The `{value, input}` object form wraps any stdio value with an explicit direction.
+const initializeStdioValueObject = ({value, input}, optionName) => {
 	checkBooleanOption(input, `${optionName}.input`);
 
 	return {
-		type: 'native',
+		type: getStdioItemType(value, optionName),
 		value,
 		direction: input ? 'input' : undefined,
 		optionName,

lib/stdio/stdio-option.js

@@ -1,7 +1,7 @@
 import {STANDARD_STREAMS_ALIASES} from '../utils/standard-stream.js';
 import {normalizeIpcStdioArray} from '../ipc/array.js';
 import {isFullVerbose} from '../verbose/values.js';
-import {isPipeInputObject} from './type.js';
+import {isStdioValueObject} from './type.js';
 
 // Add support for `stdin`/`stdout`/`stderr` as an alias for `stdio`.
 // Also normalize the `stdio` option.
@@ -15,11 +15,27 @@ export const normalizeStdioOption = ({stdio, ipc, buffer, ...options}, verboseIn
 
 // The `stdio: 'ipc'` value (raw `child_process` syntax) was replaced by the `ipc: true` option
 const validateIpcStdioOption = stdioArray => {
-	if (stdioArray.some(stdioOption => Array.isArray(stdioOption) ? stdioOption.includes('ipc') : stdioOption === 'ipc')) {
+	if (stdioArray.some(stdioOption => hasIpcStdioOption(stdioOption))) {
 		throw new Error('The `ipc: true` option must be used instead of `stdio: \'ipc\'`.');
 	}
 };
 
+const hasIpcStdioOption = stdioOption => {
+	if (Array.isArray(stdioOption)) {
+		return stdioOption.some(item => hasIpcStdioItem(item));
+	}
+
+	return hasIpcStdioItem(stdioOption);
+};
+
+const hasIpcStdioItem = stdioOption => {
+	if (isStdioValueObject(stdioOption)) {
+		return stdioOption.value === 'ipc';
+	}
+
+	return stdioOption === 'ipc';
+};
+
 const getStdioArray = (stdio, options) => {
 	if (stdio === undefined) {
 		return STANDARD_STREAMS_ALIASES.map(alias => options[alias]);
@@ -71,7 +87,7 @@ const isOutputPipeOnly = (stdioOption, fdNumber) => isOutputPipe(stdioOption, fd
 const isOutputPipe = (stdioOption, fdNumber) => stdioOption === 'pipe'
 	|| isOutputPipeObject(stdioOption, fdNumber);
 
-const isOutputPipeObject = (stdioOption, fdNumber) => isPipeInputObject(stdioOption)
+const isOutputPipeObject = (stdioOption, fdNumber) => isStdioValueObject(stdioOption)
 	&& stdioOption.value === 'pipe'
 	&& (stdioOption.input === undefined || stdioOption.input === false || isFixedOutputPipe(fdNumber, stdioOption.input));
 

lib/stdio/type.js

@@ -130,14 +130,13 @@ const isFilePathObject = value => isPlainObj(value)
 const FILE_PATH_KEYS = new Set(['file', 'append']);
 export const isFilePathString = file => typeof file === 'string';
 
-// The `{value: 'pipe', input: true}` object form marks an additional file descriptor as input instead of output.
-// This is only needed for `'pipe'`/`'overlapped'` on fd3+, whose direction is otherwise ambiguous and defaults to output.
-export const isPipeInputObject = value => isPlainObj(value)
+// The `{value, input}` object form marks an additional file descriptor's direction explicitly.
+// This is needed for direction-ambiguous values (like `'pipe'`, `'inherit'`, a file or a transform) on fd3+, which otherwise default to output.
+export const isStdioValueObject = value => isPlainObj(value)
 	&& Object.keys(value).length > 0
-	&& Object.keys(value).every(key => PIPE_INPUT_KEYS.has(key))
-	&& NATIVE_PIPE_VALUES.has(value.value);
-const PIPE_INPUT_KEYS = new Set(['value', 'input']);
-const NATIVE_PIPE_VALUES = new Set(['pipe', 'overlapped']);
+	&& Object.keys(value).every(key => STDIO_VALUE_KEYS.has(key))
+	&& 'value' in value;
+const STDIO_VALUE_KEYS = new Set(['value', 'input']);
 
 export const isUnknownStdioString = (type, value) => type === 'native'
 	&& typeof value === 'string'

test-d/return/result-stdio.test-d.ts

@@ -114,6 +114,12 @@ expectType<undefined>(inputFd3Result.stdio[3]);
 const inputPipeFd3Result = await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 'pipe', input: true}]});
 expectType<undefined>(inputPipeFd3Result.stdio[3]);
 
+const inputInheritFd3Result = await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 'inherit', input: true}]});
+expectType<undefined>(inputInheritFd3Result.stdio[3]);
+
+const inputFdFd3Result = await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 3, input: true}]});
+expectType<undefined>(inputFdFd3Result.stdio[3]);
+
 const outputPipeFd3Result = await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 'pipe'}]});
 expectType<string>(outputPipeFd3Result.stdio[3]);
 

test-d/stdio/option/input-pipe.test-d.ts

@@ -1,3 +1,4 @@
+import {Writable} from 'node:stream';
 import {expectError, expectAssignable} from 'tsd';
 import {
 	execa,
@@ -11,6 +12,9 @@ import {
 const inputPipe = {value: 'pipe', input: true} as const;
 const input = true as boolean;
 const booleanInputPipe = {value: 'pipe', input} as const;
+const transform = function * (line: string) {
+	yield line;
+};
 
 await execa('unicorns', {stdin: inputPipe});
 execaSync('unicorns', {stdin: inputPipe});
@@ -31,6 +35,17 @@ expectError(execaSync('unicorns', {stdin: {value: 'overlapped', input: true}}));
 expectError(await execa('unicorns', {stdin: {value: 'other', input: true}}));
 expectError(await execa('unicorns', {stdin: {value: 'pipe', input: 'true'}}));
 
+// The `{value, input}` form works with any direction-ambiguous value, not just `'pipe'`/`'overlapped'`.
+await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 'inherit', input: true}]});
+await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: new URL('file:///test'), input: true}]});
+await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: {file: './example'}, input: true}]});
+await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: transform, input: true}]});
+expectAssignable<StdinOption>({value: 'inherit', input: true});
+expectAssignable<StdinOption>({value: {file: './example'}, input: true});
+
+// A value with a fixed direction cannot be marked as input.
+expectError(await execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: new Writable(), input: true}]}));
+
 expectAssignable<StdinOption>(inputPipe);
 expectAssignable<StdinOption>(booleanInputPipe);
 expectAssignable<StdinSyncOption>(inputPipe);

test-d/subprocess/stdio.test-d.ts

@@ -46,6 +46,15 @@ expectType<Writable>(inputPipeSubprocess.stdio[3]);
 const outputPipeSubprocess = execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 'pipe'}]});
 expectType<Readable>(outputPipeSubprocess.stdio[3]);
 
+const inputInheritSubprocess = execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 'inherit', input: true}]});
+expectType<null>(inputInheritSubprocess.stdio[3]);
+
+const inputFdSubprocess = execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 3, input: true}]});
+expectType<null>(inputFdSubprocess.stdio[3]);
+
+const inputFileSubprocess = execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: {file: './example'}, input: true}]});
+expectType<Writable>(inputFileSubprocess.stdio[3]);
+
 const input = true as boolean;
 const booleanInputPipeSubprocess = execa('unicorns', {stdio: ['pipe', 'pipe', 'pipe', {value: 'pipe', input}]});
 expectType<Readable | Writable>(booleanInputPipeSubprocess.stdio[3]);

test/stdio/direction.js

@@ -60,6 +60,36 @@ const testDirectionInputPipe = async (t, stdioOption) => {
 test('stdio[*] { value: "pipe", input: true } sets the direction to input', testDirectionInputPipe, {value: 'pipe', input: true});
 test('stdio[*] { value: "overlapped", input: true } sets the direction to input', testDirectionInputPipe, {value: 'overlapped', input: true});
 
+const uppercaseGenerator = function * (line) {
+	yield line.toUpperCase();
+};
+
+test('stdio[*] { value: generator, input: true } sets the direction to input', async t => {
+	const subprocess = execa('stdin-fd.js', ['3'], getStdio(3, {value: uppercaseGenerator, input: true}));
+	subprocess.stdio[3].end(foobarString);
+	const {stdout} = await subprocess;
+	t.is(stdout, foobarString.toUpperCase());
+});
+
+test('stdio[*] { value: {file}, input: true } sets the direction to input', async t => {
+	const filePath = tempfile();
+	await writeFile(filePath, foobarString);
+	const {stdout} = await execa('stdin-fd.js', ['3'], getStdio(3, {value: {file: filePath}, input: true}));
+	t.is(stdout, foobarString);
+	await rm(filePath);
+});
+
+const testInputFixedDirection = (t, stdioOption, execaMethod) => {
+	t.throws(() => {
+		execaMethod('empty.js', getStdio(3, {value: stdioOption, input: true}));
+	}, {message: /cannot be used with a writable value/});
+};
+
+test('stdio[*] { value: WritableStream, input: true } is invalid', testInputFixedDirection, new WritableStream(), execa);
+test('stdio[*] { value: WritableStream, input: true } is invalid - sync', testInputFixedDirection, new WritableStream(), execaSync);
+test('stdio[*] { value: process.stdout, input: true } is invalid', testInputFixedDirection, process.stdout, execa);
+test('stdio[*] { value: process.stdout, input: true } is invalid - sync', testInputFixedDirection, process.stdout, execaSync);
+
 test('stdio[*] { value: "pipe", input: true } cannot be used in sync mode', t => {
 	t.throws(() => {
 		execaSync('empty.js', getStdio(3, {value: 'pipe', input: true}));