Skip to main content

Debugging

API BackendTooling

Lightweight debugging. Wraps the amazing debug library to provide additional functionality.

Installation​

yarn add @boost/debug

Environment variables​

  • BOOSTJS_DEBUG_NAMESPACE (string) - A prefix for all debugger namespaces when created with createDebugger().
  • BOOSTJS_DEBUG_VERBOSE (boolean) - Print verbose messages logged from debugger.verbose(), otherwise they are hidden.

Debugging​

Like logging, a "debugger" is a collection of functions that write to process.stderr. The key difference is that debug messages are only displayed if the DEBUG environment variable is set and contains the debugger's namespace (logic provided by the debug package). The namespace can be defined when instantiating a debugger using createDebugger.

import { createDebugger } from '@boost/debug';

const debug = createDebugger('boost');

process.env.DEBUG = 'boost:*';

debug('Something is broken!');

A namespace can either be a string or an array of strings.

Each debug function that logs (excluding invariants) requires a message string as the 1st argument, and an optional rest of arguments to interpolate into the message using util.format().

debug('Name: %s %s', user.first_name, user.last_name);
debug('Object: %O', data);

Invariant messages​

Invariant debugging logs either a success or a failure message, depending on the truthy evaluation of a condition. This can be achieved with debugger.invariant(), which requires the condition to evaluate, a message to always display, and a success and failure message.

debug.invariant(fs.existsSync(filePath), 'Does file exist?', 'Yes!', 'No');

Verbose output​

Debug messages are already hidden behind the DEBUG environment variable, but Boost takes it a step further to support verbose debugging. Messages logged with debugger.verbose() will not be displayed unless the BOOSTJS_DEBUG_VERBOSE environment variable is set -- even if DEBUG is set.

// Will not write!
debug.verbose('We need extra information');

process.env.BOOSTJS_DEBUG_VERBOSE = 'true';

// Will write!
debug.verbose('We need extra information (again)');

Silencing output​

By default, all logged messages are immediately written when DEBUG contains the debugger namespace. To silence output for a specific debugger, call the debugger.disable() function, and to re-enable, call debugger.enable().

debug.disable();

// Will not write!
debug('Something is broken!');

Messages that are logged while silenced are lost and are not buffered.

Test utilities​

A handful of Vitest utilities are available in the @boost/debug/test module. View the API for a full list.