maraisr/diaryPublic

History

readme.md

diary

yarn add diary makes logging simple


downloads size

⚡ Features

⚙️ Install

yarn add diary

🚀 Usage

import { info, diary, middleware } from 'diary';

middleware((logEvent) => {
  if (logEvent.level === 'error') {
    Sentry.captureException(logEvent.extra[0]);
  }
});

info('this important thing happened');
// ~> ℹ info  this important thing happened

const scopedDiary = diary('my-module');
scopedDiary.info('this other important thing happened');
// ~> ℹ info  [my-module] this other important thing happened

Controlling runtime emission of logs:

browser

import { diary } from 'diary';

localStorage.setItem('DEBUG', 'scopeA:two,scopeB:*');

const scopeA1 = diary('scopeA:one');
const scopeA2 = diary('scopeA:two');
const scopeB1 = diary('scopeB:one');
const scopeB2 = diary('scopeB:two');

scopeA1.info('message'); // won't log ✗
scopeA2.info('message'); // will log ✔
scopeB1.info('message'); // will log ✔
scopeB2.info('message'); // will log ✔

node

// example.js
import { diary } from 'diary';

const scopeA1 = diary('scopeA:one');
const scopeA2 = diary('scopeA:two');
const scopeB1 = diary('scopeB:one');
const scopeB2 = diary('scopeB:two');

scopeA1.info('message'); // won't log ✗
scopeA2.info('message'); // will log ✔
scopeB1.info('message'); // will log ✔
scopeB2.info('message'); // will log ✔

$ DEBUG=scopeA:two,scopeB:* node example.js

🔎 API

diary(name: string)

Returns: log functions

A default diary is exported, accessible through simply importing any log function.

Example of default diary
import { info } from 'diary';

info("i'll be logged under the default diary");

name

Type: string

The name given to this diary, will appear in the middleware under the name property as well as in console messages.

log functions

A set of functions that map to console.error, console.warn, console.debug, console.info and console.info. Aptly named;

  • fatal(message: string|Error, ...extra: any[])

  • error(message: string|Error, ...extra: any[])

    If an Error instance is sent, the error object will be accessible through the first item in the extra's array in a middleware. This is for both fatal and error.

  • warn(message: string, ...extra: any[])

  • debug(message: string, ...extra: any[])

  • info(message: string, ...extra: any[])

  • log(message: string, ...extra: any[])

All extra parameters are simply spread onto the console function, so node/browser's built-in formatters will format any objects etc.

middleware(callback: function, diary?: Diary)

Returns: void

Middlewares are function handlers that run for every log function. They allow for modifying the log event object, or simply returning false to bailout. Executing in a forwards direction, meaning middlewares will be run sequentially as they were defined.

handler

Type: Function

Which gets given a single argument of:

interface LogEvent {
  name: string;
  level: LogLevels;
  message: string;
  extra: unknown[];
}
Example
import { middleware, info } from 'diary';

middleware((logEvent) => {
  if (logEvent.level === 'error') {
    fetch('/api/errors', {
      method: 'POST',
      body: JSON.stringify({ error: logEvent.extra[0] }),
    });
  }
});

info('something informative');

This method isn't a Promise, so won't be awaited. It's a fire and forget kinda deal.

diary (optional)

Type: Diary

The result of a calling diary;

A middleware without the optional second parameter, will run for all diaries.

setLevel(level: LogLevel)

Returns: void

Sets the level form which log's will get output to the console.

level

Type: string

One of the log functions's name.

Example
import { setLevel, info } from 'diary';
setLevel('error');

info('something informative');

Note; this will also filter the events from all middlewares.

💨 Benchmark

Validation
✔ diary
✔ ulog
✔ roarr
✔ bunyan
✔ debug
✔ pino
✔ winston

Benchmark
  diary      x 645,535 ops/sec ±1.48% (88 runs sampled)
  ulog       x 22,814 ops/sec ±48.31% (8 runs sampled)
  roarr      x 425,260 ops/sec ±1.71% (92 runs sampled)
  bunyan     x 16,344 ops/sec ±0.83% (94 runs sampled)
  debug      x 34,541 ops/sec ±1.18% (91 runs sampled)
  pino       x 47,025 ops/sec ±1.75% (97 runs sampled)
  winston    x 13,076 ops/sec ±3.23% (89 runs sampled)

Ran with Node v15.5.0

License

MIT © Marais Rossouw