@sigill/watch-your-step NPM

watch-your-step

Minimal ~~task~~ step runner.

It was designed with build-scripts in mind. Those often rely on external tools (e.g. CMake, Ninja...) that can produce lots of logs, which does not play nice with fancy task runners with dynamic logging capabilities like Listr2 or Tasuku.

Install

npm i @sigill/watch-your-step

Usage

import { step } from '@sigill/watch-your-step'

step({
  title: 'Main step',
  action: () => {
    step('Substep 1', () => {
      console.log('Working on substep 1...');
    });

    step({
      title: 'Substep 2',
      skip: () => 'We are skipping that step',
      action: () => {
        console.log('Working on substep 2...');
      }
    });

    step({
      title: 'Substep 3',
      action: () => {
        console.log('Working on substep 3...');
        throw new Error('something went wrong');
      }
    });
}});

// [STARTED] Main step
// [STARTED] Substep 1
// Working on substep 1...
// [SUCCESS] Substep 1 (0ms)
// [SKIPPED] Substep 2 (We are skipping that step)
// [STARTED] Substep 3
// Working on substep 3...
// [FAILURE] Substep 3 (1ms)
// [FAILURE] Main step (4ms)
// Error: something went wrong
//     at action (file://[...]/example.ts:22:15)
//     ...

To use a custom logger:

import { ConsoleLogger, makeStepFunction } from './index.js';

const logger = new ConsoleLogger({useGroup: true}); // Or any custom logger.
const step = makeStepFunction(logger);

step(...);

API

`step<T>(spec)`, `step<T>(title, action)`

Executes an action.

The various prototypes of this function are just provided to enhance type-checking. In particular, if the step is skippable, its return value can be undefined.

Parameters

spec (Step<T>, required) - The action to execute.
- title (string, required) - Title of the step.
- action (() => T, required) - The action to execute. If it is asynchronous, T is a Promise.
- skip (() => string | boolean, optional) - If thuthy, skips the action. If the returned value is a string, its value should describe why the action has been skipped.