@darkobits/log

A logger for CLIs. Noop.

Contents

• Features
• Install
• Basic Usage
• API
  • .chalk
  • #configure
  • #getLevel
  • #getLevels
  • #isLevelAtLeast
  • #prefix
  • #addSecret
  • #createPipe
  • #beginInteractive
  • #createTimer
  • #createProgressBar
  • #createSpinner
• Debug Support
• Caveats

Features

• Highly Configurable
• Chalk-included
• Interactive Mode
• Timers
• Spinners
• Progress Bars

Install

$ npm i @darkobits/log

Basic Usage

This package's default export is a factory function that accepts an options object.

If the level option is omitted, the log level will be set to process.env.LOG_LEVEL if set. Otherwise, it will be set to info.

Example:

import LogFactory from '@darkobits/log';

const log = LogFactory({heading: 'myApp'});

log.info(`Now you're thinking with ${log.chalk.bold('Portals')}!`);

API

This section documents the properties and methods of each logger instance. The examples below assume a logger (referred to as log) has already been created.

.chalk

To afford a convenient way to style log messages, the logger creates a custom Chalk instance for each logger, the options for which are configurable. By creating a custom Chalk instance, the logger avoids conflicting with the default/global Chalk instance that may be in use by other parts of an application.

Example:

log.info(`Have a ${log.chalk.bold.pink('fabulous')} day!`);

configure(config: Partial<LogOptions>): void

Configure/re-configure the logger instance. The provided object will be deep-merged with the logger's existing configuration. This method can therefore be used to accomplish things like:

• Adding log levels.
• Changing the styling for existing log levels and other tokens.
• Changing the log level.

Example:

// Change the log level.
log.configure({level: 'verbose'});

// Add a new log level.
log.configure({
  levels: {
    foo: {
      level: 5000,
      label: 'FOO!',
      style: (token, chalk) => chalk.keyword('blue')(token)
    }
  }
});

getLevel(): LevelDescriptor

Returns a LevelDescriptor object for the current log level.

Example:

Assuming the current level is info:

const curLevel = log.getLevel();

curLevel.label //=> 'info'
curLevel.level //=> 6000
curLevel.style //=> StyleFunction

getLevels(): {[key: string]: LevelDescriptor}

Returns an object mapping log level names (ex: info) to LevelDescriptor objects for each configured level. Note: The logger does not implement a method for the silent level.

isLevelAtLeast(name: string): boolean

Returns true if a message written at the provided log level would be written to the output stream based on the current log level.

Example:

log.configure({level: 'info'});
log.isLevelAtLeast('error') //=> true
log.isLevelAtLeast('silly') //=> false

prefix(prefix: Primitive): Prefix

Applies a prefix, styled according to the logger's style.prefix options, to each line written to the output stream for the current call.

Example:

log.info(log.prefix('someFunction'), 'Hello\nworld.');

addSecret(secret: Primitive | RegExp, maskChar = '*'): void

This method may be used to ensure passwords and other sensitive information are not inadvertently written to the output stream. It accepts either a string literal or a regular expression and an optional mask character. By default, secrets are masked using *.

Example:

const user = {
  name: 'Frodo',
  password: 'shire'
};

log.addSecret(user.password);
log.info('User data:', user);

createPipe(level: string): NodeJS.WritableStream

Creates a writable stream that will output any data written to it as log messages at the indicated level. Useful for displaying the output of a child process, for example.

In the following example, all output written to process.stderr by the child process will be written as log messages at the verbose level.

Example:

import execa from 'execa';

log.info('Starting child process...');

const childProcess = execa('echo', ['"I am a banana!"'], {stdout: 'pipe'});
childProcess.stdout.pipe(log.createPipe('verbose'));

await childProcess;

log.info('Done.');

beginInteractive(MessageFn | BeginInteractiveOptions): EndInteractiveFn

Begins a new interactive session and returns a function that may be invoked to end the interactive session. This method accepts either an options object or a function that will be invoked to render each update during the interactive session. If a custom interval is not being used, the shorthand (message function only) form is recommended.

The function returned by beginInteractive accepts a function that will be invoked to produce the final content written to the interactive line(s).

Example:

const spinner = log.createSpinner();
const time = log.createTimer();
const endInteractive = log.beginInteractive(() => log.info(`${spinner} Please stand by...`));

// Some time later...

endInteractive(() => log.info(`Done in ${time}.`));

> screenshot(s) here

createTimer(options?: TimerOptions): Timer

Creates a timer (chronograph) that starts immediately. The timer object may be placed directly into an interpolated string literal and will render its current value. Formatting is facilitated using pretty-ms, and this method's options are identical to those of pretty-ms.

Additionally, the timer object has a #reset() method that may be invoked to reset the timer to zero.

Example:

const timer = log.createTimer();

// Some time later...

log.info(`Done in ${timer}.`);

> screenshot(s) here.

createProgressBar(options: ProgressBarOptions): ProgressBar

Creates a progress bar. The progress bar object may be placed directly into an interpolated string literal and will render its current value. The only required option for this method is getProgress, a function that will be invoked every time the progress bar is rendered, and should return a number between 0 and 1 indicating how full the bar should be.

Example:

import axios from 'axios';

let completed = 0;

const progressBar = log.createProgressBar({
  // `getProgress` can simply return the value of `completed`.
  getProgress: () => completed
});

// Begin an interactive session that will continuously render our progress bar
// while the download is outstanding.
const endInteractive = log.beginInteractive(() => log.info(`Downloading file: ${progressBar}`));

// Download a file with Axios.
const download = await axios({
  url: 'https://my.domain.com/some-file.zip',
  onDownloadProgress: (progressEvent) => {
    // On each progress event, update our `completed` variable.
    completed = progressEvent.loaded / progressEvent.total;
  }
});

// Finally, end our interactive session.
endInteractive(() => log.info('Download complete.'));

createSpinner(options?: SpinnerOptions): Spinner

Creates a spinner. The spinner object may be placed directly into an interpolated string literal and will render its current value. The only option this method accepts is name, which should be a valid cli-spinners spinner name. If no options are provided, the dots spinner will be used.

Example:

const spinner = log.createSpinner();

const endInteractive = log.beginInteractive(() => log.info(`${spinner} Reticulating splines...`));

// Once all splines have been reticulated...

endInteractive(() => log.info(`Done.`));

Debug Support

...

Caveats

...