Skip to content

A fancy wrapper for debug with and chaining support for full Console Web API.

License

Notifications You must be signed in to change notification settings

bitchcraft/unicorn-logger

Repository files navigation

@bitchcraft/unicorn-logger

             ,
          „„/,
         / (×\
   ,—~~~’ / `-'    UnicornLogger
  /( )__( )   ́ ́ ́           1.2.0
 ‘ //   //    ́ ́ ́ ́ ́  
   ``   ``   ́ ́ ́ ́ ́ ́ ́ ́

A fancy wrapper for debug that supports all Console Web API methods and allows chaining.

CircleCI

Installation

$ yarn add @bitchcraft/unicorn-logger
$ npm install -P @bitchcraft/unicorn-logger

Usage

UnicornLogger optimizes debug for writing to the browser console, but is also usable in NodeJS. It binds all Console Web API methods to debug with graceful fallbacks.

As with debug you can control the logging output with the DEBUG env (NodeJS) or a localStorage key debug. Values are a string with wildcards (e. g. api:*,-api:auth*,-*info*,*important*).

Create a new logger instance by calling the UnicornLogger constructor with a namespace (string). The new logger instance is directly callable (defaults to log) and exposes the following methods on top. All methods return a reference to the instance to allow method chaining.

ES6 example

import UnicornLogger from '@bitchcraft/unicorn-logger';

const logger = new UnicornLogger('myNamespace');
logger.group('new console group')
	.log('some stuff: %O', { logger })
	.warn('Oops. There is some unicorn barf on the ground.')
	.error('Something went seriously wrong here')
	.groupEnd();

ES5 example

var UnicornLogger require('@bitchcraft/unicorn-logger');
var logger = UnicornLogger('myNamespace');

logger.group('new console group')
	.log('some stuff: %O', { logger })
	.warn('Oops. There is some unicorn barf on the ground.')
	.error('Something went seriously wrong here')
	.groupEnd();

Supported methods

Method Parameters Description
assert assertion: boolean, ...obj: Any Writes an error message to the console if the assertion is false. If the assertion is true, nothing happens.
clear Clears the console
error ...obj: Any Outputs an error message to the console
group label: string Creates a new inline group in the Web Console log. This indents following console messages by an additional level, until groupEnd() is called.
groupCollapsed label: string Creates a new collapsed inline group in the Web Console log.
groupEnd Exits the current inline group in the Web Console.
info ...obj: Any Outputs an informational message to the Web Console. Most browsers prefix these messages with an (i)-icon.
log (alias: debug) Outputs a message to the console.
table data: Array or Object, columns: Object Displays tabular data as a table.
time label: string Starts a timer you can use to track how long an operation takes. You give each timer a unique name, and may have up to 1,000 timers per instance. When you call console.timeEnd() with the same label, the elapsed time in milliseconds since the timer was started will be written to the console.
timeEnd label: string Stops a timer that was previously started by calling time().
trace ...obj: Any Outputs a stack trace to the console.
warn ...obj: Any Outputs a warning message to the console.

ES2015+ import with flow types

// babel: env, stage-0, flow
import UnicornLogger from '@bitchcraft/unicorn-logger/src/UnicornLogger';

Plugins/Middlewares

UnicornLogger can be extended trough middlewares/plugins. A middleware can:

  • react to logging calls
  • manipulate call arguments
  • cancel the further execution of logging calls
  • register its own logging functions

Middlewares can be easily added to an instance or globally to the logger Class. Global middlewares are applied before instance ones, both will be executed in the order they were added.

import UnicornLogger from '@bitchcraft/unicorn-logger';

const logger = new UnicornLogger('myNamespace');
logger.use(new ExampleMiddleware()); // Instance Middleware
UnicornLogger.use(new ExampleMiddleware()); // Global Middleware

For middleware development see the wiki

Bundle size

About core-js takes up roughly 62% of the bundle size, which should not increase your bundle size if you are running babel. After minification, the gzipped size (including core-js) should be around 13KB. You can check out the bundle analytics for the non-minified bundle.

Help and feedback

Please file issues in Github

Contribute

We are open for PRs. Please respect to the linting rules.

License

UnicornLogger is free software und the BSD-3-Clause (see LICENSE.md). The unicorn UTF8 art is CC-Attribution 2018 Josh Li.

Contributors