@mmutils/logger 0.1.0 → 0.1.1

package/README.md

@@ -78,6 +78,8 @@ Requires Node.js 20 or newer.
 
 ## Quick start
 
+<!-- code:quick-start -->
+
 ```ts
 import { Logger, messagePlugin, graphPlugin } from '@mmutils/logger';
 
@@ -92,8 +94,12 @@ logger.error(new Error('Connection lost'));
 logger.infoGraph([1, 3, 8, 21, 8, 3], { title: 'CPU', unit: '%' });
 ```
 
-This prints the sample at the top. Plugins can also be chained, with the
-same typing:
+<!-- /code -->
+
+This prints the sample at the top
+([`examples/quick-start.js`](examples/quick-start.js)); every feature has
+its own example, see [Examples](#examples). Plugins can also be chained,
+with the same typing:
 
 ```ts
 const logger = new Logger().use(messagePlugin()).use(graphPlugin());
@@ -291,6 +297,36 @@ logger.infoGraph(values, {
 });
 ```
 
+For example, from [`examples/graphs.js`](examples/graphs.js), with the
+datasets of [`examples/data.js`](examples/data.js):
+
+<!-- code:graph -->
+
+```ts
+logger.infoGraph(latency, {
+  title: 'Latency',
+  unit: 'ms',
+  precision: 0,
+  aggregate: 'max', // the slowest request of each bar
+  axis: { start: 0, end: 1032.4, unit: 'ms', capTo: 1 }, // a time axis
+});
+logger.warningGraph(queue, {
+  title: 'Queue',
+  rows: 2,
+  axis: { start: 'Mon', end: 'Fri' },
+});
+logger.infoGraph(temperatures, {
+  title: 'Temperature',
+  unit: '°C',
+  precision: 1,
+  rows: 4,
+  baseline: 20, // warmer days grow up, colder days down
+  axis: { start: 'Mar 2', end: 'Mar 15' },
+});
+```
+
+<!-- /code -->
+
 ![A latency graph with max aggregation and a time axis, a queue graph with day labels, and a temperature graph split at 20 °C](assets/graph.svg)
 
 <details>
@@ -300,14 +336,14 @@ logger.infoGraph(values, {
 
 ```text
 2026/03/16 15:35:00 [i]   info
-Latency                 89.17 ms
-│                   █          │
-│   ▁▁            ▁▁█          │
-│▆█████▇▅▄▃▂▃▄▅▆█████▇▆▄▃▂▂▃▅▆▇│
+Latency                   370 ms
+│  ▇   ▇    ▃    ▆   █    ▃    │
+│▃▄█▅▅▄█▃▂  █  ▁▂█▄▅▅█▄▃▂▁█    │
+│████████████▇█████████████▇▇▇█│
 0ms                      1s 32ms
-average: 20.72 ms        0.00 ms
-min: 8.00 ms
-max: 89.17 ms
+average: 154 ms             0 ms
+min: 105 ms
+max: 370 ms
 2026/03/16 15:35:00 /!\  warning
 Queue                       9.00
 │       ▁▁▃▃▄▆▆██▆▆▄▃▃▁▁       │
@@ -317,16 +353,16 @@ average: 4.76               0.00
 min: 1.00
 max: 9.00
 2026/03/16 15:35:00 [i]   info
-Temperature              25.1 °C
-│      ▁▂▁▁                    │
-│  ▄▅▇██████▆▆▂▂               │
-│               ▀▀█████████████│
-│                  ▔▀▀█████▀▀▔▔│
+Temperature              25.8 °C
+│  ▂▃▆▇██▆▄▁                   │
+│▄▄█████████▄▃             ▁▁▁▁│
+│             ▀▀████████▀▔▔    │
+│               ▔▔▀▀▀▀▔        │
 Mar 2                     Mar 15
-average: 18.4 °C         11.5 °C
+average: 20.4 °C         15.4 °C
 baseline: 20.0 °C
-min: 11.5 °C
-max: 25.1 °C
+min: 15.4 °C
+max: 25.8 °C
 ```
 
 <!-- /output -->
@@ -388,6 +424,38 @@ from -10 to 10:
 | `'max'`          | only down, from 10                     |
 | `20` (any value) | only down, from 20: the range holds it |
 
+The first three on a wave from -8 to 8
+([`examples/graph-baseline.js`](examples/graph-baseline.js) has a realistic
+case for each):
+
+![The same wave with baseline 0 (split), 'min' (bars up) and 'max' (bars down), side by side](assets/baseline.svg)
+
+<details>
+<summary><sub>The output above as plain text</sub></summary>
+
+<!-- output:baseline -->
+
+```text
+  info                   |   info                   |   info
+baseline: 0            8 | baseline: 'min'        8 | baseline: 'max'        8
+│   ▄▆██▆▄             │ | │   ▄▆██▆▄             │ | │███▀▔  ▔▀█████████████│
+│ ▄████████▄           │ | │ ▄████████▄           │ | │█▀        ▀███████████│
+│            ▀████████▀│ | │████████████▄        ▄│ | │            ▀████████▀│
+│              ▀▀██▀▀  │ | │██████████████▄▂  ▂▄██│ | │              ▀▀██▀▀  │
+average: 0            -8 | average: 0            -8 | average: 0            -8
+baseline: 0              | min: -8                  | min: -8
+min: -8                  | max: 8                   | max: 8
+max: 8                   |                          |
+```
+
+<!-- /output -->
+
+<sub><i>Bars and frames may not line up in this text if your font lacks the block characters; the image shows the real alignment.</i></sub>
+
+</details>
+
+---
+
 ```ts
 logger.infoGraph(temperatures, {
   title: 'Temperature',
@@ -469,6 +537,8 @@ ignored)` if the plugin has none. A `max` below a numeric baseline is
 `columnsPlugin()` lays out messages and graphs side by side. Each log is a
 cell of a grid; `column()` picks the column the next logs go to:
 
+<!-- code:columns -->
+
 ```ts
 const logger = new Logger({ timestamp: 'HH:mm:ss' }) // short, for narrow columns
   .use(messagePlugin())
@@ -488,6 +558,8 @@ for (const column of [0, 1]) {
 logger.endColumns();
 ```
 
+<!-- /code -->
+
 ![Two columns side by side: wrapped messages and graphs, call for call](assets/columns.svg)
 
 <details>
@@ -608,20 +680,31 @@ collectors, and becomes the default kind. Use it **instead of**
 one output style (e.g. JSON in production, `messagePlugin` in development).
 If both set the default kind, the last one used wins:
 
+<!-- code:json -->
+
 ```ts
 import { Logger, jsonPlugin } from '@mmutils/logger';
 
 const logger = new Logger({ plugins: [jsonPlugin()] });
+const err = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:5432'), {
+  code: 'ECONNREFUSED',
+});
 
 logger.info({ msg: 'Server started', port: 8080 });
 logger.error({ msg: 'Query failed', err });
 ```
 
-```
+<!-- /code -->
+
+<!-- output:json -->
+
+```text
 {"id":1,"time":"2026-03-16T15:35:00.000Z","type":"info","data":{"msg":"Server started","port":8080}}
-{"id":2,"time":"2026-03-16T15:35:00.004Z","type":"error","data":{"msg":"Query failed","err":{"name":"Error","message":"connect ECONNREFUSED 127.0.0.1:5432","stack":"Error: connect ECONNREFUSED 127.0.0.1:5432\n    at …","code":"ECONNREFUSED"}}}
+{"id":2,"time":"2026-03-16T15:35:00.000Z","type":"error","data":{"msg":"Query failed","err":{"name":"Error","message":"connect ECONNREFUSED 127.0.0.1:5432","stack":"Error: connect ECONNREFUSED 127.0.0.1:5432\n    at main (file:///app/server.js:12:16)","code":"ECONNREFUSED"}}}
 ```
 
+<!-- /output -->
+
 ```ts
 jsonPlugin({
   kind: 'json', // kind written by the plugin
@@ -761,7 +844,32 @@ plugins use:
 The level colors are the terminal's 16 basic colors, so they follow its
 theme: red for `fatal` (its badge is white on red), bright red for `error`,
 yellow for `warning`, blue for `info`, magenta for `debug`, cyan for
-`trace`, gray for `verbose`.
+`trace`, gray for `verbose`
+([`examples/levels.js`](examples/levels.js),
+[`examples/styles.js`](examples/styles.js)):
+
+![One message per log type, from fatal to verbose, each with its symbol, badge and color](assets/levels.svg)
+
+<details>
+<summary><sub>The output above as plain text</sub></summary>
+
+<!-- output:levels -->
+
+```text
+2026/03/16 15:35:00 [X]   fatal   Out of memory: the process exits now
+2026/03/16 15:35:00 [!]   error   Payment failed: card declined for order 1042
+2026/03/16 15:35:00 /!\  warning  Disk 91% full on /var, cleanup starts at 95%
+2026/03/16 15:35:00 [i]   info    Server listening on http://localhost:8080
+2026/03/16 15:35:00 (?)   debug   Cache miss for user:42, loading from the database
+2026/03/16 15:35:00 /\/   trace   GET /api/orders → 200 in 34 ms
+2026/03/16 15:35:00 ...  verbose  Pool: 3 of 10 connections in use
+```
+
+<!-- /output -->
+
+</details>
+
+---
 
 ### Symbols
 
@@ -879,14 +987,43 @@ Re-declaring an existing logger method in `M` replaces its signature and docs
 in autocomplete. That's how `messagePlugin` changes `info(data: unknown)` to
 `info(message: string)`.
 
+## Examples
+
+Each file in [`examples/`](examples) shows one topic, with comments on what
+to look for in its output. Build first, then run one, or all of them with
+`npm run demo`:
+
+```sh
+npm run build
+node examples/graphs.js
+```
+
+| File                                              | Shows                                                        |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| [`quick-start.js`](examples/quick-start.js)       | The quick start above                                        |
+| [`levels.js`](examples/levels.js)                 | The seven log types, filtering with `level`                  |
+| [`messages.js`](examples/messages.js)             | Text, objects, arrays, errors, values JSON can't represent   |
+| [`timestamps.js`](examples/timestamps.js)         | Patterns, UTC, the precise clock, elapsed time, a fixed time |
+| [`graphs.js`](examples/graphs.js)                 | Size, `aggregate`, axis labels, statistics                   |
+| [`graph-baseline.js`](examples/graph-baseline.js) | `baseline`, `min` and `max` on realistic data                |
+| [`columns.js`](examples/columns.js)               | Call for call, wrap modes, graph widths, `row(n)`            |
+| [`live.js`](examples/live.js)                     | A status board redrawn in place (run it in a terminal)       |
+| [`json.js`](examples/json.js)                     | JSON lines, time formats, limits, an audit kind              |
+| [`safety.js`](examples/safety.js)                 | Sanitizing, output limits, data that can't be read           |
+| [`styles.js`](examples/styles.js)                 | Level colors, symbols, overrides, `useStyles: false`         |
+| [`custom-plugin.js`](examples/custom-plugin.js)   | A new kind with a method, a transformer                      |
+
+The images in this README are drawn from the same files
+(`npm run images`), so they show what the examples print.
+
 ## Development
 
 ```sh
 npm install
 npm run check   # format, lint, typecheck, tests
 npm run build   # dist/esm, dist/cjs, dist/types
-npm run demo    # feature tour (after build)
-npm run images  # README images in assets/ and their text, from real output (after build)
+npm run demo    # every example, one after the other (after build)
+npm run images  # README images, their text and code, from examples/ (after build)
 ```
 
 ## AI use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmutils/logger",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Plugin-extensible TypeScript logger: a transformer pipeline, baked ANSI styles, styled messages, terminal bar graphs, side-by-side columns and JSON lines.",
   "keywords": [
     "logger",