console-stamp-color - npm explorer

# Console-Stamp-COLOR 3.5!

[![npm][npm-image]][npm-url]
[![downloads][downloads-image]][npm-url]

[npm-image]: https://img.shields.io/npm/v/console-stamp-color.svg?style=flat-square
[npm-url]: https://npmjs.org/package/console-stamp-color
[downloads-image]: https://img.shields.io/npm/dm/console-stamp-color.svg?style=flat-square

This module lets you take control over the output from console logging methods in Node.js. Such as prefixing the log statement with timestamp information, log levels, add coloured output and much more.

Usage ##

$3

console

npm install console-stamp-color@latest





$3



You need to provide the console object to

console-stamp

 in order to patch the builtin console.

js

require( 'console-stamp-color' )( console );



console.log('Hello, World!');



The default behaviour is to add a prefix to each log statement with timestamp information and log level.

terminal

[10.02.2019 15:37:43.452] [LOG] Hello, World!





You can change this by provinding an options object as the second parameter.

js

require('console-stamp-color')(console, { 

    format: ':date(yyyy/mm/dd HH:MM:ss.l)' 

} );



console.log('Hello, World!');

terminal

[2020/01/19 13:56:49.383] Hello, World!





Notice how the log level is suddenly missing. You need to add it specifically to the format string.

js

require('console-stamp-color')(console, { 

    format: ':date(yyyy/mm/dd HH:MM:ss.l) :label' 

} );



console.log('Hello, World!');

terminal

[2020/01/19 23:20:30.371] [LOG] Hello, World!





Read more about how to customize the formatting of the log statement below.





$3



You can also provide a custom console with its own

stdout and stderr

 like this:

js

const fs = require('fs');

const output = fs.createWriteStream('./stdout.log');

const errorOutput = fs.createWriteStream('./stderr.log');

const logger = new console.Console(output, errorOutput);



require('console-stamp-color')(logger, {

    stdout: output,

    stderr: errorOutput

});





Everything is then written to the files.



NOTE: If

stderr isn't passed, warning and error output will be sent to the given stdout

.



$3

console-stamp

 v3 has been rewritten adding tokens as a new and easier way to customize and extend your logging output.



With that in mind, some consessions has been made and you will probably need to update your

console-stamp

 integration.



####

options.pattern is replaced by options.format

options.format

 is now the place where you provide the format of the logging prefix using tokens.



For example,

{ pattern: 'dd.mm.yyyy HH:MM:ss.l'} is replaced by { format: ':date(dd.mm.yyyy HH:MM:ss.l)' }

.



PS: Providing a string with a date format based on dateformat as a second parameter is still supported. 



####

options.label

 is gone



The log level label (INFO, DEBUG etc.) is now only shown if the token

:label is part of the format string in options.format

. It is part of the default format.

options.labelSuffix and options.labelPrefix are also gone as now you can provide these values directly in the options.format

 string.





$3



Here are some examples on how to customize your log statements with

console-stamp

.



#### Only update timestamp format



Without any other customizations you can provide the timestamp format directly.

js

require('console-stamp-color')( console, 'yyyy/mm/dd HH:MM:ss.l' );



To set the timestamp format using the options object you can use the

date

 token.

js

require('console-stamp-color')(console, { 

    format: ':date(yyyy/mm/dd HH:MM:ss.l)' 

} );



console.log('Hello, World!');



[2020/01/19 23:08:39.202] Hello, World!





#### Add coloured output

console-stamp

 uses the excellent chalk library to provide coloured output and other styling.

js

require( 'console-stamp-color' )( console, {

    format: ':date().blue.bgWhite.underline :label(7)'

} );



You can also simply place some text in parenthesis, and then add your styling to that.

js

require( 'console-stamp-color' )( console, {

    format: '(->).yellow :date().blue.bgWhite.underline :label(7)'

} );





Note that by sending the parameter

--no-color

 when you start your node app, will prevent any colors from console.

console

$ node my-app.js --no-color



