Hewer

https://www.npmjs.com/package/hewer

A small, extensible, easy-to-use, zero-dependency logging library for node.js

Index

Motivation

This library was written to solve a need I had for a simple log standardization solution that would be very easy to extend and adapt without increasing the already possibly excessively big dependency tree of my projects. So, instead of making it some internal solution, I decided to make it a stand-alone open-source library so other people could possibly benefit from it.

Installation

npm install --save hewer

Basic Usage

var hewer = require ( ' hewer ' ) ; var Logger = new hewer . Logger ( ) ; Logger . log ( { ' name ' : ' Aragorn ' , ' class ' : ' Ranger ' } ) . with ( ' level ' , ' 99 ' ) . with ( ' kingdom ' , ' Gondor ' ) . info ( ' Here comes the king ' ) ;

API

class Logger(filters, writers, formatter)

Parameters

filters : Array of Filter - OPTIONAL - A list of filters that will be applied to the log message. writers : Array of Writer - OPTIONAL - A list of writers that will be used to write the log message to some output. If no writer is provided then the ConsoleWriter will be used. formatter : Formatter - OPTIONAL - A formatter that may transform and format the message before sending it to a writer. If no formatter is provided then the DefaultFormatter will be used.

Creates a new log instance with the optional provided meta data.

Parameters

meta : JSON - OPTIONAL - A JSON with a any arbitrary meta.

Logger.addFilter(filter) returns [ Logger ]

Adds a Filter to the filters pool

Parameters

filter : Filter - MANDATORY -

Logger.addWriter(writer) returns [ Logger ]

Adds a Writer to the writers pool

Parameters

writer : Writer - MANDATORY -

Logger.setFormatter(formatter) returns [ Logger ]

Defines the Formatter that's going to be used

Parameters

formatter : Formatter - MANDATORY

class Log(meta, logger)

Parameters

meta : JSON - MANDATORY - A JSON with a any arbitrary meta. logger : Logger - MANDATORY

Appends some meta data to the log.

Parameters

key : STRING - MANDATORY - The name of your meta data. value : ANY - MANDATORY - Your actual data.

Commits the message and the meta provided to the set of writers with log level INFO .

Parameters

