https://github.com/maraisr/diary

📑 Zero-dependency, fast logging library for Node, Browser and Workers
https://github.com/maraisr/diary

cloudflare-workers debug fast logger logging logging-library middleware pino winston

Last synced: 9 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/maraisr/diary
• Owner: maraisr
• License: mit
• Created: 2020-09-12T00:10:28.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2024-09-06T03:03:36.000Z (2 months ago)
• Last Synced: 2024-10-30T03:57:08.243Z (10 days ago)
• Topics: cloudflare-workers, debug, fast, logger, logging, logging-library, middleware, pino, winston
• Language: TypeScript
• Homepage:
• Size: 495 KB
• Stars: 253
• Watchers: 6
• Forks: 7
• Open Issues: 1
• Metadata Files:
  • Readme: readme.md
  • License: license

Awesome Lists containing this project

• awesome - maraisr/diary - 📑 Zero-dependency, fast logging library for Node, Browser and Workers (TypeScript)
• awesome-node-esm - diary - zero-dependency, fast logging library for both Node and Browser. (Packages / Logging)

README

        




# ![diary](./shots/logo.png)







**Dear diary, you make my logging so easy**



  





  





  





  











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

[![sponsor me](https://badgen.net/badge/icon/sponsor?icon=github&label&color=gray)](https://github.com/sponsors/maraisr)

[![buy me a coffee](https://badgen.net/badge/icon/buymeacoffee?icon=buymeacoffee&label&color=gray)](https://www.buymeacoffee.com/marais)





## ⚡ Features

- No [dependencies](https://npm.anvaka.com/#/view/2d/diary)

- Outstanding [performance](#-benchmark)

- Support for [`debug`'s filter](https://www.npmjs.com/package/debug#wildcards)

## ⚙️ Install

```sh

npm add diary

```

## 🚀 Usage

```ts

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`.

```shell

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

```

## 🔎 API

### diary(name: string, onEmit?: Reporter)

Returns: [log functions](#log-functions)

> A default diary is exported, accessible through simply importing any [log function](#log-functions).

>

> 

> Example of default diary

>

> ```ts

> 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](#enablequery-string)). A reporter gets given the

`LogEvent` interface:

```ts

interface LogEvent {

  name: string;

  level: LogLevels;

  messages: any[];

}

```

> _Note_: you can attach any other context in middleware.

>

> Example

>

> ```ts

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

```ts

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).

```ts

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](#diary-name-string);

### enable(query: string)

Type: `Function`

Opts certain log messages into being output. See more [here](#programmatic).

## 💨 Benchmark

> via the [`/bench`](/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

- [workers-logger](https://github.com/maraisr/workers-logger) — fast and effective logging for

  [Cloudflare Workers](https://workers.cloudflare.com/)

## License

MIT © [Marais Rossouw](https://marais.io)