Dear diary, you make my logging so easy

This is free to use software, but if you do like it, consider supporting me ❤️

⚡ 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 it's 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);
});

For errors (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 calling diary;

enable(query: string)

Type: Function

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

💨 Benchmark

via the /bench directory with Node v20.2.0

JIT
✔ diary  ~ 1,434,414 ops/sec ± 0.16%
✔ pino   ~    47,264 ops/sec ± 0.02%
✔ bunyan ~     9,644 ops/sec ± 0.01%
✔ debug  ~   444,612 ops/sec ± 0.22%

AOT
✔ diary  ~ 1,542,796 ops/sec ± 0.29%
✔ pino   ~   281,232 ops/sec ± 0.03%
✔ bunyan ~   588,768 ops/sec ± 0.16%
✔ debug  ~ 1,287,846 ops/sec ± 0.24%

AOT: The logger is set up ahead of time, and ops/sec is the result of calling the log fn. Simulates long-running process, with a single logger. JIT: The logger is set up right before the log fn is called per op. Simulates setting up a logger per request for example.

License

MIT © Marais Rossouw