@n7e/log v0.1.1

Log

A lightweight and extendable logging library.

For further insights, read on.

• Installation
• Logger
  • Logger Implementations
  • Log Levels
  • Logging Messages
  • Message Context
  • Log Formatters
• Logger Builder
  • Aggregate Logger Builder

Installation

To install this library use your favorite package manager. No additional steps are required to start using the library.

npm install @n7e/log

This library is implemented in TypeScript but can be used with JavaScript without any additional steps.

Logger

Loggers has the ability to send messages of varying severity to a wide range of targets.

All loggers implement the Logger interface. To reference it simply import it and use it as a type.

import type { Logger } from "@n7e/log";

function someFunction(logger: Logger): void {
    // ...
}

Logger is just an interface describing the functionality of a logger. To create a logger instance you need to reference a specific implementation.

Logger Implementations

This library provides the following loggers:

Log Levels

Log messages are assigned a severity level to enable filtering and specific actions to be taken on certain severity levels.

A defined set of log levels are available through an enum and can be accessed like so:

import { LogLevel } from "@n7e/log";

logger.log(LogLevel.INFO, "This is an informational message");

The available log levels are:

Logging Messages

To produce log messages the Logger interface provides a dedicated method for each log level as well as a log() method to log messages with a provided log level. Although it's ultimately up to the implementation either method should produce the same result. The following lines should essentially be equal in functionality.

import { LogLevel } from "@n7e/log";

logger.info("This is an informative message");
logger.log(LogLevel.INFO, "This is an informative message");

Since implementations can send log messages to any number of remote resources all methods of the Logger interface returns a promise. If it's important to ensure the message has been received by the target the promise should be awaited.

await logger.info("This is an informative message");

Message Context

Every logged message can have an optional associated context object. The significance of the context is up to the logger implementation and/or log formatters used by the logger.

logger.info("This is an informative message", {key: "value"});

The log message may or may not be affected by the passed context object.

Log Formatters

Some logger implementations accept a log formatter to format the message being logged. All log formatters implement the LogFormat interface and can be imported from the @n7e/log/format module.

import type { LogFormatter } from "@n7e/log/format";

function someFunction(formatter: LogFormatter): void {
    // ...
}

LogFormatter is just an interface describing the functionality of a log formatter. To create a log formatter instance you need to reference a specific implementation.

This library provides the following log formatters:

Logger Builder

Logger builders has the ability to create logger instances.

All logger builders implement the LoggerBuilder interface. To reference it simply import it and use it as a type.

import type { LoggerBuilder } from "@n7e/log";

function someFunction(loggerBuilder: LoggerBuilder): void {
    // ...
}

LoggerBuilder is just an interface describing the functionality of a logger builder. To create a logger builder instance you need to reference a specific implementation.

Aggregate Logger Builder

To create an aggregate logger instance import and use the provided AggregateLoggerBuilder logger builder.

import { AggregateLoggerBuilder } from "@n7e/log";

const loggerBuilder = new AggregateLoggerBuilder();

To configure the build aggregate logger instance any number of loggers can be provided to the builder.

loggerBuilder.addLogger(new ConsoleLogger());

If a logger should log records for and above a certain log level the desired log level can be provided.

loggerBuilder.addLogger(new ConsoleLogger(), LogLevel.WARNING);

The console logger will now only log messages with log level: warning, error, critical, alert or emergency.

If you need to customize the delegation behaviour you can configure the logger to use a custom predicate to determine whether to delegate to a logger. The provided predicate must conform to the AggregateLoggerDelegationPredicate interface.

loggerBuilder.useDelegationPredicate(() => true);

To produce an aggregate logger instance simply call the build() method when all desired loggers have been configured.

const logger = loggerBuilder.build();