Hackable and configurable to the core, signale can be used for logging purposes, status reporting, as well as for handling the output rendering process of other node modules and applications.
Come over to Gitter or Twitter to share your thoughts on the project.
- 15 out-of-the-box loggers
- Hackable to the core
- Clean and beautiful output
- Integrated timers
- Custom pluggable loggers
- Filename, date and timestamp support
- Scoped loggers and timers
- Simple and minimal syntax
- Globally configurable through
package.json
- Overridable configuration per file and logger
npm install signale
Import signale and start using any of the default loggers.
View all of the available loggers.
await
complete
error
debug
fatal
fav
info
note
pause
pending
star
start
success
warn
watch
const signale = require('signale');
signale.success('Operation successful');
signale.debug('Hello', 'from', 'L59');
signale.pending('Write release notes for 1.2.0');
signale.fatal(new Error('Unable to acquire lock'));
signale.watch('Recursively watching build directory...');
signale.complete({prefix: '[task]', message: 'Fix issue #59', suffix: '(@klauscfhq)'});
To create a custom logger define an options
object yielding a types
field with the logger data and pass it as argument to a new signale instance.
const {Signale} = require('signale');
const options = {
scope: 'custom',
types: {
remind: {
badge: '**',
color: 'yellow',
label: 'reminder'
},
santa: {
badge: 'π
',
color: 'red',
label: 'santa'
}
}
};
const custom = new Signale(options);
custom.remind('Improve documentation.');
custom.santa('Hoho! You have an unused variable on L45.');
Additionally, all default loggers can be overridden to your own preference.
Here is an example where we override the default error
and success
loggers.
const {Signale} = require('signale');
const options = {
types: {
error: {
badge: '!!',
color: 'red',
label: 'fatal error'
},
success: {
badge: '++',
color: 'green',
label: 'huge success'
}
}
};
const signale = new Signale();
signale.error('Default Error Log');
signale.success('Default Success Log');
const custom = new Signale(options);
custom.error('Custom Error Log');
custom.success('Custom Success Log');
The options
object can hold the scope
and types
attributes, where the first corresponds to the name of the scope the logger is reporting from and the second is where the objects named after the custom loggers reside.
- Type:
String
Name of the scope.
- Type:
Object
Holds the configuration of the custom and default loggers.
- Type:
String
The icon corresponding to the logger.
- Type:
String
The label used to identify the type of the logger.
- Type:
String
The color of the label, can be any of the foreground colors supported by chalk.
To create a scoped logger from scratch, define the scope
field inside the options
object and pass it as argument to a new signale instance.
const {Signale} = require('signale');
const options = {
scope: 'global scope'
};
const global = new Signale(options);
global.success('Successful Operation');
To create a scoped logger based on an already existing one, use the scope()
function, which will return a new signale instance, inheriting all custom loggers, timers and configuration from the initial one.
const signale = require('signale');
const global = signale.scope('global scope');
global.success('Hello from the global scope');
function foo() {
const outer = global.scope('outer', 'scope');
outer.success('Hello from the outer scope');
setTimeout(() => {
const inner = outer.scope('inner', 'scope');
inner.success('Hello from the inner scope');
}, 500);
}
foo();
Timer are managed by the time()
and timeEnd()
functions. A unique label can be used to identify a timer on initialization, though if none is provided the timer will be assigned one automatically. In addition, calling the timeEnd()
function without a specified label will have as effect the termination of the most recently initialized timer, that was created without providing a label.
const signale = require('signale');
signale.time('test');
signale.time();
signale.time();
setTimeout(() => {
signale.timeEnd();
signale.timeEnd();
signale.timeEnd('test');
}, 500);
To enable global configuration define the options under the signale
namespace in your package.json
.
The following illustrates all the available options with their respective default values.
{
"signale": {
"displayScope": true,
"displayBadge": true,
"displayDate": false,
"displayFilename": false,
"displayLabel": true,
"displayTimestamp": false,
"underlineLabel": true,
"underlineMessage": false
}
}
View all of the available options in detail.
- Type:
Boolean
- Default:
true
Display the scope name of the logger.
- Type:
Boolean
- Default:
true
Display the badge of the logger.
- Type:
Boolean
- Default:
false
Display the current local date in YYYY-MM-DD
format.
- Type:
Boolean
- Default:
false
Display the name of the file that the logger is reporting from.
- Type:
Boolean
- Default:
true
Display the label of the logger.
- Type:
Boolean
- Default:
false
Display the current local time in HH:MM:SS
format.
- Type:
Boolean
- Default:
true
Underline the logger label.
- Type:
Boolean
- Default:
false
Underline the logger message.
To enable local configuration call the config()
function on your signale instance. Local configurations will always override any pre-existing configuration inherited from package.json
.
In the following example, loggers in the foo.js
file will run under their own configuration, overriding the package.json
one.
// foo.js
const signale = require('signale');
// Overrides any existing `package.json` config
signale.config({
displayFilename: true,
displayTimestamp: true,
displayDate: false
});
signale.success('Hello from the Global scope');
Also, scoped loggers can have their own independent configuration, overriding the one inherited by the parent instance or package.json
.
// foo.js
const signale = require('signale');
signale.config({
displayFilename: true,
displayTimestamp: true,
displayDate: false
});
signale.success('Hello from the Global scope');
function foo() {
// `fooLogger` inherits the config of `signale`
const fooLogger = signale.scope('foo scope');
// Overrides both `signale` and `package.json` configs
fooLogger.config({
displayFilename: true,
displayTimestamp: false,
displayDate: true
});
fooLogger.success('Hello from the Local scope');
}
foo();
- Type:
Function
Can be any default or custom logger.
- Type:
String
Can be one or more comma delimited strings.
const signale = require('signale');
signale.success('Successful operation');
//=> β success Successful operation
signale.success('Successful', 'operation');
//=> β success Successful operation
- Type:
Error Object
Can be any error object.
const signale = require('signale');
signale.error(new Error('Unsuccessful operation'));
//=> β error Error: Unsuccessful operation
// at Module._compile (module.js:660:30)
// at Object.Module._extensions..js (module.js:671:10)
// ...
- Type:
Object
Can be an object holding the prefix
, message
and suffix
attributes, with prefix
and suffix
always prepended and appended respectively to the logged message
.
const signale = require('signale');
signale.complete({prefix: '[task]', message: 'Fix issue #59', suffix: '(@klauscfhq)'});
//=> [task] β complete Fix issue #59 (@klauscfhq)
Defines the scope name of the logger.
- Type:
String
Can be one or more comma delimited strings.
const signale = require('signale');
const foo = signale.scope('foo');
const fooBar = signale.scope('foo', 'bar');
foo.success('foo');
//=> [foo] βΊ β success foo
fooBar.success('foo bar');
//=> [foo] [bar] βΊ β success foo bar
Clears the scope name of the logger.
const signale = require('signale');
const foo = signale.scope('foo');
foo.success('foo');
//=> [foo] βΊ β success foo
foo.unscope();
foo.success('foo');
//=> β success foo
Sets the configuration of an instance overriding any existing global or local configuration.
- Type:
Object
Can hold any of the documented options.
// foo.js
const signale = require('signale');
signale.config({
displayFilename: true,
displayTimestamp: true,
displayDate: true
});
signale.success('Successful operations');
//=> [2018-5-15] [11:12:38] [foo.js] βΊ β success Successful operations
- Return Type:
String
Sets a timers and accepts an optional label. If none provided the timer will receive a unique label automatically.
Returns a string corresponding to the timer label.
- Type:
String
Label corresponding to the timer. Each timer must have its own unique label.
const signale = require('signale');
signale.time();
//=> βΆ timer_0 Initialized timer...
signale.time();
//=> βΆ timer_1 Initialized timer...
signale.time('label');
//=> βΆ label Initialized timer...
- Return Type:
Object
Deactivates the timer to which the given label corresponds. If no label is provided the most recent timer, that was created without providing a label, will be deactivated.
Returns an object {label, span}
holding the timer label and the total running time.
- Type:
String
Label corresponding to the timer, each timer has its own unique label.
const signale = require('signale');
signale.time();
//=> βΆ timer_0 Initialized timer...
signale.time();
//=> βΆ timer_1 Initialized timer...
signale.time('label');
//=> βΆ label Initialized timer...
signale.timeEnd();
//=> βΌ timer_1 Timer run for: 2ms
signale.timeEnd();
//=> βΌ timer_0 Timer run for: 2ms
signale.timeEnd('label');
//=> βΌ label Timer run for: 2ms
For more info on how to contribute to the project, please read the contributing guidelines.
- Fork the repository and clone it to your machine
- Navigate to your local fork:
cd signale
- Install the project dependencies:
npm install
oryarn install
- Lint code for errors:
npm test
oryarn test
- Klaus Sinani (@klauscfhq)