npm add diary makes logging simple

---

⚡ Features

• No dependencies
• Outstanding performance
• Support for debug's filter

⚙️ Install

npm add diary

🚀 Usage

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

// 1️⃣ Choose to enable the emission of logs, or not.
enable('*');

// 2️⃣ log something
info('this important thing happened');
// ~> ℹ info  this important thing happened

// Maybe setup a scoped logger
const scopedDiary = diary('my-module', (event) => {
  if (event.level === 'error') {
    Sentry.captureException(event.error);
  }
});

// 3️⃣ log more things
scopedDiary.info('this other important thing happened');
// ~> ℹ info  [my-module] this other important thing happened

Node users

The enable function is executed for you from the DEBUG environment variable. And as a drop in replacement for debug.

DEBUG=client:db,server:* node example.js

🔎 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;

  messages: any[];
}

Note: you can attach any other context in middleware.

Example

import { diary, default_reporter } from 'diary';
const scope = diary('scope', (event) => {
  event.ts = new Date();
  return default_reporter(event);
});

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, error, warn, debug, info, and log. All of which follow the same api signature:

declare logFunction(message: object | Error | string, ...args: unknown[]): void;

All parameters are simply spread onto the function and reported. Node/browser's built-in formatters will format any objects (by default).

info('hi there'); // ℹ info  hi there
info('hi %s', 'there'); // ℹ info  hi there
info('hi %j', { foo: 'bar' }); // ℹ info hi { "foo": "bar" }
info('hi %o', { foo: 'bar' }); // ℹ info hi { foo: 'bar' }
info({ foo: 'bar' }); // ℹ info { foo: 'bar' }

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 v18.10.0

benchmark :: jit
  bunyan               x    10,398 ops/sec ±0.59% (94 runs sampled)
  debug                x   458,688 ops/sec ±4.73% (85 runs sampled)
  diary                x 1,054,755 ops/sec ±12.08% (79 runs sampled)
  pino                 x    40,553 ops/sec ±0.68% (97 runs sampled)

benchmark :: aot
  bunyan               x 448,535 ops/sec ±14.30% (72 runs sampled)
  debug                x 878,692 ops/sec ±18.58% (76 runs sampled)
  diary                x 795,359 ops/sec ±31.93% (59 runs sampled)
  pino                 x 263,425 ops/sec ±0.83% (98 runs sampled)

Related

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

License

MIT © Marais Rossouw