Class: Logger

The Logger class implements the logger functionality.

The logger is constructed on top of a console object, where the messages are logged.

Use log.always() instead of the console.log(), since it accounts for different contexts, created for example when using REPL.

There is no critical level, corresponding to errors that prevent the program to run, since these are actually related to bugs; use assert() instead.

The messages may include formatting directives, with additional arguments, as defined by the Node.js console (not really necessary with ES6).

All output functions accept an optional string message and possibly some arguments, as processed by the standard Node.js util.format(msg, ...args) function.

If the logging code is more complex than a single line, for example if it needs a long loop, it is recommended to explicitly check the log level and, if not high enough, skip the code entirely.

  if (log.isVerbose) {
    for (const [folderName, folder] of Object.entries(folders)) {
      log.trace(`'${folderName}' ${folder.toolchainOptions}`)
    }
  }

There are cases when the logger must be created very early in the life cycle of an application, even before it is practically possible to determine the log level.

For these cases, if the logger is created without a log level, it is set to a preliminary state, and all log lines are stored in an internal buffer, until the log level is set, when the buffer is walked and the lines are processed.

Constructors

new Logger()

new Logger(params: { level: LogLevel; console: Console; }): Logger

Defined in: logger.ts:267

Create a Logger instance.

The typical use case is to create a logger with a given log level, usually info.

const log = new Logger({
  level: 'info'
})

By default, the system console is used.

The complete use case is to create the logger instance with both a console and a level. This might be particularly useful in tests, where a mock console can be used to capture log messages.

const log = new Logger({
  console: mockConsole,
  level: 'info'
})

If present, the console must be an object derived from the node Console, possibly with some methods overridden.

The level property is optional since it can be set later. Without it, the constructor will create the logger in a preliminary state, and all log lines will be stored in an internal buffer until the log level is set.

const log = new Logger()

Parameters

Parameter	Type	Description
`params`	{ `level`: `LogLevel`; `console`: `Console`; }	The generic object used to pass parameters to the constructor.
`params.level`?	`LogLevel`	The name of the log level; if not passed, the logger is created in a preliminary state, and all log lines will be stored in an internal buffer, until the log level is set. Optional.
`params.console`?	`Console`	The underlying console object used to log the message. Optional. If not passed, the JavaScript standard `console` object is used.

Returns

Logger

Constants

defaultLevel

static defaultLevel: LogLevel = 'info'

Defined in: logger.ts:159

The recommended default level.

numericLevels

static numericLevels: { silent: number; error: number; warn: number; info: number; verbose: number; debug: number; trace: number; all: number; }

Defined in: logger.ts:168

Internal numerical values for the log level.

Name	Type	Default value	Defined in
`silent`	`number`	0	logger.ts:169
`error`	`number`	10	logger.ts:170
`warn`	`number`	20	logger.ts:171
`info`	`number`	30	logger.ts:172
`verbose`	`number`	40	logger.ts:173
`debug`	`number`	50	logger.ts:174
`trace`	`number`	60	logger.ts:175
`all`	`number`	70	logger.ts:176

numericLevelUndefined

static numericLevelUndefined: number = Infinity

Defined in: logger.ts:184

The value used for the undefined log level (maximum value).

numericLevelAlways

static numericLevelAlways: number = -1

Defined in: logger.ts:191

The value used for the always case (minimum value).

Internal Members

levelNumericValue

protected levelNumericValue: number = Logger.numericLevelUndefined

Defined in: logger.ts:209

The numerical value of the log level.

levelName

protected levelName: undefined | LogLevel = undefined

Defined in: logger.ts:215

The name of the log level.

buffer

protected buffer: LoggerBufferRecord[] = []

Defined in: logger.ts:223

Empty buffer where preliminary log lines are stored until the log level is set.

Log Level Accessors

hasLevel

Get Signature

get hasLevel(): boolean

Defined in: logger.ts:321

