README

A Simple Log Facade for JavaScript

Language Badge Package Badge
release notes

Introduction

A simple configurable logging facade for javascript, using the popular config package interface.

Usage

Standalone

To use the module, import the LoggerFactory and call the getLogger function with a logging category (your module requires path is a sensible choice).

const config = require('config');
const {LoggerFactory} = require('@alt-javascript/logger');
const logger = LoggerFactory.getLogger('@myorg/mypackage/MyModule',config);

logger.info('Hello world!');

The LoggerFactory will create a ConsoleLogger (uses console.log('...')) object instance, with the root logging level set to info by default. To change the logging level for your module (category), add something similar to the following in your config files.

local-development.json

{
  "logging" : {
     "format" : 'json',
     "level" : {
       "/" : "info",
       "@myorg/mypackage/MyModule" : "debug"
     }
  }
}

@alt-javascript/boot

The LoggerSyntax is more fluent if you combine
@alt-javascript/boot and @alt-javascript/config to bind the LoggerFactory to the global root context, freeing your sub-modules from requiring and injecting the config.

MyModule.js

const {config} = require('@alt-javascript/config');
const {LoggerFactory} = require('@alt-javascript/logger');
const {boot} = require('@alt-javascript/boot');
boot({config:config});

Then in your application modules, you only need.

MyModule.js

const {LoggerFactory} = require('@alt-javascript/logger');

const logger = LoggerFactory.getLogger('@myorg/mypackage/MyModule');
logger.info('Hello from MyModule!')

Log Levels

The logger supports the following levels by default, but is fully configurable.

{
  ENUMS: {
    fatal: 0, error: 1, warn: 2, info: 3, verbose: 4, debug: 5,
  },
  DEBUG: 'debug',
  VERBOSE: 'verbose',
  INFO: 'info',
  WARN: 'warn',
  ERROR: 'error',
  FATAL: 'fatal',
}

You can test if a level is enabled for your module (category), for example.

if (logger.isDebugEnabled()){
    logger.debug(`This a performance impacting logline => ${costlyFunction()}`)
}

Configuring

While the module uses sensible defaults, it is flexible and pluggable. To use the popular winston package you can use a WinstonLoggerFactory, passing it your winston and winston options (nullish options will fall back to defaults).

const config = require('config');
const {winston} = require('winston');
const {WinstonLoggerFactory} = require('@alt-javascript/logger');
const logger = WinstonLoggerFactory.getLogger('@myorg/mypackage/MyModule', config, winston,  {/*mywinstonoptions*/}));

logger.info('Hello world!');

The ConsoleLogger uses a JSONFormatter, but a PlainTextFormatter (or similar implementation) can easily be substituted in the config by setting the 'logging.format' config value to 'text'

{
  "logging" : {
     "format" : 'text',
     "level" : {
       "/" : "info",
       "@myorg/mypackage/MyModule" : "debug"
     }
  }
}

Testability

Testing loggers is hard, and testability is a first class concern at @alt-javascript so the module exports a 'CachingLoggerFactory' that will provide a logger implementation that will capture log lines that can be asserted.

const config = require('config');
const {CachingLoggerFactory} = require('@alt-javascript/logger');
const logger = CachingLoggerFactory.getLogger('@myorg/mypackage/MyModule', config);

logger.info('Hello world!');

//...

assert.isTrue(logger.provider.console.cache[0].contains('Hello world!'))

License

May be freely distributed under the MIT license.

Usage no npm install needed!