⚡ Features

• No dependencies
• Outstanding performance
• Support for debug's filter
• Browser compatible through localStorage

⚙️ Install

npm add diary

🚀 Usage

import { info, diary } from 'diary';

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

const scopedDiary = diary('my-module', (event) => {
  if (event.level === 'error') {
    Sentry.captureException(event.error);
  }
});

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

Controlling runtime emission of logs, using the code below as an example:

// 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 ✔

browser

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

// then your scripts

💡 Tip - Set this via the DevTools, then hit refresh. Saves you having to re-bundle.

node

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

workers

Create an Environment Variable with DEBUG.

⚠️ Specifically referencing the Cloudflare Workers

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, onEmit?: Reporter)

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—and will also be available in all logEvents.

onEmit (optional)

Type: Reporter

A reporter is run on every log message (provided its enabled). A reporter gets given the LogEvent interface:

interface LogEvent {
  name: string;
  level: LogLevels;

  message: string;
  extra: unknown[];
}

Errors (for error and fatal) there is also an error: Error property.

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 with the error property on the context, 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.

diary (optional)

Type: Diary

The result of a calling diary;

enable(query: string)

Type: Function

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

💨 Benchmark

via the /bench directory with Node v16.2.0

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

Benchmark
  @graphile/logger     x 20,198,944 ops/sec ±1.15% (89 runs sampled)
  bunyan               x    120,302 ops/sec ±0.63% (94 runs sampled)
  debug                x    211,486 ops/sec ±1.95% (88 runs sampled)
  diary                x  6,682,958 ops/sec ±1.79% (90 runs sampled)
  pino                 x     40,994 ops/sec ±2.15% (83 runs sampled)
  roarr                x    812,015 ops/sec ±1.87% (84 runs sampled)
  ulog                 x     24,878 ops/sec ±24.93% (19 runs sampled)
  winston              x      9,499 ops/sec ±14.17% (67 runs sampled)

Related

• workers-logger — fast and effective logging for Cloudflare Workers

License

MIT © Marais Rossouw