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 = ; var Logger = ; Logger // Add more meta data // And a few more meta data; // 2016-04-05T03:32:15.604 INFO Here comes the king {"name":"Aragorn","class":"Ranger","level":"99","kingdom":"Gondor"}
API
Logger(filters, writers, formatter)
class 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 theConsoleWriter
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 theDefaultFormatter
will be used.
Logger.log(meta)
returns Log
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
Log(meta, logger)
class Parameters
meta
:JSON
-MANDATORY
- A JSON with a any arbitrary meta.logger
:Logger
-MANDATORY
Log.with(key, value)
returns Log
Appends some meta data to the log.
Parameters
key
:STRING
-MANDATORY
- The name of your meta data.value
:ANY
-MANDATORY
- Your actual data.
Log.info(message)
returns Promise
Commits the message
and the meta
provided to the set of writers with log level INFO
.
Parameters
message
:STRING
- `OPTIONAL - Some arbitrary log message.
Log.warn(message)
returns Promise
Just like Log.info
but with log level WARN
.
Log.error(message)
returns Promise
Just like Log.info
but with log level ERROR
.
Log.debug(message)
returns Promise
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 = ;var PatternFilter = hewerfiltersPatternFilter; var nameErasingFilter = // '$1[REDACTED]'; var Logger = nameErasingFilter; Logger // Add more meta data // And a few more meta data;// 2016-04-08T15:02:54.022 INFO Here comes the king {"name":[REDACTED],"class":"Ranger","level":"99","kingdom":"Gondor"}
Built-in Filters
IdentityFilter
class The default filter used in case you don't pick any. Just returns the string as it is.
Usage
var IdentityFilter = filtersIdentityFilter; var filter = ; console;//You shall not pass!
PatternFilter(pattern, replacement)
class 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 stringreplacement
:STRING
-MANDATORY
- The string for which the pattern should be replaced
Usage
var PatternFilter = filtersPatternFilter; var filter = // '$1 (A.K.A Strider)'; console;//I am Aragorn (A.K.A Strider) son of Arathorn
KeyFilter(key, replacement)
class Replaces the value of a key in a serialized JSON
Parameters
key
:STRING
-MANDATORY
- The name of the key that must be replacedreplacement
:STRING
-MANDATORY
- The string for which the value of the key should be replaced
Usage
var KeyFilter = filtersKeyFilter; var filter = 'name' '[REDACTED]'; console;//Here comes the king {"name":"[REDACTED]","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
Filter()
interface Filter.apply(message)
returns STRING
Parameters
message
:STRING
-MANDATORY
- The log string that will be sent to a writer
Usage
var hewer = ; { this { //Do something with the string return str + " That's what Bilbo Baggins hates!"; }} var Logger = Logger;//2016-04-10T15:30:50.546 WARN Smash the bottles and burn the corks! {} That's what Bilbo Baggins hates!Logger;//2016-04-10T15:30:50.551 WARN Chip the glasses and crack the plates! {} That's what Bilbo Baggins hates!
Formatters
Built-in formatters
DefaultFormatter()
class Usage
var DefaultFormatter = formattersDefaultFormatter; var formatter = ; console;//2016-04-10T16:16:13.763 INFO There is only one Lord of the Ring, only one who can bend it to his will {}
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
Formatter
interface Formatter.format(message, level, meta)
returns STRING
Parameters
message
:STRING
-MANDATORY
- The log messagelevel
:STRING
-MANDATORY
- Some log level namemeta
:JSON
-MANDATORY
- Some meta data object
Usage
var hewer = ; var { this { return ` `; }} var Logger = null null Logger ;// "INFO Gandalf! {"titles":["The gray","The white"]}"
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
ConsoleWriter()
class Writes the log message to the console
Usage
var ConsoleWriter = writersConsoleWriter; var writer = ; { console;} writer;//The world has changed//Elfic whispering writer;//I feel it in the water//Elfic whispering writer;//I feel it in the earth//Elfic whispering writer;//I smell it in the air//Elfic whispering
Custom writers
API
Writer
interface Writer.info(message, callback)
Writes message with INFO log level
Parameters
message
:STRING
-MANDATORY
- The log messagecallback(error)
:FUNCTION
-MANDATORY
- A callback function to be called after the writer task has been executed
Writer.debug(message, callback)
Just like Writer.info but with DEBUG log level
Writer.warn(message, callback)
Just like Writer.info but with WARN log level
Writer.error(message, callback)
Just like Writer.info but with ERROR log level
Usage
var hewer = ; { this { //Do something with the message ; } this { //Do something with the message ; } this { //Do something with the message ; } this { //Do something with the message ; }} var Logger = null Logger ;
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
The MIT License (MIT)
Copyright (c) 2016 Mateus Chagas
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.