Add pipeStdin() method

[ehmicky]

#531 added pipeStdout(), pipeStderr() and pipeAll() to redirect a child process's stdout/stderr to another process, a stream or a file.

For completeness and convenience, we should add a similar pipeStdin() which would redirect another process stdout, stream or file to a child process stdin.

This pattern is currently already documented in our Tips section.

const subprocess = execa('cat')
fs.createReadStream('stdin.txt').pipe(subprocess.stdin)
await subprocess

This would simplify it to:

await execa('cat').pipeStdin('stdin.txt')

[sindresorhus]

await execa('cat').pipeStdin('stdin.txt') reads to me as we are piping cat into stdin.txt, but we are doing the reverse.

Maybe:

await execa('cat').pipeToStdinFrom('stdin.txt')

[ehmicky]

Yes, I was also thinking users might not realize things are done from a reverse direction than pipeStdout() and the likes. pipeToStdinFrom() sounds good 👍

I'm going to take up this PR right now. 🧑‍🏭

[ehmicky]

I implemented it in #535. Doing so gave me some additional insights in terms of overall experience as I wrote tests and documentation for it. And now, it feels to me like this method is not as useful as pipeStdout()/pipeStderr()/pipeAll():

• Users might be confused about the direction being reversed from pipeStdout()
• Unlike pipeStdout(), the flow of data is different from the flow of the code. It makes more sense for processes that are later in the pipe order to come last in the code itself. The current pattern $({ input: process.stdin })`cat` follows that order, but not $`cat`.pipeToStdinFrom(process.stdin)
• The input option already fills this feature for streams. It also supports raw data. When it comes to processes, pipeStdout() can be used, after flipping the order of the processes in the code.

So pipeToStdinFrom() would only facilitate reading from a file, by specifying 'input.txt' instead of fs.createReadStream('input.txt').

Based on this, I do not think it is worth the additional complexity introduced to the API.

On the other hand, we could improve the documentation to highlight the above patterns, so I opened #536 for this.

[sindresorhus]

I agree with your assessment.

[sindresorhus]

Do you think a `$({inputFromFile: 'input.txt'})`cat` option would be useful as a shortcut? Piping from a file is quite a common use-case.

[ehmicky]

Yes, I agree it would.

Naming-wise, would inputFile be good too? I am wondering whether it might shorter yet clear enough. 🤔

[sindresorhus]

inputFile is good 👍

[ehmicky]

Done in #542.