hook-std

What is hook-std?

The hook-std npm package allows you to hook into and modify the standard output (stdout) and standard error (stderr) streams in Node.js. This can be useful for capturing logs, testing console output, or redirecting output for various purposes.

What are hook-std's main functionalities?

Capture stdout

This feature allows you to capture and manipulate the standard output (stdout) stream. The code sample demonstrates how to capture console.log output and process it.

const hookStd = require('hook-std');

(async () => {
  const unhook = hookStd.stdout({silent: true}, output => {
    console.log('Captured output:', output);
  });

  console.log('This will be captured');

  await unhook();
})();

Capture stderr

This feature allows you to capture and manipulate the standard error (stderr) stream. The code sample demonstrates how to capture console.error output and process it.

const hookStd = require('hook-std');

(async () => {
  const unhook = hookStd.stderr({silent: true}, output => {
    console.error('Captured error:', output);
  });

  console.error('This error will be captured');

  await unhook();
})();

Modify stdout

This feature allows you to modify the standard output (stdout) stream before it is printed to the console. The code sample demonstrates how to prepend a string to the console.log output.

const hookStd = require('hook-std');

(async () => {
  const unhook = hookStd.stdout(output => {
    return 'Modified output: ' + output;
  });

  console.log('This will be modified');

  await unhook();
})();

Modify stderr

This feature allows you to modify the standard error (stderr) stream before it is printed to the console. The code sample demonstrates how to prepend a string to the console.error output.

const hookStd = require('hook-std');

(async () => {
  const unhook = hookStd.stderr(output => {
    return 'Modified error: ' + output;
  });

  console.error('This error will be modified');

  await unhook();
})();

Other packages similar to hook-std

capture-console

The capture-console package provides similar functionality to hook-std by allowing you to capture and manipulate stdout and stderr streams. However, it offers a simpler API and fewer customization options compared to hook-std.

intercept-stdout

The intercept-stdout package allows you to intercept and modify stdout and stderr streams. It is similar to hook-std but focuses more on simplicity and ease of use, with fewer advanced features.

stdout-stderr

The stdout-stderr package provides utilities to capture and manipulate stdout and stderr streams. It is similar to hook-std but offers a more straightforward API and is designed to be easy to integrate into testing frameworks.

README

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.