@rhobweb/console-logger

Overview

Module to provide console logging with log levels, printf style formatting and coloured log levels.

Usage

Environment Variables

Variable	Description	Default
NODE_LOG_LEVEL	Only output log items at this level and above, below. See NODE_LOG_LEVEL	'info'
LOG_COLOURS	Either 'true' to use the default colours or a comma separated list of log level colours, see LOG_COLOURS.	false
LOG_FORMAT_OPTIONS	Comma separated list of util.formatWithOptions options to use by default.	See LOG_FORMAT_OPTIONS.
NODE_ENV	The development stage, one of: 'production', 'test', 'development'.
	This only affects the default values used for the LOG_FORMAT_OPTIONS.

NODE_LOG_LEVEL

The level of verbosity is defined using the following log levels in increasing verbosity order.

• off
• error
• warn
• http
• info
• verbose
• debug
• silly

If NODE_LOG_LEVEL is not specified, the default vaile depends on the stage

NODE_ENV	Default
production	info
All others	verbose

LOG_COLOURS

A comma separated list of log level colours, which outputs the log level in the specified colour. If set to 'true' use the default colours.
See the colors module for the supported colours.
The default colours are:

error=red,warn=magenta,http=green,info=blue,verbose=grey,debug=white,silly=cyan

LOG_FORMAT_OPTIONS

A comma separated list of format options to be passed to util.formatWithOptions, The default options are:

maxMessageLength=null,maxArrayLength=null,depth=null,breakLength=320

The format options are extended with custom options that are applicable to this module only.

Option	Description
maxMessageLength	Custom option that limits the maximum number of characters of the output message. If null, messages are not truncated.
	This is applied to the final message after all other format options have been applied to it.
paramSeparator	Custom option to specify the string that separates top level parameters. Defaults to the empty string.
	e.g., params [ 'p1', 'p2' ] would by default be output as: 'p1p2'
stringified	Custom option to output Objects as stringified JSON, i.e., double quoted property names. This is useful for copying and pasting the output into a JSON file.
	NOTE: that the output object shall be incomplete if the object contains any types that cannot be stringified, e.g., RegExp.
maxArrayLength	The number of array elements to print, truncated arrays are output with the number of elements missing, e.g., '1, 2, ... 1 more item'. If null, no truncation.
depth	The depth to traverse objects, e.g., '{ p1: 'v1', p2: { p2_1: 'v21', p2_2: [Object] } }'. If null, no truncation.
breakLength	Determines the maximum number of characters to fit on one line when outputting objects. Defaults to 80. (Note: affected by the 'compact' option)

Type Formatting

The util.inspect method formats types as per the following table. It should be noted that the documentation for util.inspect states:

The output of util.inspect may change at any time and should not be depended upon programmatically.

Type	Output
string	As a top level item output without quotes, otherwise in single quotes.
	e.g., ( 'str1', { p1: 'str2' } ) => str1, { p2_1: 'v21' }
number	e.g., ( 123e-5 ) => 0.00123
Object	e.g., ( { p1: { p1_1: 'v11' } } ) => { p1: { p1_1: 'v11' } }
Array	e.g., [ 1, 2, 3 ] => [ 1, 2, 3 ]
RegExp	e.g., RegExp( /^fred/ ) => /^fred/
boolean	e.g., true => true
function	e.g., function f() {} => [Function: f]
Symbol	e.g., Symbol(bert) => Symbol(bert)
Buffer	A sequence of decimal values
	e.g., Buffer.from('4143', 'hex') => 65 67

Methods

Method Parameters

Parameter	Description
options	The 'options' parameter contains a single property 'formatOptions' which contains a format options object with properties that enhance or override the default values defined in LOG_FORMAT_OPTIONS.
	The 'formatOptions' object may also contain a 'fmt' property that is used to override the default formatting, see util.format.
	Alternatively the 'options' parameter may contain a single 'fmt' property.
level	The log level for the message. If the specified level is below the configured log level no message shall be output.
parameterX	A parameter of any type.

log Method

Output a formatted message to the console, according to the current log level.

logger.log( [<level>,] [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

Log Level Methods

This are convenience methods that call log method with the specified log level.

• logger.error( [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

• logger.warn( [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

• logger.http( [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

• logger.info( [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

• logger.verbose( [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

• logger.debug( [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

• logger.silly( [<options>,] [<parameter1> [<parameter2&gt,...]] ) ;

Long Messages

This module uses the default console to write to stdout.
The default console uses util.inspect to format the message defaults the maximum message length to 10000 ( see util.inspect ).
Messages longer than this maxium length are output using multiple calls to the default console, separated by messages indicating the part number, e.g.,

2022-10-14T09:40:38.889Z : info    : This is the start of a long message...
...end of part 1
MESSAGE PART: 002/003
Start of part 2...
...end of part 2
MESSAGE PART: 003/003
Start of part 3...
...end of part 3

Example Usage

Using Default Values

The default log level is 'info'.

const logger = require( '@rhobweb/console-logger' ) ;
logger.log( 'Message with no level' ) ;
logger.info( 'Message at level: info' ) ;
logger.log( 'verbose', 'Message at level: verbose' ) ;

Should produce something like the following output:

2022-12-25T01:02:03.123Z: info    : Message with no level
2022-12-25T01:02:03.124Z: info    : Message with at level: info

Using Configured Values

process.env.LOG_COLOURS    = true ;
process.env.NODE_LOG_LEVEL = 'silly' ;
const logger = require( '@rhobweb/console-logger' ) ;
logger.error( 'Level error' ) ;
logger.warn( 'Level warn' ) ;
logger.log( 'http', 'Level http' ) ;
logger.log( 'info', 'Level ', 'info' ) ;
logger.log( 'verbose', { level: 'verbose' } ) ;
logger.log( 'debug', 'Level debug' ) ;
logger.log( 'silly', [ 'Level', { silly: 1 } ] ) ;

Should produce something like the following output:

2022-12-25T01:02:03.123Z: error   : Level error
2022-12-25T01:02:03.134Z: warn    : Level warn
2022-12-25T01:02:03.245Z: http    : Level http
2022-12-25T01:02:03.356Z: info    : Level info
2022-12-25T01:02:03.789Z: verbose : { Level: 'verbose' }
2022-12-25T01:02:03.801Z: debug   : Level debug
2022-12-25T01:02:03.999Z: silly   : [ 'Level', { silly: 1 } ]

Using with Webpack

This module can be used client-side, but requires the following additional configuration for webpack 5.
Install the following modules:

  npm install process stream-browserify os-browserify

In the webpack.config file for the browser add the following:

const { ProvidePlugin } = require("webpack");
. . .
module.exports = {
  . . .
  plugins: [
    . . .
    new ProvidePlugin( { process: 'process/browser' } )
  ],
  . . .
  resolve: {
    . . .
    fallback: { "stream": require.resolve("stream-browserify"), "os": require.resolve("os-browserify") }
  },
  . . .
};

Testing

Pre-Requisites

• mocha is to be found in the PATH, typically /usr/bin/mocha.

Unit Tests

From the module directory ( '@rhobweb/console-logger' ), run:

npm install

npm run test-unit

npm run test-coverage

npm run test-system