For more examples on styling, check out the chalk documentation.







$3



There are only three predefined tokens registered by default. These are:



    :date([format][,utc])[.color]

    :label([padding])[.color]

    :msg[.color]



:date([format][,utc])

* format {String}


    Containing the date format based on dateformat


    Default: 'dd.mm.yyyy HH:MM:ss.l' 

* utc {Boolean}


    Set to

true

 will return UTC-time 


    Default: false

    

:label([padding])

* padding {Number}


    The total length of the label, including the brackets and padding


    Default: 7

    

:msg

* If the

:msg token is provided in format

, the output from the console will be returned in its place, otherwise the console output will be added as the last output, with no formatting.



#### Create a custom token

To define your own token, simply add a callback function with the token name to the tokens option. This callback function is expected to return a string. The value returned is then available as ":foo()" in this case:

javascript

require( 'console-stamp-color' )( console, {

    format: ':foo() :label(7)',

    tokens:{

        foo: () => {

            return '[my prefix]';

        }

    }

} );



console.log("Bar");

terminal

[my prefix] [LOG]   Bar





The token callback function is called with one argument, representing an Object with the following properties:

*

method

 {String} 


    The invoked method

*

msg

 {String} 


    The console output as a string

*

params

 {Array} 


    The token parameters (ex: The token call

:label(7) will have params [7]

)

*

tokens

 {Object} 


    All the defined tokens, incl. the defaults 

*

defaultTokens

 {Object} 


    Only the default tokens, even if it's been redefined in options



##### Example

Here we are making a custom date token called

mydate

 using moment.js to format the date

js

const moment = require('moment');

moment.locale('ja');



require( 'console-stamp-color' )( console, {

    format: ':mydate() :label(7)',

    tokens:{

        mydate: () => {

            return

[${moment().format('LLLL')}]

;

        }

    }

} );



console.log('This is a console.log message');

console.info('This is a console.info message');

console.debug('This is a console.debug message');

console.warn('This is a console.warn message');

console.error('This is a console.error message');





Result:

terminal

[2016年5月12日午前11時10分 木曜日] [LOG]   This is a console.log message

[2016年5月12日午前11時10分 木曜日] [INFO]  This is a console.info message

[2016年5月12日午前11時10分 木曜日] [DEBUG] This is a console.debug message

[2016年5月12日午前11時10分 木曜日] [WARN]  This is a console.warn message

[2016年5月12日午前11時10分 木曜日] [ERROR] This is a console.error message









$3



The option.extend option enables the extension or modification of the logging methods and their associated log levels:



The default logging methods and their log levels are as follows:

js

levels = {

    error: 1,

    warn: 2,

    info: 3,

    log: 4,

    debug: 4

};





The extend option enables the usage of custom console logging methods to be 

used with this module, for example:

js

// Extending the console with a custom method

console.fatal = function(msg) {

    console.org.error(msg);

    process.exit(1);

}



// Initialising the output formatter

require( 'console-stamp-color' )( console, {

    extend: {

        fatal: 1

    }

} );





Note how the

console.org.error method used in the custom method. This is to prevent circular calls to console.error





-------------



$3

js

require( 'console-stamp-color' )( console, [options] );





#### console

The global console or custom console.





#### options {Object|String}



The second parameter is an object with several options. As a feature this parameter can be a string containing the date-format.



* options.format {String}
A string with date format based on dateformat


    Default: ':date(dd.mm.yyyy HH:MM:ss.l) :label'



* options.tokens {Object}
Containing token-functions. See example here.



* options.include {Array}
An array containing the methods to include in the patch


    Default: ["debug", "log", "info", "warn", "error"]



* options.level {String}
A string choosing the most verbose logging function to allow.


    Default:

log





* options.extend {Object}
An object describing methods and their associated log level, 

    to extend the existing

method <-> log level

 pairs.


    For an example see Custom methods.



* options.stdout {WritableStream}
A custom

stdout

 to use with custom console.


    Default:

process.stdout





