Description

This is a framework for showing multi-stage output in the terminal. It's integrated with oclif's builtin Performance capabilities so that perf metrics are automatically captured for each stage.

Features

Integrated Performance Tracking: this is integrated with oclif's builtin Performance capabilities so that perf metrics are automatically captured for each stage.
Responsive Design: elements will be added or removed based on the height of the terminal window. It even resizes itself if you resize the screen while the command is running.
CI Friendly Output: a simpler output will be shown inside non-tty environments like CI systems to avoid any excessive output that might be hard to read in CI logs.

Examples

You can see examples of how to use it in the examples directory.

You can run any of these with the following:

tsx examples/basic.ts

Usage

Basic Usage

const ms = new MultiStageOutput({
  jsonEnabled: false,
  stages: ['stage 1', 'stage 2', 'stage 3'],
  title: 'Basic Example',
})
// goto `stage 1`
ms.goto('stage 1')
// do some stuff

// goto `stage 2`
ms.goto('stage 2')

// As a convenience, use .next() to goto the next stage
ms.next()

// stop the multi-stage output from running anymore. Pass in an Error if applicable.
ms.stop()

Adding information blocks before or after the stages output.

You can add blocks on information before or after the list of stages. There are 3 kinds of information that can be displayed:

message: a simple string message
static-key-value: a simple key:value pair, e.g. name: Foo. If the value is undefined, the key will not be shown.
dynamic-key-value: a key:value pair where the value is expected to come in at an unknown time. This will display a spinner until the value is provided. If .stop is called with an error before the value is provided, then a ✘ will be displayed.

const ms = new MultiStageOutput<{message: string; staticValue: string; dynamicValue: string}>({
  jsonEnabled: false,
  stages: ['stage 1', 'stage 2', 'stage 3'],
  // preStagesBlock will be displayed BEFORE the list of stages
  preStagesBlock: [
    {
      get: (data) => data?.message,
      type: 'message',
    },
  ],
  // postStagesBlock will be displayed AFTER the list of stages
  postStagesBlock: [
    {
      get: (data) => data?.staticValue,
      label: 'Static',
      type: 'static-key-value',
    },
    {
      get: (data) => data?.dynamicValue,
      label: 'Dynamic',
      type: 'dynamic-key-value',
    },
  ],
})
// Goto `stage 1` and provide partial data to use for the information blocks
ms.goto('stage 1', {message: 'This is a message', staticValue: 'This is a static key:value pair'})

// Provide more data to use
ms.updateData({dynamicValue: 'This is a dynamic key:value pair'})

// Goto `stage 2` and provide more partial data
ms.goto('stage 2')

// Goto stage 3
ms.goto('stage 3')

ms.stop()

Adding information blocks on a specific stage

You can also add information blocks onto specific stages, which will nest the information underneath the stage.

const ms = new MultiStageOutput<{message: string; staticValue: string; dynamicValue: string}>({
  jsonEnabled: false,
  stageSpecificBlock: [
    // This will be nested underneath `stage 1`
    {
      get: (data) => data?.message,
      stage: 'one',
      type: 'message',
    },
    // This will be nested underneath `stage 2`
    {
      get: (data) => data?.staticValue,
      label: 'Static',
      stage: 'two',
      type: 'static-key-value',
    },
    // This will be nested underneath `stage 1`
    {
      get: (data) => data?.dynamicValue,
      label: 'Dynamic',
      stage: 'one',
      type: 'dynamic-key-value',
    },
  ],
  stages: ['stage 1', 'stage 2', 'stage 3'],
  title: 'Stage-Specific Information Block Example',
})

ms.goto('stage 1', {message: 'This is a message', staticValue: 'This is a static key:value pair'})

ms.goto('stage 2', {dynamicValue: 'This is a dynamic key:value pair'})

ms.goto('stage 3')

ms.stop()

Customizing the Design

You can customize the design of the multi-stage output using the design property:

const ms = new MultiStageOutput({
  jsonEnabled: false,
  stages: ['stage 1', 'stage 2', 'stage 3'],
  title: 'Basic Example',
  design: {
    title: {
      textColor: 'red',
    }
    icons: {
      completed: {
        figure: 'C',
        paddingLeft: 1,
        color: '#00FF00'
      }
    }
  }
})

See Design for all the options available to you.

Other Options

showElapsedTime: Optional. Whether or not to show the Elapsed Time at the bottom. Defaults to true
showStageTime: Optional. Whether or not to show the time for each stage. Defaults to true
title: Optional. The title to show at the top.
timerUnit: The unit to use for the elapsed time and stage time. Can be ms or s. Defaults to ms

Contributing

See the contributing guide.

oclif / multi-stage-output