Accessor to check if the log level was initialised.

If the logger was created without an explicit log level, the logger is in a preliminary state and all log lines will be stored in an internal buffer until the log level is set.

Example

if (!log.hasLevel) {
  log.level = defaultLevel
}

Remarks

changed to an accessor in v5.0.0
added as a method in v2.1.0

Returns

boolean

True if the level was set.

level

Get Signature

get level(): undefined | LogLevel

Defined in: logger.ts:376

Accessor to get the log level.

Example

console.log(log.level)

Returns

undefined | LogLevel

A string with the log level name.

Set Signature

set level(level: undefined | LogLevel): void

Defined in: logger.ts:342

Accessor to set the log level.

If the log level is not one of the known strings, an assert will fire.

If this is the first time when the log level is set, flush the internal buffer.

Example

log.level = 'info'

Parameters

Parameter	Type	Description
`level`	`undefined` \| `LogLevel`	A string with the new log level.

Returns

void

Log Level Check Accessors

isSilent

Get Signature

get isSilent(): boolean

Defined in: logger.ts:390

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is silent or higher.

isError

Get Signature

get isError(): boolean

Defined in: logger.ts:404

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is error or higher.

isWarn

Get Signature

get isWarn(): boolean

Defined in: logger.ts:418

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is warn or higher.

isInfo

Get Signature

get isInfo(): boolean

Defined in: logger.ts:432

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is info or higher.

isVerbose

Get Signature

get isVerbose(): boolean

Defined in: logger.ts:446

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is verbose or higher.

isDebug

Get Signature

get isDebug(): boolean

Defined in: logger.ts:460

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is debug or higher.

isTrace

Get Signature

get isTrace(): boolean

Defined in: logger.ts:474

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is trace or higher.

isAll

Get Signature

get isAll(): boolean

Defined in: logger.ts:488

Accessor to check the log level.

Remarks

changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is all.

Log Level Check Methods

isLevel()

isLevel(level: LogLevel): boolean

Defined in: logger.ts:535

Check if the log level is set to a given level name.

This is a more generic version of the accessors (like isDebug, etc), to be used when the log level is not know at compile time.

It can also be used to ensure that the log level is not decreased, for example:

Example

if (!log.islevel(newLevel)) {
  log.level = newLevel
}

Parameters

Parameter	Type	Description
`level`	`LogLevel`	The name of the log level.

Returns

boolean

True if the current log level is equal to the given level or higher.

Remarks

added in v6.0.0

Other

console

Get Signature

get console(): Console

Defined in: logger.ts:503

Accessor to get the underlying console object.

Direct access to the console object is useful in tests, when the console is a mock object, which allows to check the logged messages.

Returns

Console

The console object used by the logger.

Output Methods

always()

always(message: any, ...args: any[]): void

Defined in: logger.ts:598

Always log a message, regardless of the log level, (even 'silent', when no other messages are logged).

The message is passed via console.log().

Example

log.always(version)

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

error()

error(message: any, ...args: any[]): void

Defined in: logger.ts:632

Log an error message, if the log level is error or higher.

The message is prefixed with error: and passed via console.error().

There is a special case when the input is an Error object. It is expanded, including a full stack trace, and passed via console.error().

try {
  // ...
} catch (err) {
  log.error(err)
}

Example

log.error('Not good...')

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

output()

output(message: any, ...args: any[]): void

Defined in: logger.ts:674

Log an error message, if the log level is error or higher.

It differs from error() by not prefixing the string with error: and using console.log() instead of console.error().

There is a special case when the input is an Error object. It is expanded, including a full stack trace, and passed via console.log().

try {
  // ...
} catch (err) {
  // Do not show the stack trace.
  log.output(err)
}

Example

log.output('Not good either...')

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

warn()

warn(message: any, ...args: any[]): void

Defined in: logger.ts:697

Log a warning message, if the log level is warn or higher.

