By default, the subprocess output is a UTF8 string. If it is binary, the encoding
option should be set to 'buffer'
instead. The output will be an Uint8Array
.
import {execa} from 'execa';
const {stdout} = await execa({encoding: 'buffer'})`unzip file.zip`;
console.log(stdout.byteLength);
When the output is binary, the encoding
option can also be set to 'hex'
, 'base64'
or 'base64url'
. The output will be a string then.
const {stdout} = await execa({encoding: 'hex'})`unzip file.zip`;
console.log(stdout); // Hexadecimal string
By default, the subprocess iterates over line strings. However, if the encoding
subprocess option is binary, or if the binary
iterable option is true
, it iterates over arbitrary chunks of Uint8Array
data instead.
for await (const data of execa({encoding: 'buffer'})`unzip file.zip`) { /* ... */ }
Streams produced by subprocess.readable()
and subprocess.duplex()
are binary by default, which means they iterate over arbitrary Buffer
chunks. However, if the binary
option is false
, they iterate over line strings instead, and the stream is in object mode.
const readable = execa`npm run build`.readable({binary: false});
readable.on('data', lineString => { /* ... */ })
The same applies to transforms. When the encoding
subprocess option is binary, or when the binary
transform option is true
, it iterates over arbitrary chunks of Uint8Array
data instead.
However, transforms can always yield
either a string
or an Uint8Array
, regardless of whether the output is binary.
const transform = function * (data) { /* ... */ }
await execa({stdout: {transform, binary: true}})`unzip file.zip`;
There are multiple ways to pass binary input using the stdin
, input
or inputFile
options. This includes using a Uint8Array
, a file, or a stream.
await execa({stdin: new Uint8Array([/* ... */])})`hexdump`;