Diary NPM | npm.io

⚡ Features

No dependencies
Outstanding performance
Support for debug's filter
Browser compatible through localStorage
Middleware to pipe into Sentry or alike

⚙️ Install

npm add diary

🚀 Usage

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

after((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

~ programmatic

import { diary, enable } from 'diary';

enable('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 ✔

enable('scopeA:*');

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

🔎 API

diary(name: string)

Returns: log functions

A default diary is exported, accessible through simply importing any log function.
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.

{before,after}(callback: function, diary?: Diary)

Returns: Dispose

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.

When the return is called, it will remove the middleware from the diary instance.

handler

Type: Function

Which gets given a single argument of:

interface LogEvent {
  name: string;
  level: LogLevels;
  message: string;
  extra: unknown[];
}

import { before, after, info } from 'diary';

before((logEvent) => {
  logEvent.context = {
    hello: 'world',
  };
});

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

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.

enable(query: string)

Type: Function

Opts certain log messages into being output. See more here.

💨 Benchmark

Validation
✔ @graphile/logger
✔ bunyan
✔ debug
✔ diary
✔ pino
✔ roarr
✔ ulog
✔ winston

Benchmark
  @graphile/logger     x 18,073,373 ops/sec ±1.00% (87 runs sampled)
  bunyan               x 108,855 ops/sec ±0.77% (95 runs sampled)
  debug                x 200,244 ops/sec ±1.49% (85 runs sampled)
  diary                x 1,144,250 ops/sec ±1.66% (83 runs sampled)
  pino                 x 47,588 ops/sec ±1.11% (90 runs sampled)
  roarr                x 822,330 ops/sec ±1.13% (88 runs sampled)
  ulog                 x 24,555 ops/sec ±28.02% (17 runs sampled)
  winston              x 11,048 ops/sec ±5.27% (81 runs sampled)