LogFlake

LogFlake is a NodeJS console logger with superpowers. It has the same API as the usual Console but with beautified output, a message header with timestamp and useful information, trackability and a toolset for a better control of your log messages.

const logger = require('logflake');
const log = logger({ logDir: './logs' });

/**
 * here are some usage examples. to the last one (the error) we ask the logger
 * to save the output on a logfile at ./logs. you can also choose to save all
 * the logs output automatically, keep reading the docs to know more about
 */

log('Hello world');

log('Wellcome %s', 'dev');

log('warn', 'Oh no, this is a waning');

log('error', 'Oh no, an error has occurred!').save();

Console message output example:

[ CONSOLE ERROR ] linux: username (main: test.js) 7/24/2021, 11:46:01 PM

This is an error message
········································································

Installing

You can install using npm or yarn

npm install logflake

or

yarn add logflake

Getting Started

Import LogFlake, create a logger function and log whatever you want.

const logger = require('logflake');
const log = logger();

log('Hello world!');

Or if you prefer ESM

import logger from 'logflake';
const log = logger();

log('Hello world!');

When using CJS you can use a shorthand

const log = require('logflake')();

log('Hello world!');

Basic Usage

To log a message or anything, you simply do:

log('Hello World');

This will output:

[ CONSOLE LOG ] linux: username (main: test.js) 7/24/2021, 11:34:14 PM 

Hello world
········································································

You must have noticed the header with useful information. By default, they are:

[ CONSOLE LOG ] linux: username (main: test.js) 7/24/2021, 11:34:14 PM 
1*              2*     3*       4*              5*

