@ms-cloudpack/task-reporter

A library for standardizing how tasks are logged to the console.

Example usage

1. Create a reporter:

const taskReporter = new TaskReporter({
  productName: `Foobar`,
  version: `1.2.3`,
  description: `running tasks with ${bold(`15`)} workers`,
  showStarted: false,
  showPending: true,
  showCompleted: true,
  showSummary: true,
  showTaskDetails: true,
});

2. Run tasks with the reporter runTask method:

await taskReporter.runTask(`build something`, async () => {
  // ...do async things.

  return {
    status: 'fail' // default: 'complete'
    message: 'optional message',
    details: 'optional details',
    extended: 'optional debugging info'
  }
});

2b. For tasks that may not be easily encapsulated within a wrapper function, you can use the addTask method:

const task = taskReporter.addTask(`build something`, /* initially idle */ true);

// When you are starting the task, you can call start:
try {
  task.start();
} finally {
  task.complete({ status: 'complete' /* etc */ });
}

3. You can use various formatting helpers to spice up the colorization and formatting of your logging:

// Fail example, with provide details:
import { bulletedList } from '@ms-cloudpack/task-reporter';

task.complete({
  status: 'fail',
  message: 'Reason',
  details: bulletedList(['Name: value', 'Errors:', ['sub-bullet things', 'etc'], 'Warnings', ['warn1', etc]]),
});

For formatting details, a variety of style helpers can be imported.

import { cyan, bold, red } from '@ms-cloudpack/task-reporter';

task.complete('fail', { message: cyan(bold(`I am an ${red(`error`)}`)) });

1. When all your tasks are completed, or if you encountered an exit-early scenario, call reporter.complete('reason') to end task logging:

// You can instruct the reporter to complete when all tasks are done.
reporter.completeWhenTasksDone();

// Or, you can manually tell it to complete at any point. For example, you may want to complete things when the
// users hits ctrl-c. Prematurely completing means pending tasks will be skipped and running tasks will be aborted.
process.on('SIGINT', () => {
  reporter.complete('User hit Ctrl-C');
});