cli-progress-footer

cli-progress-footer

Manage dynamic progress content below std output stream

Content agnostic. For reliable output all of process std output needs go through this utility. To ensure that by default process.stdout.write is overriden and process.stderr is redirected into process.stdout (with possibility to opt out from both).

Installation

npm install cli-progress-footer

Usage

const cliProgressFooter = require("cli-progress-footer")();

// Write progress
cliProgresssFooter.updateProgress("# processing 1\n# processing 2\n# processing 3\n");
...
// Update progress content when necessary
cliProgresssFooter.updateProgress("# processing 2\n# processing 3\n# processing 4\n");
...
// Update progress content when necessary
cliProgresssFooter.updateProgress("# processing 3\n# processing 4\n");

By default both stdout and stderr output is automatically handled and ensured to appear above progress content

Options

overrideStdout bool (default: true)

Whether to override data written to process.stdout stream so it appears in all cases above progress bar. Modified writes are passed immediately to native process.stdout.write so there's no risk of losing some log content or seing it out of sync

You may opt out but then if any content is written to process.stdout, process output may appear as not reliable.

When opting out you may write regular log content via cliProgressFooter.writeStdout(data)

redirectStderr bool (default: true)

When progress footer is in play, all output should be treated as one std stream. If it's not the case then any stderr output may break visible log output. Therefore by default all stderr content is redirected to stdout.

If you wish to redirect stderr somewhere else with cli means, then it's best turn this function off (so proces.stderr.write is not overriden)

discardStdin bool (default: true)

Whether to mute stdin input (so it doesn't add to displayed progress output). In scope of that setting also cursor is hidden

workaroundChildProcess bool (default: true)

Whether to hide a progress bar for a time being of child process runs with inherited stdio.

Problem is that output of such processes cannot be controlled, and if happens will break the progress bar output.

Internal workaround is to decorate child_process module functions, and react accordingly whenever problematic child process is created

Throbber animation

Additionally each progress line may be automatically prefixed with throbber (frames customizable at cliProgresssFooter.progressAnimationPrefixFrames), for that apply following setting:

cliProgressFooter.shouldAddProgressAnimationPrefix = true;

Tests

npm test

Changelog

2.3.3 (2024-02-29)

Bug Fixes

• Ensure \r chars do not break progress output (888af14)

Maintenance Improvements

• Exclude updateProgress method (48bc757)