diary

npm add diary makes logging simple


downloads size
## ⚑ 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) - Browser compatible through `localStorage` ## βš™οΈ Install ```sh npm add diary ``` ## πŸš€ Usage ```ts 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, using the code below as an example: ```ts // 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 βœ” ``` #### _browser_ ```ts localStorage.setItem('DEBUG', 'scopeA:two,scopeB:*'); // then your scripts ``` > πŸ’‘ Tip - Set this via the DevTools, then hit refresh. Saves you having to re-bundle. #### _node_ ```sh DEBUG=scopeA:two,scopeB:* node example.js ``` #### _workers_ Create an [Environment Variable](https://developers.cloudflare.com/workers/platform/environments) with `DEBUG`. > ⚠️ Specifically referencing the Cloudflare Workers #### _programmatic_ ```ts 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](#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; 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](#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 v16.2.0 ``` Validation βœ” @graphile/logger βœ” bunyan βœ” debug βœ” diary βœ” pino βœ” roarr βœ” ulog βœ” winston Benchmark @graphile/logger x 20,198,944 ops/sec Β±1.15% (89 runs sampled) bunyan x 120,302 ops/sec Β±0.63% (94 runs sampled) debug x 211,486 ops/sec Β±1.95% (88 runs sampled) diary x 6,682,958 ops/sec Β±1.79% (90 runs sampled) pino x 40,994 ops/sec Β±2.15% (83 runs sampled) roarr x 812,015 ops/sec Β±1.87% (84 runs sampled) ulog x 24,878 ops/sec Β±24.93% (19 runs sampled) winston x 9,499 ops/sec Β±14.17% (67 runs sampled) ``` ## 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)