The message is prefixed with warning: and passed via console.error().

Example

log.info(title)

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

info()

info(message: any, ...args: any[]): void

Defined in: logger.ts:720

Log an informative message, if the log level is info or higher.

The message is passed via console.log().

Example

log.info(title)

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

verbose()

verbose(message: any, ...args: any[]): void

Defined in: logger.ts:742

Log a verbose message, if the log level is verbose or higher.

The message is passed via console.log().

Example

log.verbose('Configurations:')

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

debug()

debug(message: any, ...args: any[]): void

Defined in: logger.ts:765

Log a debug message, if the log level is 'debug' or higher.

The message is prefixed with debug: and passed via console.log().

Example

log.debug(`spawn: ${cmd}`)

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

trace()

trace(message: any, ...args: any[]): void

Defined in: logger.ts:789

Log a trace message, if the log level is trace or higher.

The message is prefixed with trace: and passed via console.log().

Example

log.trace(`${this.constructor.name}.doRun()`)

Parameters

Parameter	Type	Default value	Description
`message`	`any`	`''`	Message to log, as accepted by `util.format()`.
...`args`	`any`[]	`undefined`	Optional variable arguments.

Returns

void

write()

protected write(numericLevel: number, loggerFunction: LoggerFunction, message: undefined | string): void

Defined in: logger.ts:557

The internal log writer.

If the log level was defined, call the actual logger function, otherwise store the log lines in the array buffer, for later processing, when the log level is finally defined.

Parameters

Parameter	Type	Description
`numericLevel`	`number`	The log numeric level.
`loggerFunction`	`LoggerFunction`	The function to be used to write the message.
`message`	`undefined` \| `string`	The log message.

Returns

void

Constructors​

new Logger()​

Parameters​

Returns​

Constants​

defaultLevel​

numericLevels​

numericLevelUndefined​

numericLevelAlways​

Internal Members​

levelNumericValue​

levelName​

buffer​

Log Level Accessors​

hasLevel​

Get Signature​

Example​

Remarks​

Returns​

level​

Get Signature​

Example​

Returns​

Set Signature​

Example​

Parameters​

Returns​

Log Level Check Accessors​

isSilent​

Get Signature​

Remarks​

Returns​

isError​

Get Signature​

Remarks​

Returns​

isWarn​

Get Signature​

Remarks​

Returns​

isInfo​

Get Signature​

Remarks​

Returns​

isVerbose​

Get Signature​

Remarks​

Returns​

isDebug​

Get Signature​

Remarks​

Returns​

isTrace​

Get Signature​

Remarks​

Returns​

isAll​

Get Signature​

Remarks​

Returns​

Log Level Check Methods​

isLevel()​

Example​

Parameters​

Returns​

Remarks​

Other​

console​

Get Signature​

Returns​

Output Methods​

always()​

Example​

Parameters​

Returns​

error()​

Example​

Parameters​

Returns​

output()​

Constructors

new Logger()

Parameters

Returns

Constants

defaultLevel

numericLevels

numericLevelUndefined

numericLevelAlways

Internal Members

levelNumericValue

levelName

buffer

Log Level Accessors

hasLevel

Get Signature

Example

Remarks

Returns

level

Get Signature

Example

Returns

Set Signature

Example

Parameters

Returns

Log Level Check Accessors

isSilent

Get Signature

Remarks

Returns

isError

Get Signature

Remarks

Returns

isWarn

Get Signature

Remarks

Returns

isInfo

Get Signature

Remarks

Returns

isVerbose

Get Signature

Remarks

Returns

isDebug

Get Signature

Remarks

Returns

isTrace

Get Signature

Remarks

Returns

isAll

Get Signature

Remarks

Returns

Log Level Check Methods

isLevel()

Example

Parameters

Returns

Remarks

Other

console

Get Signature

Returns

Output Methods

always()

Example

Parameters

Returns

error()

Example

Parameters

Returns

output()