@alt-javascript/logger

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
-------------------------

$3

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

``javascript
import config from 'config';
import { LoggerFactory } from '@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
`json
{
"logging" : {
"format" : 'json',
"level" : {
"/" : "info",
"@myorg/mypackage/MyModule" : "debug"
}
}
}
`

$3

The Logger syntax 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
`javascript
import config from '@alt-javascript/config';
import { LoggerFactory } from '@alt-javascript/logger';
import { boot } from '@alt-javascript/boot';
boot({config:config});

`

Then in your application modules, you only need.

MyModule.js
`javascript
import { LoggerFactory } from '@alt-javascript/logger';

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


$3

The module is also able to be used directly in the browser, in combination with the config module.
You can either import the LoggerFactory globally as an IIFE (Immediately Invoked Function Expression),
as follows:

`html



`

Or import the ES6 module bundle from a module, as follows:

`javascript
import { LoggerFactory } from 'https://cdn.jsdelivr.net/npm/@alt-javascript/logger/dist/alt-javascript-logger-esm.js'
import { ConfigFactory } from 'https://cdn.jsdelivr.net/npm/@alt-javascript/logger/dist/alt-javascript-config-esm.js'

//...as above
`

$3

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

`javascript
{
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.

`javascript
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).

`javascript
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'

`json
{
"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.

`javascript
import config from 'config';
import { CachingLoggerFactory } from '@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.

Copyright (c) 2021-2022 Craig Parravicini