diary: A TypeScript repository from abeforgit

npm add diary makes logging simple

⚡ 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:

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, 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

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

Benchmark
  @graphile/logger     x 21,801,529 ops/sec ±0.88% (93 runs sampled)
  bunyan               x 109,073 ops/sec ±0.71% (94 runs sampled)
  debug                x 228,734 ops/sec ±1.28% (88 runs sampled)
  diary                x 6,962,434 ops/sec ±0.50% (93 runs sampled)
  pino                 x 48,998 ops/sec ±0.93% (91 runs sampled)
  roarr                x 927,402 ops/sec ±0.64% (94 runs sampled)
  ulog                 x 25,681 ops/sec ±27.59% (17 runs sampled)
  winston              x 12,314 ops/sec ±5.01% (83 runs sampled)

Ran with Node v16.2.0

abeforgit/diary