hook-std

Hook and modify stdout and stderr

Install

npm install hook-std

Usage

import assert from 'node:assert';
import {hookStdout} from 'hook-std';

const promise = hookStdout(output => {
	promise.unhook();
	assert.strictEqual(output.trim(), 'unicorn');
});

console.log('unicorn');
await promise;

You can also unhook using the second transform method parameter:

import assert from 'node:assert';
import {hookStdout} from 'hook-std';

const promise = hookStdout((output, unhook) => {
	unhook();
	assert.strictEqual(output.trim(), 'unicorn');
});

console.log('unicorn');
await promise;

Automatically collect output without a transform function:

import {hookStdout} from 'hook-std';

const promise = hookStdout();
console.log('unicorn');
console.log('rainbow');
console.log(promise.output); // 'unicorn\nrainbow\n'
promise.unhook();
await promise;

API

hookStd(options?, transform?)

Hook streams in streams option, or stdout and stderr if none are specified.

Returns a Promise with a unhook() method which, when called, unhooks both stdout and stderr and resolves the Promise with an empty result. The returned promise also has an output property to access the collected output.

When hooking multiple streams, the output property contains the interleaved output in the order the writes occurred:

import {hookStd} from 'hook-std';

const promise = hookStd();
process.stdout.write('A');
process.stderr.write('B');
process.stdout.write('C');
console.log(promise.output); // 'ABC' (interleaved in order)
promise.unhook();

hookStdout(options?, transform?)

Hook stdout.

Returns a Promise with a unhook() method which, when called, unhooks stdout and resolves the Promise with an empty result. The returned promise also has an output property to access the collected output.

hookStderr(options?, transform?)

Hook stderr.

Returns a Promise with a unhook() method which, when called, unhooks stderr and resolves the Promise with an empty result. The returned promise also has an output property to access the collected output.

options

Type: object

silent

Type: boolean
Default: true

Suppress stdout/stderr output.

once

Type: boolean
Default: false

Automatically unhook after the first call.

streams

Type: stream.Writable[]
Default: [process.stdout, process.stderr]

The writable streams to hook. This can be useful for libraries allowing users to configure a writable stream to write to.

transform

Type: Function

Receives stdout/stderr as the first argument and the unhook method as the second argument. Return a string to modify it. Optionally, when in silent mode, you may return a boolean to influence the return value of .write(…).

Output is automatically collected and can be accessed via the output property of the returned promise, regardless of whether a transform function is provided.