message : STRING - `OPTIONAL - Some arbitrary log message.

Just like Log.info but with log level WARN .

Just like Log.info but with log level ERROR .

Just like Log.info but with log level DEBUG .

Filters

A filter receives a formatted log message and then applies some string-transformation rule over it.

Usage

var hewer = require ( ' hewer ' ) ; var PatternFilter = hewer . filters . PatternFilter ; var nameErasingFilter = new PatternFilter ( / ( \" name \" \: ) ( \" . * ? \" ) / , ' $1[REDACTED] ' ) ; var Logger = new hewer . Logger ( [ nameErasingFilter ] ) ; Logger . log ( { ' name ' : ' Aragorn ' , ' class ' : ' Ranger ' } ) . with ( ' level ' , ' 99 ' ) . with ( ' kingdom ' , ' Gondor ' ) . info ( ' Here comes the king ' ) ;

Built-in Filters

class IdentityFilter

The default filter used in case you don't pick any. Just returns the string as it is.

Usage

var IdentityFilter = require ( ' hewer ' ) . filters . IdentityFilter ; var filter = new IdentityFilter ( ) ; console . log ( filter . apply ( ' You shall not pass! ' ) ) ;

class PatternFilter(pattern, replacement)

A filter that applies a pattern or substring and replaces it by a pattern or substring

Parameters

pattern : STRING or REGEXP - MANDATORY - The pattern for matching some string replacement : STRING - MANDATORY - The string for which the pattern should be replaced

Usage

var PatternFilter = require ( ' hewer ' ) . filters . PatternFilter ; var filter = new PatternFilter ( / ( Aragorn ) / , ' $1 (A.K.A Strider) ' ) ; console . log ( filter . apply ( " I am Aragorn son of Arathorn " ) ) ;

class KeyFilter(key, replacement)

Replaces the value of a key in a serialized JSON

Parameters

key : STRING - MANDATORY - The name of the key that must be replaced replacement : STRING - MANDATORY - The string for which the value of the key should be replaced

Usage

var KeyFilter = require ( ' hewer ' ) . filters . KeyFilter ; var filter = new KeyFilter ( ' name ' , ' [REDACTED] ' ) ; console . log ( filter . apply ( ' Here comes the king {"name":"Aragorn","class":"Ranger","level":"99","kingdom":"Gondor"} ' ) ) ;

Custom filter

A filter is simply a class that has an apply method that takes a string as parameter and returns a string

API

interface Filter()

Filter.apply(message) returns STRING

Parameters

message : STRING - MANDATORY - The log string that will be sent to a writer

Usage

var hewer = require ( ' hewer ' ) ; function CustomFilter ( ) { this . apply = function ( str ) { return str + " That's what Bilbo Baggins hates! " ; } } var Logger = new hewer . Logger ( [ new CustomFilter ( ) ] ) Logger . log ( ) . warn ( ' Smash the bottles and burn the corks! ' ) ; Logger . log ( ) . warn ( ' Chip the glasses and crack the plates! ' ) ;

Formatters

Built-in formatters

class DefaultFormatter()

Usage

var DefaultFormatter = require ( ' hewer ' ) . formatters . DefaultFormatter ; var formatter = new DefaultFormatter ( ) ; console . log ( formatter . format ( " There is only one Lord of the Ring, only one who can bend it to his will " , " INFO " , { } ) ) ;

Custom formatter

A formatter is simply a class that has a format method that receives some message , some log level name , and some meta data and returns a formatted string.

API

interface Formatter

Formatter.format(message, level, meta) returns STRING

Parameters

message : STRING - MANDATORY - The log message level : STRING - MANDATORY - Some log level name meta : JSON - MANDATORY - Some meta data object

Usage

var hewer = require ( ' hewer ' ) ; var function CustomFormatter ( ) { this . format = function ( message , level , meta ) { return ` ${ level } ${ message } ${ JSON . stringify ( meta ) } ` ; } } var Logger = new hewer . Logger ( null , null , new CustomFormatter ( ) ) Logger . log ( { titles : [ ' The gray ' , ' The white ' ] } ) . info ( ' Gandalf! ' ) ;

Writers

A writer is the final destiny of any log message. A writer is where the message is going to be printed to the console, be sent to a database etc.

Built-in Writers

class ConsoleWriter()

Writes the log message to the console

Usage

var ConsoleWriter = require ( ' hewer ' ) . writers . ConsoleWriter ; var writer = new ConsoleWriter ( ) ; function saySomeElficWhisper ( ) { console . log ( ' Elfic whispering! ' ) ; } writer . info ( ' The world has changed ' , saySomeElficWhisper ) ; writer . debug ( ' I feel it in the water ' , saySomeElficWhisper ) ; writer . warn ( ' I feel it in the earth ' , saySomeElficWhisper ) ; writer . error ( ' I smell it in the air ' , saySomeElficWhisper ) ;

Custom writers

API

interface Writer

Writes message with INFO log level

Parameters

message : STRING - MANDATORY - The log message callback(error) : FUNCTION - MANDATORY - A callback function to be called after the writer task has been executed

Just like Writer.info but with DEBUG log level

Just like Writer.info but with WARN log level

Just like Writer.info but with ERROR log level

Usage

var hewer = require ( ' hewer ' ) ; function CustomWriter ( ) { this . info = function ( message , callback ) { callback ( ) ; } this . debug = function ( message , callback ) { callback ( ) ; } this . error = function ( message , callback ) { callback ( ) ; } this . warn = function ( message , callback ) { callback ( ) ; } } var Logger = new hewer . Logger ( null , [ new CustomWriter ( ) ] ) Logger . log ( { titles : [ ' The gray ' , ' The white ' ] } ) . info ( ' Gandalf! ' ) ;

Contributing

If you want to contribute to the project with new Filters, Formatters, Writers, fixes, functionalities, optimizations, documentation, issues etc. All you have to do is open an issue and, if needed, fork this project and open a pull request.

Testing

npm test

License