Skip to content
/ diary Public

📑 Zero-dependency, fast logging library for Node, Browser and Workers

License

Notifications You must be signed in to change notification settings

maraisr/diary

Repository files navigation

diary

Dear diary, you make my logging so easy

js downloads licenses gzip size brotli size

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

sponsor me buy me a coffee

⚡ Features

⚙️ 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 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 setup a head 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 setup right before the log fn is called per op. Simulates setting up a logger per request for example.

Related

License

MIT © Marais Rossouw