* options.stderr {WritableStream}
A custom

stderr

 to use with custom console.


    Default:

options.stdout or process.stderr



    

* options.preventDefaultMessage {Boolean}
If set to

true

 Console-stamp will not print out the standard output from the console. This can be used in combination with a custom message token.
Default:

false`

Usage ##

$3

console

npm install console-stamp-color@latest





$3



You need to provide the console object to

console-stamp

 in order to patch the builtin console.

js

require( 'console-stamp-color' )( console );



console.log('Hello, World!');



The default behaviour is to add a prefix to each log statement with timestamp information and log level.

terminal

[10.02.2019 15:37:43.452] [LOG] Hello, World!





You can change this by provinding an options object as the second parameter.

js

require('console-stamp-color')(console, { 

    format: ':date(yyyy/mm/dd HH:MM:ss.l)' 

} );



console.log('Hello, World!');

terminal

[2020/01/19 13:56:49.383] Hello, World!





Notice how the log level is suddenly missing. You need to add it specifically to the format string.

js

require('console-stamp-color')(console, { 

    format: ':date(yyyy/mm/dd HH:MM:ss.l) :label' 

} );



console.log('Hello, World!');

terminal

[2020/01/19 23:20:30.371] [LOG] Hello, World!





Read more about how to customize the formatting of the log statement below.





$3



You can also provide a custom console with its own

stdout and stderr

 like this:

js

const fs = require('fs');

const output = fs.createWriteStream('./stdout.log');

const errorOutput = fs.createWriteStream('./stderr.log');

const logger = new console.Console(output, errorOutput);



require('console-stamp-color')(logger, {

    stdout: output,

    stderr: errorOutput

});





Everything is then written to the files.



NOTE: If

stderr isn't passed, warning and error output will be sent to the given stdout

.



$3

console-stamp

 v3 has been rewritten adding tokens as a new and easier way to customize and extend your logging output.



With that in mind, some consessions has been made and you will probably need to update your

console-stamp

 integration.



####

options.pattern is replaced by options.format

options.format

 is now the place where you provide the format of the logging prefix using tokens.



For example,

{ pattern: 'dd.mm.yyyy HH:MM:ss.l'} is replaced by { format: ':date(dd.mm.yyyy HH:MM:ss.l)' }

.



PS: Providing a string with a date format based on dateformat as a second parameter is still supported. 



####

options.label

 is gone



The log level label (INFO, DEBUG etc.) is now only shown if the token

:label is part of the format string in options.format

. It is part of the default format.

options.labelSuffix and options.labelPrefix are also gone as now you can provide these values directly in the options.format

 string.





$3



Here are some examples on how to customize your log statements with

console-stamp

.



#### Only update timestamp format



Without any other customizations you can provide the timestamp format directly.

js

require('console-stamp-color')( console, 'yyyy/mm/dd HH:MM:ss.l' );



To set the timestamp format using the options object you can use the

date

 token.

js

require('console-stamp-color')(console, { 

    format: ':date(yyyy/mm/dd HH:MM:ss.l)' 

} );



console.log('Hello, World!');



[2020/01/19 23:08:39.202] Hello, World!





#### Add coloured output

console-stamp

 uses the excellent chalk library to provide coloured output and other styling.

js

require( 'console-stamp-color' )( console, {

    format: ':date().blue.bgWhite.underline :label(7)'

} );



You can also simply place some text in parenthesis, and then add your styling to that.

js

require( 'console-stamp-color' )( console, {

    format: '(->).yellow :date().blue.bgWhite.underline :label(7)'

} );





Note that by sending the parameter

--no-color

 when you start your node app, will prevent any colors from console.

console

$ node my-app.js --no-color



For more examples on styling, check out the chalk documentation.







$3



There are only three predefined tokens registered by default. These are:



    :date([format][,utc])[.color]

    :label([padding])[.color]

    :msg[.color]



:date([format][,utc])

* format {String}


    Containing the date format based on dateformat


    Default: 'dd.mm.yyyy HH:MM:ss.l' 

* utc {Boolean}


    Set to

true

 will return UTC-time 


    Default: false

    

:label([padding])

* padding {Number}


    The total length of the label, including the brackets and padding


    Default: 7

    

:msg

* If the

:msg token is provided in format

, the output from the console will be returned in its place, otherwise the console output will be added as the last output, with no formatting.



#### Create a custom token

To define your own token, simply add a callback function with the token name to the tokens option. This callback function is expected to return a string. The value returned is then available as ":foo()" in this case:

javascript

require( 'console-stamp-color' )( console, {

    format: ':foo() :label(7)',

    tokens:{

        foo: () => {

            return '[my prefix]';

        }

    }

} );



console.log("Bar");

terminal

[my prefix] [LOG]   Bar





The token callback function is called with one argument, representing an Object with the following properties:

*

method

 {String} 


    The invoked method

*

msg

 {String} 


    The console output as a string

*

params

 {Array} 


    The token parameters (ex: The token call

:label(7) will have params [7]

)

*

tokens

 {Object} 


    All the defined tokens, incl. the defaults 

*

defaultTokens

 {Object} 


    Only the default tokens, even if it's been redefined in options



##### Example

Here we are making a custom date token called

mydate

 using moment.js to format the date

js

const moment = require('moment');

moment.locale('ja');



require( 'console-stamp-color' )( console, {

    format: ':mydate() :label(7)',

    tokens:{

        mydate: () => {

            return

[${moment().format('LLLL')}]

;

        }

    }

} );



console.log('This is a console.log message');

console.info('This is a console.info message');

console.debug('This is a console.debug message');

console.warn('This is a console.warn message');

console.error('This is a console.error message');





Result:

terminal

[2016年5月12日午前11時10分 木曜日] [LOG]   This is a console.log message

[2016年5月12日午前11時10分 木曜日] [INFO]  This is a console.info message

[2016年5月12日午前11時10分 木曜日] [DEBUG] This is a console.debug message

[2016年5月12日午前11時10分 木曜日] [WARN]  This is a console.warn message

[2016年5月12日午前11時10分 木曜日] [ERROR] This is a console.error message









$3



The option.extend option enables the extension or modification of the logging methods and their associated log levels:



The default logging methods and their log levels are as follows:

js

levels = {

    error: 1,

    warn: 2,

    info: 3,

    log: 4,

    debug: 4

};





The extend option enables the usage of custom console logging methods to be 

used with this module, for example:

js

// Extending the console with a custom method

console.fatal = function(msg) {

    console.org.error(msg);

    process.exit(1);

}



// Initialising the output formatter

require( 'console-stamp-color' )( console, {

    extend: {

        fatal: 1

    }

} );





Note how the

console.org.error method used in the custom method. This is to prevent circular calls to console.error





-------------



$3

js

require( 'console-stamp-color' )( console, [options] );





#### console

The global console or custom console.





#### options {Object|String}



The second parameter is an object with several options. As a feature this parameter can be a string containing the date-format.



* options.format {String}
A string with date format based on dateformat


    Default: ':date(dd.mm.yyyy HH:MM:ss.l) :label'



* options.tokens {Object}
Containing token-functions. See example here.



* options.include {Array}
An array containing the methods to include in the patch


    Default: ["debug", "log", "info", "warn", "error"]



* options.level {String}
A string choosing the most verbose logging function to allow.


    Default:

log





* options.extend {Object}
An object describing methods and their associated log level, 

    to extend the existing

method <-> log level

 pairs.


    For an example see Custom methods.



* options.stdout {WritableStream}
A custom

stdout

 to use with custom console.


    Default:

process.stdout





* options.stderr {WritableStream}
A custom

stderr

 to use with custom console.


    Default:

options.stdout or process.stderr



    

* options.preventDefaultMessage {Boolean}
If set to

true

 Console-stamp will not print out the standard output from the console. This can be used in combination with a custom message token.
Default:

false`