binary.md

🤖 Binary data

Binary input

There are multiple ways to pass binary input using the stdin, input or inputFile options: Uint8Arrays, files, streams or other subprocesses.

This is required if the subprocess input includes null bytes.

import {execa} from 'execa';

const binaryData = new Uint8Array([/* ... */]);
await execa({stdin: binaryData})`hexdump`;

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.

const {stdout} = await execa({encoding: 'buffer'})`zip -r - input.txt`;
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'})`zip -r - input.txt`;
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'})`zip -r - input.txt`) {
	/* ... */
}

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 or not.

const transform = function * (data) {
	/* ... */
}

await execa({stdout: {transform, binary: true}})`zip -r - input.txt`;

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

---

Next: 🧙 Transforms
Previous: 📃 Text lines
Top: Table of contents