1. This is the header prefix or namespace, setted as "CONSOLE" by default. It can be changed by you. The second term is the log level (LOG by default. The header prefixes are colorized in according to the log level: { log: 'blue', info: 'cyan', warn: 'yellow', error: 'red', trace: 'magenta', quiet: 'black' }.

2. The current Operational System label information.

3. The current O.S. username information.

4. The current mainfile that is running the code.

5. The datetime notation (in en by default). You can change the locale on the options.

You can disable or enable the items 2, 3, 4, 5 on the LogFlake options.

The log() function

log(level?: string, ...arguments: any): Chain

We call it the log function because its just a convention, but you can name it whatever yout want. Check how to create a log function in the Getting Started section of this doc. As already said, the log function API has exactly the same usage of the common console.log. So, you can do anything you would do with a console.log, for example:

const example = { fizz: 1, buzz: 2 };

log('Hello %s', 'world');
log('This is an object', example);

The first argument of the log() function can be used to control the Log Level that you want to use. When you dont specify the level, the common log level will be used by default.

Log Levels

The console levels are:

To output an error message, for example:

log('error', 'This is an error message');

This will output:

[ CONSOLE ERROR ] linux: username (main: test.js) 7/24/2021, 11:46:01 PM 

This is an error message
········································································

The usage remains the same:

const error = new Error('Unexpected error');

log('error', 'An unexpected error has occurred: ', error);

Common Log() Examples

// common log
log('Im a common log', 'With many arguments', 'and Log level infered');

// info log
log('info', 'Im a info log level and my prefix is cyan');

// warn log
log('warn', 'Im a warning, i have a yellow prefix');

Logging an error:

const where = 'myfile';

log('error', 'This is an error on %s', where);

Outputing a console trace:

log('trace', 'This message will output a trace');

Generating a log message in quiet mode:

log('quiet', 'Anything will be outputed on std');

Logger Options

There is a plenty of options you can set on your logger. You must pass the options as an object when calling the LogFlake function:

const logger = require('logflake');

const log = logger({ /* options go here */ });

For example, to change the namespace, disable the output colors and add a line break after every log, you can do:

const logger = require('logflake');

const log = logger({
  prefix: 'Example',
  colors: false,
  linebreak: true
});

log('info', 'This is an example');

Options

Obs 1. You can check all the format available options here: https://nodejs.org/api/util.html#util_util_inspect_object_options

Obs 2. Every log() log function position on the code is marked with a unique hash, so we can count how many times it was called, for example.

Obs 3. The headerTextColor option accepts any Chalk color. Check all the modifiers here: https://www.npmjs.com/package/chalk

Namespaces (Prefix)

For every log function instance you can have a namespace. This is simply a prefix showed on the console message header. To change the console namespace (prefix) you can pass a string when creating the log() function, or pass it as an option.

Using namespaces:

You can define a namespace directly when creating the log() function:

const logger = require('logflake');
const log = logger('Hello');              // HELLO will be the namespace

log('Hello world');                       // HELLO namespaced log
log('error', 'This is an error message'); // HELLO namespaced log

Will output:

[ HELLO LOG ] linux: username (main: test.js) 7/24/2021, 11:45:57 PM 

Hello world
········································································
[ HELLO ERROR ] linux: username (main: test.js) 7/24/2021, 11:46:01 PM 

This is an error message
········································································

Note the "Hello" namespace on the log header. Every message logged with the namespaced log() function will be prefixed with HELLO.

Defining the namespace as an option:

You can also pass the namespace by defining the prefix option:

const logger = require('logflake');
const log = logger({ prefix: 'Hello' });  // "HELLO" will be the Namespace

log('Hello world');                       // HELLO namespaced log
log('error', 'This is an error message'); // HELLO namespaced log

Namespace shorthand

If you wont use any other option, and you are using CJS, you can use a shorthand and pass the namespace directly like this:

const log = require('logflake')('Namespace');

Advanced usage

The log() function has a chained toolset that allows you to control and change your log behavior. To run a log only once inside a loop and save its output on a file, for example, you could do:

const logger = require('logflake');
const log = logger({ logDir: './logs' });

for(let i=0; i<100; i++) {
  log('error', 'Oh no, an error has occurred!')
    .once()
    .save();
}

The log above will be fired only once, even inside a loop, and its output will be saved on a file at logDir path. The log() chain provides chained methods to help you with things like that. We will talk about chained methods in a next sections.

Chaining

Any log call has a chain of useful methods. The example below runs only once and saves its output on a local file. See the section Chained methods of this doc to know more about.

log('This is an example')
  .once()
  .save();

Referencing

You can create a "reference" to a log function by assigning it to a variable or const:

// the log will be fired and assigned to a const
const logError = log('Unexpected error');

// the log will be saved
logError.save();

In the example bellow, the log will be triggered, assigned to the const, then saved. But you can have a situation when you dont want to immediately trigger the log while assigning it to a variable, then you can use quiet as log level. In the example, the fire() method will trigger the referenced log:

const logError = log('quiet', 'Unexpected error');

logError.fire('error').save();

Chained Methods

As said, you can use chained methods to change your log behavior. The methods are:

save

save(options?: SaveOptions): chain  

Saves the log output to a local file. This method depends on the option logDir. The logDir option will specify where to save the log files. When calling "save()" a file named with the current date will be created on the logDir. All the logs saved on the current day and pointing to the same folder will be saved in the same file, and so on.

Usage:

const logger = require('logflake');
const log = logger({ logDir: './logs/' });

// this log message wont be saved
log('Not saved');

// this log message will be saved
log('Will be saved').save();

When the option alwaysSave is true, all the logs will be saved. The save method will be implicitly called for all of them. In this case, your explicity save() callings will be ignored to avoid duplication. If you set { force: true } as save() option, it will be fired twice: one due the alwaysSave option, another due the explicit save({ force: true }).

For example:

const logger = require('logflake');
const log = logger({ logDir: './logs/', alwaysSave: true });

// this log message will be saved 1 time
log('Will be saved A');

// this log message will be saved 1 time
log('Will be saved B').save();

// this log will be saved 2 times, one
// due the alwaysSave, other due forced save
log('Will be saved C').save({ force: true});

The only available option on save is { force }.

once

once(): chain  

Tells the log to be fired for one single time on the current runtime. If you are inside a big for loop, a route or whatever, and for some reason a deduplicated log is useful for you, or if you just dont want thounsands of duplicated outputs, you can use once:

for(let i = 0; i < 1000; i++) {
  // this log will be fired only once
  log('Just one time').once();
}

The log chain will also occur only once:

for(let i = 0; i < 1000; i++) {
  // this log will be fired and saved only once
  log('Just one time').once().save();
}

get

get(callback: Function, colors: boolean = false): chain

Gets the current log output and a bunch of useful information. This is handy when you want to send an specific log output/information to other destinations as a database, slack, telegram, etc.

log('error', 'Example').get((output, info) => {
  // do whatever you want with the params
});

This function accepts a callback that returns the log output and an info object. Also accepts a second boolean parameter which gets the output with colors; default is false. Note: if this very same function has been called 1000 times, the hash will be the same since is a hash per function/line.

Callback

cb(output: string, info: object): unknown

Output

For the given example, the output would be the following string:

[ CONSOLE ERROR ] linux: username (main: test.js) 7/26/2021, 9:42:49 PM 

Example
········································································

Info

The info object returns the following properties:

{
  hash       | the triggered function hash
  trace      | a stack trace of the triggered log
  level      | the log level that has been called
  date       | the current date of the log call
  dateUTC    | the current UTC date of the log call
  callCount  | number of times that this same log was triggered
}

fire

fire(level?: string, args?: any): chain

When using references, you can use fire to trigger the referenced log. When using fire, you also gets a new log function. The level parameter on this function overrides the original log level, and the args increments the original parameters. If you dont specify a level for fire(), "log" will be used by default. For example:

const logError = log('quiet', 'Unexpected error');

if (someErrorCheck) {
  logError.fire('error'); // log "Unexpected error" x1
}

if (anotherErrorCheck) {
  logError.fire('error'); // log "Unexpected error" x1
}

You can also use different log levels for same reference:

const logGeneric = log('quiet', 'Generic message');

if (whateverYouWant) {
  logGeneric.fire();        // log LOG "Generic message" x1
}

if (someErrorCheck) {
  logGeneric.fire('error'); // log ERROR "Generic message" x1
}

if (anotherErrorCheck) {
  logGeneric.fire('warn');  // log WARN "Generic message" x1
}

You can also increment te original parameters:

const reportFileError = log('quiet', 'There was an error on the file %s');

// output: There was an error on the file index.js
reportFileError.fire('error', 'index.js');

const logProcessedObject = log('quiet', 'Object processed: ');

// output: Object processed: { fizz: 1, buzz: 2 }
logProcessedObject.fire('info', { fizz: 1, buzz: 2});

// output: Object processed: { fizz: 1, buzz: 2 } { fizzbuzz: 3 }
logProcessedObject.fire('info', { fizz: 1, buzz: 2}, { fizzbuzz: 3 });

Events

The onLog event is available as a Logger Option and accepts a callback that is triggered everytime a log output occurs. The params passed to the callback are output and info containing useful information about the triggered log. It works very similar to the get method, but its automatically triggered for all log outputs.

const logger = require('logflake');

const log = logger({
  onLog: (output, info) => {
    // do whatever you want with the params
  }
});

log('Hello world');
log('error', 'Oh no, an error!');

On the example above, the onLog function callback will be triggered 2 times, passing the output containing the log contents, and the info with information about the log call. To see details about the output and 'info' params, check the get() method on the Chained methods section. Everytime a log is generated with this instance (function), the onLog callback will be triggered. Your callback will have this signature:

cb(output: string, info: object): unknown

This is very very handy if you want to create plugins or new transporters for LogFlake. You can use it to capture the logs and send to a database, slack, telegram or whatever you want.

About

LogFlake is a Free and Open Source package created by Felippe Regazio.