binary.md

Binary data

Binary output

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);

Encoding

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

Iterable

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

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 => { /* ... */ })

Transforms

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`;

Binary input

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`;