log-events
v0.4.0
Published
Create custom, chainable logging methods that emit log events when called.
Downloads
415
Readme
log-events
Create custom, chainable logging methods that emit log events when called.
Install
Install with npm:
$ npm install --save log-events
Usage
Logger
Create a new Logger
constructor to allow
updating the prototype without affecting other contructors.
._emit
Factory for emitting log messages. This method is called internally for any emitter or mode method that is called as a function. To listen for events, listen for the emitter name or 'log'
when a mode is called as a method.
Wildcard *
may also be listened for and will get 2 arguments (name, stats)
where
name
is the emitter that was emitted and stats
is the stats object for that event.
Params
name
{String}: the name of the emitter event to emit. Example:info
message
{String}: Message intended to be emitted.returns
{Object}Logger
: for chaining
Events
emits
:*
Wildcard emitter that emits the emitter event name and stats object.emits
:stats
Emitter that emits the stats object for the specified name.
Example
// emit `info` when `info` is an emitter method
logger.info('message');
// emit `log` when `verbose` is a mode method
logger.verbose('message');
// listen for all events
logger.on('*', function(name, stats) {
console.log(name);
//=> info
});
logger.info('message');
.emitter
Add an emitter method to emit an event with the given name
.
Params
name
{String}: the name of the emitter event to emit.level
{Number}: Priority level of the emitter. Higher numbers are less severe. (Default: 100)fn
{Function}: Optional emitter function that can be used to modify an emitted message. Function may be an existing style function.returns
{Object}this
: for chaining
Events
emits
:emitter
Emits name and new emitter instance after adding the emitter method.
Example
// add a default `write` emitter
logger.emitter('write');
// add some styles
logger.style('red', function(msg) {
return colors.red(msg);
});
logger.style('cyan', function(msg) {
return colors.cyan(msg);
});
// add an `info` logger that colors the msg cyan
logger.emitter('info', logger.cyan);
// use the loggers:
logger.red.write('this is a red message');
logger.info('this is a cyan message');
.mode
Add arbitrary modes to be used for creating namespaces for emitter methods.
Params
mode
{String}: Mode to add to the logger.options
{Object}: Options to describe the mode.options.type
{String|Array}: Type of mode being created. Defaults tomode
. Valid values are['mode', 'toggle']
.toggle
mode may be used to indicate a "flipped" state for another mode. e.g.not.verbose
.toggle
modes may not be used directly for emitting log events.fn
{Function}: Optional style function that can be used to stylize an emitted message.returns
{Object}this
: for chaining
Events
emits
:mode
Emits the name and new mode instance after adding the mode method.
Example
// create a simple `verbose` mode
logger.mode('verbose');
// create a `not` toggle mode
logger.mode('not', {type: 'toggle'});
// create a `debug` mode that modifies the message
logger.mode('debug', function(msg) {
return '[DEBUG]: ' + msg;
});
// use the modes with styles and emitters from above:
logger.verbose.red.write('write a red message when verbose is true');
logger.not.verbose.info('write a cyan message when verbose is false');
logger.debug('write a message when debug is true');
.style
Create a logger style
with the given fn
.
Params
style
{String}: The name of the style to create.fn
{Function}returns
{Object}: Returns the instance for chaining.
Events
emits
:style
Mode
Mode constructor for making a mode object when
a mode is created with logger.mode()
Params
options
{Object}: Options to configure the mode.options.name
{String}: Required name of the modeoptions.type
{String|Type}: Type of mode to create. Defaults tomode
. Values may be['mode', 'toggle']
.
type
Type of mode
. Valid types are ['mode', 'toggle']
Example
console.log(verbose.type);
//=> "mode"
console.log(not.type);
//=> "toggle"
name
Readable name of mode
.
Example
console.log(verbose.name);
//=> "verbose"
console.log(not.name);
//=> "not"
fnfn
Optional modifier function that accepts a value and returns a modified value. When not present, an identity function is used to return the original value.
Example
var msg = "some error message";
// wrap message in ansi codes for "red"
msg = red.fn(msg);
console.log(msg);
//=> "\u001b[31msome error message\u001b[39m";
Stats
Stats contructor that contains information about a chained event being built up.
Params
parent
{Object}: Optional stats instance to inheritmodes
andstyles
from.
Example
{
// "not" => toggle, "verbose" => mode
modes: ['not', 'verbose'],
// "red" => modifier
styles: ['red'],
// specified when emitter is created
level: 1,
// name of emitter that will trigger an event
// in this case "red" will not trigger an event
name: 'subhead',
// arguments passed into emitter function "subhead"
args: ['foo', 'bar', 'baz']
}
.addMode
Add a mode to the modes
array for this stats object.
Params
mode
{Object}: Instance of a Mode to add to the stats object.returns
{Object}this
: for chaining.
Example
var verbose = new Mode({name: 'verbose'});
stats.addMode(verbose);
.getModes
Get the array of modes from the stats object. Optionally, pass a property in and return an array with only the property.
Params
prop
{String}: Optional property to pick from the mode objects to return.returns
{Array}: Array of modes or mode properties.
Example
var modes = stats.getModes();
//=> [{name: 'verbose'}]
var modeNames = stats.getModes('name');
//=> ['verbose']
.addStyle
Add a style to the styles
array for this stats object.
Params
style
{String}: Name of style to add.returns
{Object}this
: for chaining.
Example
stats.addStyle('red');
.addEmitter
Sets the emitter for this stats object to indicate this is a complete stats object ready to be emitted.
Params
emitter
{Object}: Instance of a Emitter to add to the stats object.returns
{Object}this
: for chaining.
Example
var info = new Emitter({name: 'info'});
stats.addEmitter(info);
About
Related projects
- falsey: Returns true if
value
is falsey. Works for strings, arrays andarguments
objects with a… more | homepage - is-enabled: Using key paths that may contain "falsey" patterns, check if a property on an object… more | [homepage](https://github.com/doowb/is-enabled "Using key paths that may contain "falsey" patterns, check if a property on an object is enabled.")
- verbalize: A pluggable logging utility with built-in colors, styles, and modes. | homepage
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Building docs
(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)
To generate the readme and API documentation with verb:
$ npm install -g verb verb-generate-readme && verb
Running tests
Install dev dependencies:
$ npm install -d && npm test
Author
Brian Woodward
License
Copyright © 2016, Brian Woodward. Released under the MIT license.
This file was generated by verb-generate-readme, v0.1.31, on September 18, 2016.