yanlogger v0.0.1-10

Yet-another Logger

A simple logging library for JavaScript

Please mind that the library is in an early stage. All feedback and contributions are welcome and will be reviewed.

Quick Start

1. Configure
2. Create Logger instance
3. ???
4. Log

The Gist

Having only found logging frameworks with frustrating APIs to use I decided to waste my time and create one to my liking.

The goal of yanlogger is to provide a logging framework that requires minimal configuration for basic usage. The following is a simple sample how to create a logger instance with yanlogger:

import LogManager from 'yanlogger';

LogManager.configure({
    format: '[{timestamp|+|DD.MM.YYYY HH:mm:ss}] {logName}: {message}',
    loggers: ['Console']
});

const logger = LogManager.getLogger('mylogger');
logger.info('Hello, world!');

Installation

To install the latest stable version:

npm install --save yanlogger

To install the latest

npm install --save yanlogger@unstable

To install typings

typings install

or if you don't want to install typings globally

./node_modules/.bin/typings install

Usage

Configuration

Configuration in yanlogger is a one time event. Configuration should be done via LogManager.configure(config:Configuration). For complete configuration values see the following sections.

If for some reason you need to reset or access the configuration they can be imported from the yanlogger/core/Configuration module.

See API Documentation for the interface definition.

{
  format:string, // Message format for formatting loggers
  loggers: [
    string|{name:string, args:{}|string} // Configuration for a logger to be instantiated for yanlogger
    ...
  ]
}

From an object

To configure yanlogger from a pure JavaScript object simply imitate the following example:

import LogManager from 'yanlogger';

LogManager.configure({
    format: '[{timestamp|+|DD.MM.YYYY HH\:mm\:ss}] {logName}: {message}',
    loggers: ['Console']
});

From a file

To configure yanlogger from a pure JavaScript object simply imitate the following example:

import LogManager from 'yanlogger';

LogManager.configure('path/to/config.json');

Custom loggers

You can register custom loggers to yanlogger before the configuration has been done as shown in the following example:

See API Documentation for the interface definition.

import LogManager from 'yanlogger';

LogManager.registerLogger(MyCustomLogger);

Creating a logger instance

Creating a logger instance requires yanlogger to be configured. Before the configuration phase has been completed the getLogger function of LogManager will throw an Error.

You can get a new or a previously created instance of a named Logger via the LogManager:

import LogManager from 'yanlogger';

LogManager.getLogger('mylogger');

Logger functions

interface LogWriter {
    trace(content:any):void; // Will pass content to all loggers with LogLevel.TRACE
    debug(content:any):void; // Will pass content to all loggers with LogLevel.DEBUG
    verbose(content:any):void; // Will pass content to all loggers with LogLevel.VERBOSE
    info(content:any):void; // Will pass content to all loggers with LogLevel.INFO
    warn(content:any):void; // Will pass content to all loggers with LogLevel.WARN
    error(content:any):void; // Will pass content to all loggers with LogLevel.ERROR
    critical(content:any):void; // Will pass content to all loggers with LogLevel.CRITICAL
    fatal(content:any):void; // Will pass content to all loggers with LogLevel.FATAL
    log(level:number, content:any):void; // Will pass content to all loggers with the given LogLevel
}

API

LogManager exposes the following functions and interfaces.

Interface: Configuration

The following interface represent the structure of a valid configuration object.

interface Configuration {
    format:string,
    loggers:{[loggerName:string]:any}
}

Usage in Typescript: import {Configuration} from 'yanlogger';

Enum: LogLevel

Yanlogger has the following default LogLevel enumeration:

LogLevel = {
    TRACE: 0,
    DEBUG: 1,
    VERBOSE: 2,
    INFO: 3,
    WARN: 4,
    ERROR: 5,
    CRITICAL: 6,
    FATAL: 7
};

Interface: Logger

To create a custom logger create a class that implements the following interface:

interface Logger {
    write(logName:string, level:number, content:any):void;
}

By default the write function will receive the message content as an object. The content is passed through LogWriter to the Logger which converts possible string only messages to the following format: {message: 'mymessage'}

Example:

class MyLoggerClass implements Logger {
    write(logName, level, content) {
        if (level > LogLevel.WARN) {
            console.error(logName, level, content);
        } else {
            console.log(logName, level, content);
        }
    }
}

Function: getLogger

This function will get or create an instance of LogWriter for the given logName.

Signature:

LogManager.getLogger(logName:string):LogWriter

Usage:

import LogManager from 'yanlogger';

LogManager.getLogger('mylogger');

Function: resetConfig

This function is mainly used for unit testing the configuration.

Signature:

function resetConfig():void

Usage:

import {resetConfig} from 'yanlogger';

resetConfig();

Function: registerLogger

This function is used to register Logger classes at runtime. The registration must happen before the configuration phase has ended; otherwise the logger will not be available for LogManager.getLogger functionality.

Signature:

function registerLogger(loggerName:string, logger, force:boolean = false):void

Usage:

import {registerLogger} from 'yanlogger';

registerLogger(MyLoggerClass);