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

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

Defined in

logger.ts:267

Constants

defaultLevel

static defaultLevel: LogLevel = 'info'

The recommended default level.

Defined in

logger.ts:159

---

numericLevels

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

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

Defined in

logger.ts:168

---

numericLevelUndefined

static numericLevelUndefined: number = Infinity

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

Defined in

logger.ts:184

---

numericLevelAlways

static numericLevelAlways: number = -1

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

Defined in

logger.ts:191

Internal Members

levelNumericValue

protected levelNumericValue: number = Logger.numericLevelUndefined

The numerical value of the log level.

Defined in

logger.ts:209

---

levelName

protected levelName: undefined | LogLevel = undefined

The name of the log level.

Defined in

logger.ts:215

---

buffer

protected buffer: LoggerBufferRecord[] = []

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

Defined in

logger.ts:223

Log Level Accessors

hasLevel

Get Signature

get hasLevel(): boolean

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.

Defined in

logger.ts:321

---

level

Get Signature

get level(): undefined | LogLevel

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

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

Defined in

logger.ts:376

Log Level Check Accessors

isSilent

Get Signature

get isSilent(): boolean

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.

Defined in

logger.ts:390

---

isError

Get Signature

get isError(): boolean

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.

Defined in

logger.ts:404

---

isWarn

Get Signature

get isWarn(): boolean

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.

Defined in

logger.ts:418

---

isInfo

Get Signature

get isInfo(): boolean

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.

Defined in

logger.ts:432

---

isVerbose

Get Signature

get isVerbose(): boolean

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.

Defined in

logger.ts:446

---

isDebug

Get Signature

get isDebug(): boolean

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.

Defined in

logger.ts:460

---

isTrace

Get Signature

get isTrace(): boolean

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.

Defined in

logger.ts:474

---

isAll

Get Signature

get isAll(): boolean

Accessor to check the log level.

Remarks

• changed to an accessor in v3.0.0.

Returns

boolean

True if the log level is all.

Defined in

logger.ts:488

Log Level Check Methods

isLevel()

isLevel(level: LogLevel): boolean

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

Defined in

logger.ts:535

Other

console

Get Signature

get console(): Console

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.

Defined in

logger.ts:503

Output Methods

always()

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

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

Defined in

logger.ts:598

---

error()

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

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

Defined in

logger.ts:632

---

output()

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

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

Defined in

logger.ts:674

---

warn()

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

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

Defined in

logger.ts:697

---

info()

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

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

Defined in

logger.ts:720

---

verbose()

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

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

Defined in

logger.ts:742

---

debug()

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

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

Defined in

logger.ts:765

---

trace()

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

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

Defined in

logger.ts:789

---

write()

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

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

Defined in

logger.ts:557