@mmutils/logger 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,1039 @@
-# Temporary Holding Version
+# @mmutils/logger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, plugin-extensible TypeScript logger. Every log is a plain object that
+flows through a pipeline of transformers and template maps to an output.
+Plugins add behaviour, styles and fully typed methods, so the core stays tiny
+and you only pay for what you use.
+
+![Quick start output: a message, an object, an error and a bar graph, in color](assets/quick-start.svg)
+
+<details>
+<summary><sub>The output above as plain text</sub></summary>
+
+<!-- output:quick-start -->
+
+```text
+2026/03/16 15:35:00 [i]   info    Server started
+2026/03/16 15:35:00 /!\  warning
+user: "alice"
+retries: 3
+2026/03/16 15:35:00 [!]   error
+Error: Connection lost
+    at main (file:///app/server.js:12:16)
+2026/03/16 15:35:00 [i]   info
+CPU                      21.00 %
+│               █████          │
+│          ▁▁▁▁▁█████▁▁▁▁▁     │
+│▁▁▁▁▁▃▃▃▃▃███████████████▃▃▃▃▃│
+average: 7.33 %           0.00 %
+min: 1.00 %
+max: 21.00 %
+```
+
+<!-- /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>
+
+## Features
+
+- **Styled messages**: a colored badge per level; text, objects, arrays and
+  errors laid out to read at a glance, in the terminal's 16 basic colors, so
+  they follow its theme.
+- **Bar graphs in the terminal**: one method per level (`infoGraph`, …),
+  average, min and max, time axis labels (`0ms … 2s 25ms`), bars split at a
+  baseline for negative values, and `aggregate: 'max'` to keep spikes
+  visible.
+- **Columns**: messages and graphs side by side, call for call, with
+  wrapping per kind and a live mode that redraws cells in place (progress,
+  status boards).
+- **JSON lines** (NDJSON) for log files and collectors: errors keep their
+  message, stack and properties, times are ISO or epoch, with nanoseconds
+  from the precise clock.
+- **Timestamps** from dayjs-style patterns (`HH:mm:ss.SSS`), compiled once,
+  without `Intl`, and a precise clock with nanoseconds for benchmarks and
+  tracing.
+- **Plugin based**: each of the above is a plugin, so you only add what you
+  use, or write your own with typed methods and styles. No global
+  configuration: every logger has its own.
+- **Typed, and checked at runtime**: plugin methods and re-declared
+  signatures show up in autocomplete, with their docs; levels that come
+  from configuration as strings are checked too (`'warn'` throws instead of
+  turning every log off).
+- **Fast by design**: styles are baked to escape-code strings once, the
+  timestamp text is cached per second, filtered logs return in a few
+  nanoseconds. See the [benchmarks](bench/README.md).
+- **Safe with any data**: logged text can't send terminal escape sequences,
+  output size is limited, and logging never throws because of the data.
+- **ESM and CommonJS**, with type declarations. Two tiny runtime dependencies.
+
+## Install
+
+```sh
+npm install @mmutils/logger
+```
+
+Requires Node.js 20 or newer.
+
+## Quick start
+
+<!-- code:quick-start -->
+
+```ts
+import { Logger, messagePlugin, graphPlugin } from '@mmutils/logger';
+
+const logger = new Logger({
+  level: 'debug',
+  plugins: [messagePlugin(), graphPlugin()],
+});
+
+logger.info('Server started');
+logger.warning({ user: 'alice', retries: 3 });
+logger.error(new Error('Connection lost'));
+logger.infoGraph([1, 3, 8, 21, 8, 3], { title: 'CPU', unit: '%' });
+```
+
+<!-- /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());
+```
+
+## Without plugins
+
+The core logger outputs the log entry object itself:
+
+```ts
+new Logger().info([1, 2, 3, 4]);
+// { id: 1, timestamp: '2026/03/16 15:35:00', type: 'info', kind: 'default', data: [1, 2, 3, 4] }
+```
+
+Every `log(type, data, kind)` call:
+
+1. checks the type against `level`; filtered logs return before anything is
+   created;
+2. creates the entry `{ id, timestamp, type, kind, data }` (no `timestamp`
+   with `timestamp: false`);
+3. runs every function in `transformers`. The first is
+   `templateTransformer`, which passes each entry property through the
+   template map of the entry's kind (`templateMaps[kind]`);
+4. hands the result to the output of the kind, or to the default `output`.
+
+Plugins hook into steps 3 and 4, and so can you:
+
+| Member                          | Description                                                    |
+| ------------------------------- | -------------------------------------------------------------- |
+| `use(plugin)`                   | Registers a plugin; returns the logger typed with its methods. |
+| `hasPlugin(name)`               | Whether a plugin with that name is used.                       |
+| `addTransformer(fn, position?)` | Inserts a pipeline step, at the end by default.                |
+| `removeTransformer(fn)`         | Removes a step; `true` if it was found.                        |
+| `replaceTransformer(old, fn)`   | Replaces a step in place; `true` if it was found.              |
+| `addTemplateMap(kind, map)`     | Adds template functions for a kind, merged with existing ones. |
+| `setOutput(kind, output)`       | Sets the output of a kind.                                     |
+| `getOutput(kind)`               | The output of a kind, or the default output.                   |
+| `addStyles(sheet)`              | Adds a style sheet and rebakes the styles, see Styles.         |
+| `getStyles(type)`               | The baked styles of a log type.                                |
+| `level`, `defaultKind`          | Can be changed at any time.                                    |
+| `transformers`, `templateMaps`  | The pipeline, readable and mutable.                            |
+
+### Options
+
+| Option        | Default                         | Description                                                                            |
+| ------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
+| `level`       | `'info'`                        | Minimum level: `silent` `fatal` `error` `warning` `info` `debug` `trace` `verbose`.    |
+| `plugins`     | `[]`                            | Plugins to use, in order. Their methods are typed.                                     |
+| `timestamp`   | `'YYYY/MM/DD HH:mm:ss'` (local) | A pattern, `{ format?, utc? }`, `(time, timeNs) => string` or `false`. See Timestamps. |
+| `clock`       | `'wall'`                        | `'wall'` (`Date.now()`), `'precise'` (nanoseconds) or `() => epochMs`. See Timestamps. |
+| `useStyles`   | `true`                          | `false` bakes every style to an empty string.                                          |
+| `output`      | `console.log`                   | Output for kinds without a plugin output.                                              |
+| `defaultKind` | `'default'`                     | Kind of logs without an explicit kind.                                                 |
+
+Log methods: `fatal`, `error`, `warning`, `info`, `debug`, `trace`, `verbose`,
+and `log(type, data, kind?)`. `logger.level` can be changed at any time.
+Levels and types are checked at runtime too, since levels often come from
+configuration or environment variables as plain strings: an unknown level
+(e.g. `'warn'`) throws a `RangeError` instead of silently turning off all
+logs, and an unknown type (or `'silent'`, a level only) throws a
+`TypeError` from `log`.
+
+### Timestamps
+
+The timestamp is when `log` was called. It's a dayjs-style pattern, compiled
+once when the logger is created:
+
+```ts
+new Logger(); // 2026/03/16 15:35:00 (DEFAULT_TIMESTAMP_FORMAT, local time)
+new Logger({ timestamp: 'HH:mm:ss.SSS' }); // 15:35:00.042
+new Logger({ timestamp: { format: 'YYYY-MM-DD[T]HH:mm:ss[Z]', utc: true } });
+new Logger({ timestamp: 'h:mm:ss A' }); // 3:35:00 PM
+new Logger({ clock: 'precise', timestamp: 'ss.SSSSSSSSS EEE' }); // 00.042137508 +12.345678ms
+new Logger({ timestamp: (time, timeNs) => myFormat(time) }); // any formatter
+new Logger({ timestamp: false }); // no timestamp, the clock isn't read
+```
+
+| Token                      | Output                                                   |
+| -------------------------- | -------------------------------------------------------- |
+| `YYYY` `YY`                | `2026` `26`                                              |
+| `MMMM` `MMM` `MM` `M`      | `March` `Mar` `03` `3`                                   |
+| `DD` `D`, `dddd` `ddd`     | `16` `16`, `Monday` `Mon`                                |
+| `HH` `H`                   | `15` `15` (24 hours)                                     |
+| `hh` `h` `A` `a`           | `03` `3` `PM` `pm` (12 hours)                            |
+| `mm` `m`, `ss` `s`         | minutes, seconds                                         |
+| `SSS` `SSSSSS` `SSSSSSSSS` | milliseconds, microseconds, nanoseconds                  |
+| `Z` `ZZ`                   | `+02:00` `+0200`                                         |
+| `E`                        | elapsed since the logger was created: `+1s 32ms 400µs`   |
+| `EEE`                      | elapsed in milliseconds: `+1032.400123ms`                |
+| `[text]`                   | `text` as is (other letters may be tokens: use brackets) |
+
+**Clocks.** `'wall'` (default) is `Date.now()`: the system's wall time, in
+milliseconds. `'precise'` is `process.hrtime` anchored to `Date.now()` when
+the logger is created: exact nanoseconds and monotonic, for benchmarks and
+tracing; like any monotonic clock it can drift from wall time on
+long-running processes (NTP corrections, sleep). A function returning epoch
+milliseconds replaces the clock, e.g. a fixed time in tests. Durations you
+measure yourself belong in the data (`{ took: 300 }`), not in the timestamp.
+
+**Performance.** Text that changes at most once per second is built with
+`Date` getters (no `Intl`) and cached; a log pays the clock read (about
+70 ns), a comparison, and its fraction tokens. `E` costs about 1 µs per log
+(`formatHighResTime`), `EEE` about 0.25 µs. Change the default pattern in one
+place: `DEFAULT_TIMESTAMP_FORMAT`.
+
+## Message plugin
+
+`messagePlugin()` renders logs as styled text and becomes the default kind, so
+every `logger.info(...)` is a message. Text stays on the header line; objects,
+arrays and errors start on the next line, one property (or stack frame) per
+line.
+
+```ts
+messagePlugin({
+  showId: false, // show #id before the date
+  symbol: DEFAULT_SYMBOLS, // per type in front of the badge, see Symbols
+  kind: 'message', // kind rendered by the plugin
+  setAsDefault: true, // make `kind` the logger's default kind
+  sanitize: 'safe', // control characters of logged text, see Sanitize
+  limits: { items: 100, stringLength: 10_000 }, // output size, see Limits
+  styles: {}, // style overrides, see Styles
+  write: console.log, // string destination
+});
+```
+
+### Limits
+
+Like `util.inspect`, the message plugin caps what a single log prints, so
+logging a large buffer, array or string can't block the process or flood
+the output:
+
+- `items` (default `100`): array, buffer and typed array elements, object
+  keys, map and set entries and stack frames. Buffers and typed arrays print
+  on one line: `<Buffer 68 65 6c … 1048573 more bytes>`.
+- `stringLength` (default `10_000`): characters of a message, key, error
+  message or value. Text is cut before it is sanitized; string values are
+  cut before JSON encoding.
+
+What was left out is noted, e.g. `… 999900 more items`. Nested objects are
+still serialized by the native `JSON.stringify` before their text is cut.
+`Infinity` turns a limit off:
+
+```ts
+messagePlugin({ limits: { items: Infinity, stringLength: Infinity } });
+```
+
+The graph plugin takes the same `items` and `stringLength` in its `limits`,
+for data that is not a graph.
+
+### Sanitize
+
+By default, logged text (strings, object keys and values, errors, graph
+titles and labels) can't send terminal escape sequences (cursor moves, screen
+clears, window titles, hyperlinks, clipboard writes) or start a line that
+looks like a log header. `sanitize` is available on both bundled plugins:
+
+| `sanitize`         | Terminal sequences | Colors (`\x1B[...m`) | Newlines                    |
+| ------------------ | ------------------ | -------------------- | --------------------------- |
+| `'safe'` (default) | `\xHH`             | kept, then a reset   | continuation lines indented |
+| `'strict'`         | `\xHH`             | `\xHH`               | `\x0A`, one line per log    |
+| `'none'`           | kept               | kept                 | kept, only for trusted text |
+| custom rules       | `\xHH`             | `colors: 'keep'`     | `newlines: 'indent'`        |
+|                    |                    | or `'escape'`        | or `'keep'` or `'escape'`   |
+
+```ts
+messagePlugin({ sanitize: { colors: 'escape', newlines: 'keep' } });
+```
+
+Single line text (object keys, stack frames, graph titles and labels) always
+has its newlines escaped. Clean text costs one regex scan and no allocation;
+`'none'` costs nothing.
+
+## Graph plugin
+
+`graphPlugin()` draws bar graphs and adds one method per level: `fatalGraph`,
+`errorGraph`, `warningGraph`, `infoGraph`, `debugGraph`, `traceGraph`,
+`verboseGraph`. Settings can be set on the plugin and overridden per graph.
+
+```ts
+logger.infoGraph(values, {
+  cols: 30, // bars; the frame adds 2, so 32 terminal columns
+  // width: 32, // or the total width, frame included (not with cols)
+  rows: 3, // bar rows
+  title: 'CPU',
+  unit: '%', // appended to values
+  precision: 2,
+  max: 100, // top, default: from the values, see below
+  min: 0, // bottom, default: from the values
+  baseline: 0, // where bars start: a value, 'min' or 'max', see below
+  aggregate: 'average', // 'average' | 'max' | 'min', see below
+  showAverage: true,
+  showMin: true,
+  showMax: true,
+  axis: { start: 0, end: 1032.4, unit: 'ms' }, // optional axis row
+});
+```
+
+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>
+<summary><sub>The output above as plain text</sub></summary>
+
+<!-- output:graph -->
+
+```text
+2026/03/16 15:35:00 [i]   info
+Latency                   370 ms
+│  ▇   ▇    ▃    ▆   █    ▃    │
+│▃▄█▅▅▄█▃▂  █  ▁▂█▄▅▅█▄▃▂▁█    │
+│████████████▇█████████████▇▇▇█│
+0ms                      1s 32ms
+average: 154 ms             0 ms
+min: 105 ms
+max: 370 ms
+2026/03/16 15:35:00 /!\  warning
+Queue                       9.00
+│       ▁▁▃▃▄▆▆██▆▆▄▃▃▁▁       │
+│▂▂▄▄▅▇▇████████████████▇▇▅▄▄▂▂│
+Mon                          Fri
+average: 4.76               0.00
+min: 1.00
+max: 9.00
+2026/03/16 15:35:00 [i]   info
+Temperature              25.8 °C
+│  ▂▃▆▇██▆▄▁                   │
+│▄▄█████████▄▃             ▁▁▁▁│
+│             ▀▀████████▀▔▔    │
+│               ▔▔▀▀▀▀▔        │
+Mar 2                     Mar 15
+average: 20.4 °C         15.4 °C
+baseline: 20.0 °C
+min: 15.4 °C
+max: 25.8 °C
+```
+
+<!-- /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>
+
+---
+
+The plugin takes the same settings, as defaults for all its graphs, plus:
+
+```ts
+graphPlugin({
+  // cols, width, rows, title, unit, … as above
+  limits: { cols: 500, rows: 50, precision: 20 }, // see below
+  kind: 'graph', // kind rendered by the plugin
+  showId: false, // show #id before the date
+  symbol: DEFAULT_SYMBOLS, // per type in front of the badge, see Symbols
+  sanitize: 'safe', // see Sanitize
+  styles: {}, // style overrides, see Styles
+  write: console.log, // string destination
+});
+```
+
+Defaults: `cols: 30`, `rows: 3`, `precision: 2`, `aggregate: 'average'`,
+`baseline: 0`, empty `title` and `unit`, all statistics shown, no `max`,
+`min` and `axis`.
+Data that isn't an array of numbers, e.g.
+`logger.log('info', 'text', 'graph')`, is printed as text, limited like
+messages (`limits.items`, `limits.stringLength`).
+
+**`cols` or `width`.** `cols` is the resolution: the number of bars values are
+scaled to, like `rows` for the height. The `│` frame adds 2 characters, so
+`cols: 64` takes 66 terminal columns. `width` sets the space instead:
+`width: 64` draws 62 bars and every row of the graph is exactly 64 terminal
+columns wide, e.g. to fit a layout column. Wide characters in titles and
+labels (CJK, most emoji) count as two columns, as in `columnsPlugin`. Set one
+of them on the plugin (both throw); per graph, `width` wins.
+
+**Statistics** (average, min, max) and the default top and bottom are
+computed from your original values, so they never depend on the graph width.
+The top value is shown on the title row, the bottom value on the average
+row.
+
+**`aggregate`** decides how values sharing a column are drawn: `'average'` for
+a smooth trend, `'max'` to keep spikes visible (latency, errors), `'min'` to
+keep dips visible.
+
+**`baseline`** is where the bars start: they grow up to values above it and
+down to values below it, in the level's color. It is a value (`0` by
+default), `'min'` (the bottom of the graph) or `'max'` (the top). For values
+from -10 to 10:
+
+| `baseline`       | Bars                                   |
+| ---------------- | -------------------------------------- |
+| `0` (default)    | split at 0: up above it, down below it |
+| `'min'`          | only up, from -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',
+  unit: '°C',
+  rows: 4, // a split graph needs 2 or more rows to show both sides
+  baseline: 20, // warmer days grow up, colder days down
+});
+```
+
+- A value is always in the range, so values from 80 to 85 draw bars from 0
+  and keep their proportions. Use it for values with a sign or a target:
+  profit and loss, a temperature setpoint, latency against a budget.
+- `'min'` zooms in on values far from zero, e.g. a heap between 480 and
+  515 MB; the smallest value sits on the bottom line. `'max'` hangs every
+  bar from the top, e.g. how far a battery has drained.
+- A split graph places the baseline in proportion to the range, at the row
+  boundary that gives the bars the most room. Both sides share one scale,
+  so equal distances from the baseline draw equal bars, and a `baseline`
+  row follows the average.
+- A side gets rows only if its longest bar draws at least an eighth of a
+  row: -0.01 next to 100 sits on the baseline instead of taking a row.
+- Bars growing down end in the nearest upper block: `▔` (an eighth of a
+  row), `▀` (a half) or `█`, so their tips are coarser than those of bars
+  growing up. These are the only upper blocks every terminal and font
+  draws; the finer ones (`🮂 🮃 🮄 🮅 🮆`) are missing from many.
+- With `aggregate: 'average'`, a column holding values on both sides
+  averages toward the baseline; use `'max'` or `'min'` to keep one side's
+  extremes.
+
+**`max` and `min`** fix the top and the bottom instead of taking them from
+the values, e.g. to draw graphs on one scale. Values beyond them draw full
+bars, or nothing on a side where no bars grow (above a `'max'` baseline,
+below a `'min'` one). A numeric `baseline` must be between them; the
+default `0` moves inside them, so `min: 480` alone starts the bars at 480.
+
+**`axis`** adds a row under the bars. Strings are shown as given, numbers as
+plain numbers, or as time when `unit` is set (`'h' 'm' 's' 'ms' 'µs' 'ns'`,
+formatted by [`@mmutils/time`](https://www.npmjs.com/package/@mmutils/time)):
+
+```ts
+{ start: 'Mon', end: 'Fri' }                  // Mon            Fri
+{ start: 500, end: 1_000_500, unit: 'ns' }    // 500ns    1ms 500ns
+{ start: 0, end: 1032.4, unit: 'ms', capTo: 1 } // 0ms       1s 32ms
+```
+
+A zero label takes the smallest unit of the other label, so both show the
+same precision. `capTo` is that precision: a unit, or the number of units
+below the largest one (default `2`: `1s 32ms 400µs`).
+
+**`limits`** caps the size settings, because output grows with
+`cols × rows`. Plugin options above the limits throw when the plugin is
+created. Per-graph settings are clamped and a dim note is printed under the
+graph, e.g. `(limited: cols 100000 → 500)`. `width` is limited to
+`limits.cols + 2`. The limits are plugin options only, so logged data can't
+raise them:
+
+```ts
+graphPlugin({ limits: { cols: 500, rows: 50, precision: 20 } }); // defaults
+```
+
+Per-graph settings are treated like logged data, so a graph never throws
+because of them:
+
+- `title`, `unit` and string axis labels are cut to `limits.stringLength`
+  (default 10,000), like message text. Other values are described
+  (`5`, `{"a":1}`), and `null` gives an empty label.
+- An invalid `baseline`, `max` or `min` falls back to the plugin's, with a
+  dim note: `(limited: baseline NaN → min)`, or `(limited: max "x"
+ignored)` if the plugin has none. A `max` below a numeric baseline is
+  raised to it and a `min` above it lowered to it, also when the plugin set
+  them: `(limited: max 100 → 150)`; without a numeric baseline, a `min`
+  above `max` is lowered to it. On the plugin, all of these throw.
+- Settings that can't be read (a throwing getter, a revoked proxy) give the
+  graph with the plugin's settings and a dim note, e.g.
+  `(settings unreadable: Error: …)`.
+
+## Columns plugin
+
+`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())
+  .use(graphPlugin({ width: 40, rows: 2 })) // graphs exactly as wide as a column
+  .use(columnsPlugin({ columns: 2, width: 40 }));
+
+for (const column of [0, 1]) {
+  logger.column(column);
+  logger.info(
+    column === 0 ?
+      'call for call: this message wraps at the column width'
+    : 'same row'
+  );
+  logger.infoGraph(values);
+  logger.info('next row');
+}
+logger.endColumns();
+```
+
+<!-- /code -->
+
+![Two columns side by side: wrapped messages and graphs, call for call](assets/columns.svg)
+
+<details>
+<summary><sub>The output above as plain text</sub></summary>
+
+<!-- output:columns -->
+
+```text
+15:35:00 [i]   info    call for call: th | 15:35:00 [i]   info    same row
+is message wraps at the column width     |
+15:35:00 [i]   info                      | 15:35:00 [i]   info
+                                    9.00 |                                     9.00
+│         ▁▁▂▃▄▄▅▆▆██▆▆▅▄▄▃▂▁▁         │ | │         ▁▁▂▃▄▄▅▆▆██▆▆▅▄▄▃▂▁▁         │
+│▂▂▃▄▄▅▆▇▇████████████████████▇▇▆▅▄▄▃▂▂│ | │▂▂▃▄▄▅▆▇▇████████████████████▇▇▆▅▄▄▃▂▂│
+average: 4.76                       0.00 | average: 4.76                       0.00
+min: 1.00                                | min: 1.00
+max: 9.00                                | max: 9.00
+15:35:00 [i]   info    next row          | 15:35:00 [i]   info    next row
+```
+
+<!-- /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>
+
+---
+
+- **Call for call.** The n-th log of each column shares a row. A row is as
+  tall as its tallest cell (a wrapped message, an object, an error, a
+  graph); shorter cells get blank lines, so the next calls start on the same
+  line.
+- **Fixed width.** Every line is exactly `width` terminal columns, padded
+  with spaces except in the last column. Colors are closed before the frame
+  and reopened on the next line, East Asian wide characters and most emoji
+  count as two columns (emoji sequences such as flags are approximate), tabs
+  become spaces. Other control characters are shown as `\xHH`, even in text
+  logged with `sanitize: 'none'`: carriage returns, cursor moves and screen
+  clears can't be laid out.
+- **Wrapping, per kind.** `wrap` decides what happens to longer lines:
+  `'hard'` wraps at exactly the width, even mid-word; `'word'` wraps at the
+  last space that fits (longer words wrap hard); `'truncate'` cuts the line
+  with a dim `…` in the last column. The default is
+  `{ '*': 'hard', graph: 'truncate' }`: a graph wider than its column is cut,
+  a visible hint to size it with `graphPlugin({ width })`, instead of
+  leaking its bars into the next lines.
+
+  ```ts
+  columnsPlugin({ wrap: 'word' }); // all kinds, graphs stay cut
+  columnsPlugin({ wrap: { message: 'word', '*': 'truncate' } });
+  columnsPlugin({ kinds: ['message', 'cpu'], wrap: { cpu: 'truncate' } }); // graphPlugin({ kind: 'cpu' })
+  ```
+
+  Kinds of any plugin are set by their kind name; a mode on its own sets
+  `'*'`. `indent: 2` starts lines created by wrapping with 2 spaces, so a
+  continuation doesn't look like a new log; the cell's own lines (object
+  keys, stack frames, graph rows) are not indented. Lines that fit cost the
+  same in every mode; word wrap adds about 15% to a wrapped line.
+
+- **Moving around.** `column()` without an index moves to the next column;
+  after the last it writes the grid and starts a new one. Each column
+  remembers its own next row, so switching back continues where it stopped.
+  `row(n)` sends the next log to row `n` of the active column, replacing
+  that cell; `row()` leaves the cell at the cursor empty. A row is a row of
+  cells, not a terminal line.
+- **Streaming.** A row is written as soon as every column has moved past it,
+  so memory stays small. A column that stops logging holds back at most
+  1,000 rows: older rows are then written as they are, their empty cells
+  blank. A log for a row that was already written goes to the column's next
+  free row. `endColumns()` writes the rest, empty cells
+  blank, and returns to normal output.
+- **Live.** With `live: true` every log redraws the rows that can still
+  change, so the grid fills on screen as the calls come in and `row(n)`
+  updates a cell in place (progress, status boards). It moves the terminal
+  cursor up over its own lines, so only rows still on the screen can change;
+  older rows stay as they are. Logs of other kinds (a second message kind,
+  JSON lines) leave the drawn rows first; writes the logger doesn't see
+  (`console.log`, `stderr`) would be overwritten, and so would the screen
+  after a terminal resize. A `write` that logs to the same logger throws:
+  it would draw over the lines being drawn. Without a terminal (piped
+  or redirected output) or when the grid is wider than the terminal, it
+  falls back to streaming.
+
+```ts
+columnsPlugin({
+  columns: 2, // 1 to 100
+  width: 40, // per column, frame excluded; default: the terminal width
+  // (80 when unknown) split evenly, read when the plugin is created
+  frame: ' | ', // text between columns, no control characters
+  frameStyle: 'textDim', // style name of the frame
+  kinds: ['message', 'graph'], // kinds laid out in columns
+  wrap: { '*': 'hard', graph: 'truncate' }, // DEFAULT_COLUMNS_WRAP, see above
+  indent: 0, // spaces before lines created by wrapping
+  live: false, // redraw the rows on screen, see above
+  write: console.log, // line destination
+});
+```
+
+Use it after the plugins that render its kinds. Columns are a layout for
+text kinds: JSON lines are never laid out, and `column()` throws when no
+plugin renders the kinds. Logs filtered by level are not cells. Outside
+`column()` … `endColumns()` the logger is not slowed down: the plugin swaps
+the kinds' outputs only while a grid is open (set your own outputs before
+or after, not during). Buffered rows are lost if the process exits before
+`endColumns()`.
+
+Limits keep one log from blocking or crashing the process, since a row's
+output is its height times the grid's width: the grid (columns, widths and
+frames) is at most 10,000 terminal columns wide (larger options throw), and
+a cell at most 1,000 lines tall, the last one replaced by a dim
+`… cut at 1000 lines`.
+
+## JSON plugin
+
+`jsonPlugin()` writes one JSON object per log (NDJSON), for log files and
+collectors, and becomes the default kind. Use it **instead of**
+`messagePlugin`, not next to it: both render the whole log, and a logger has
+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.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
+  setAsDefault: true, // make `kind` the logger's default kind
+  time: 'iso', // 'iso' | 'epoch' | false
+  limits: { items: 100, stringLength: 10_000 }, // output size, see Limits
+  escapeControls: false, // escape DEL and C1 controls too
+  writeKind: false, // write "kind" after "type"
+  write: console.log, // line destination
+});
+```
+
+**Line shape.** The entry's properties in order: `id`, `time`, `type`,
+`data`, then any property added by your transformers. `kind` is left out by
+default: with one destination per kind it's always the same. Set
+`writeKind: true` when several JSON kinds share a destination (e.g. all logs
+to stdout in a container), so readers can tell them apart:
+
+```ts
+const logger = new Logger()
+  .use(jsonPlugin({ writeKind: true }))
+  .use(jsonPlugin({ kind: 'audit', setAsDefault: false, writeKind: true }));
+logger.info({ msg: 'user deleted' }, 'audit');
+// {"id":1,"time":…,"type":"info","kind":"audit","data":{"msg":"user deleted"}}
+```
+
+`data` is the logged value
+as is (text, object, array, error, …), so its keys can never collide with
+`id`, `time` or `type`. Undefined data is left out, like `JSON.stringify`
+does.
+
+**`time`** comes from the logger's `clock`, read once per log and shared with
+the text timestamp. Its type depends only on the option, never on the clock,
+and the `'precise'` clock's nanoseconds are kept:
+
+| `time`            | `'wall'` clock                      | `'precise'` clock                         |
+| ----------------- | ----------------------------------- | ----------------------------------------- |
+| `'iso'` (default) | `"time":"2026-03-16T15:35:00.042Z"` | `"time":"2026-03-16T15:35:00.042137508Z"` |
+| `'epoch'`         | `"time":1773675300042`              | `"time":1773675300042,"ns":137508`        |
+| `false`           | no time                             | no time                                   |
+
+With the logger's `timestamp: false` lines have no time and the clock isn't
+read.
+
+**Errors** keep what `JSON.stringify` drops (it writes `{}` for an error):
+`name`, `message`, `stack`, own enumerable properties such as `code`, and
+`cause`, up to 5 causes deep (a cause that loops back is `"[Circular]"`).
+This works for errors from other realms (`vm`, workers) too.
+
+Errors are detected **one level deep only**: the logged data itself
+(`logger.error(err)`) and its direct properties (`logger.error({ err })`).
+This is a performance decision: ordinary data costs a single native
+`JSON.stringify`, and finding errors anywhere would mean walking every value
+of every log. Errors nested deeper are left to native JSON, which keeps only
+their own enumerable properties, so their message and stack are lost:
+
+```ts
+logger.error({ err }); // {"err":{"name":"Error","message":"…","stack":"…","code":"ECONNREFUSED"}}
+logger.error({ request: { err } }); // {"request":{"err":{"code":"ECONNREFUSED"}}}
+```
+
+Put the errors you log at the top or under a direct property.
+
+**Values JSON can't represent** are written as JSON that keeps their meaning,
+never as invalid JSON or source code:
+
+| Value                        | Written as                                   |
+| ---------------------------- | -------------------------------------------- |
+| bigint                       | a JSON number with every digit               |
+| function, class              | `"[Function: name]"`, `"[class Name]"`       |
+| symbol                       | `"Symbol(description)"`                      |
+| buffer, typed array          | `"<Buffer 68 69>"`, `"Uint8Array(2) [1, 2]"` |
+| map, set, regular expression | `"Map(1) {\"a\" => 1}"`, `"/x/g"`            |
+| throwing getter              | `"[Getter threw: Error: …]"`                 |
+| circular, revoked proxy      | `"[Unserializable: TypeError: …]"`           |
+
+Logging never throws because of the data, and every line is valid JSON; the
+other properties still render. Errors of `write` propagate.
+
+**`limits`** keep lines bounded and valid JSON, and **keep each value's
+type**, so collectors that map fields by type (e.g. Elasticsearch, which
+rejects a document whose field changes from array to string) accept the
+line:
+
+- strings longer than `stringLength` are cut: `"xxx… 90 more characters"`;
+- arrays and objects with more than `items` elements or keys keep the first
+  `items`, followed by a `"… 3 more items"` element or a
+  `"…": "… 3 more items"` property. This applies to the data and its direct
+  properties (one level deep, like errors); deeper objects are written by
+  native JSON;
+- an array or object whose JSON is longer than `stringLength` is cut
+  structurally: elements or properties are kept while they fit (about
+  `stringLength` characters, plus the note), then the same "more" note. A
+  first element that alone doesn't fit is cut the same way, up to 4 levels
+  deep, then becomes a cut string;
+- an element that can't be serialized becomes a placeholder and the rest
+  keeps its type; a value that contains itself is `"[Circular]"`.
+
+Cutting costs time in proportion to `stringLength`, not to the value, and
+ordinary data never reaches it.
+
+Ordinary data costs one native `JSON.stringify` after a quick check of its
+values; only data with errors, binary data, bigints, functions, long strings
+or arrays is serialized property by property.
+
+**`escapeControls`**: `JSON.stringify` already escapes newlines, ESC and the
+other C0 controls, so logged text can't start a new line or send a terminal
+escape sequence. It writes DEL and C1 controls (`U+007F`–`U+009F`) as they
+are. They're harmless for log collectors, but some terminals act on C1
+controls when lines are shown raw (`cat`, `tail -f`). `escapeControls: true`
+writes them as `\u00XX`: the parsed JSON is the same, at about 1 ns per
+character.
+
+A JSON kind can also live next to messages, e.g. an audit trail:
+
+```ts
+const logger = new Logger()
+  .use(messagePlugin())
+  .use(jsonPlugin({ kind: 'audit', setAsDefault: false, write: toAuditFile }));
+
+logger.info('Server started'); // styled message
+logger.info({ action: 'login', user: 'alice' }, 'audit'); // JSON line
+```
+
+## Styles
+
+Styles are named escape-code strings, baked once per level. The bundled
+plugins use:
+
+| Style           | Default                   | Used for                                           |
+| --------------- | ------------------------- | -------------------------------------------------- |
+| `textDim`       | gray (bright black)       | date, id, symbol, units, axis labels, stack frames |
+| `textNormal`    | terminal default          | object keys, legend labels                         |
+| `textHighlight` | level color, bold         | messages, values, graph title, bars and frame      |
+| `textBadge`     | level color as background | the type badge                                     |
+
+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`
+([`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
+
+The message and graph plugins show a symbol in front of the type badge:
+
+| Type   | `fatal` | `error` | `warning` | `info` | `debug` | `trace` | `verbose` |
+| ------ | ------- | ------- | --------- | ------ | ------- | ------- | --------- |
+| Symbol | `[X]`   | `[!]`   | `/!\`     | `[i]`  | `(?)`   | `/\/`   | `...`     |
+
+They are plain ASCII, which every terminal and font draws, one column per
+character. `symbol` takes symbols per type, merged over these
+(`DEFAULT_SYMBOLS`) and padded with spaces to the widest one plus one, so the
+badges line up. A string is one symbol for every type, used as is; `''` shows
+none:
+
+```ts
+messagePlugin({ symbol: { info: '->', debug: '#' } }); // others stay
+messagePlugin({ symbol: '' }); // no symbols, e.g. in narrow columns
+```
+
+Emoji work too, but some fonts don't have them and terminals measure some of
+them differently (newer emoji such as 🪰, and symbols followed by an emoji
+variation selector such as `⚠️`): a terminal that measures one differently
+from @mmutils/logger shifts that badge by a column.
+
+### Changing styles
+
+Override them per level, or for all levels with `'*'`. Values are strings or
+[`style-escape-codes`](https://www.npmjs.com/package/style-escape-codes)
+chains:
+
+```ts
+import { sec } from 'style-escape-codes';
+
+messagePlugin({
+  styles: {
+    '*': { textDim: sec.dim },
+    error: { textBadge: sec.b.bgRed.fgWhite },
+  },
+});
+```
+
+Within one style sheet, level groups override `'*'`. `reset` is built in.
+A plugin's `styles` are merged into its default sheet, so `'*'` there can't
+replace a style the defaults set per level (`textHighlight`, `textBadge`):
+set those per level, or for all levels in a later sheet.
+
+Style names are shared by all plugins of a logger, and later sheets override
+earlier ones. Each bundled plugin registers the default styles, so overrides
+passed to `messagePlugin` are undone by a `graphPlugin()` used after it. To
+restyle a logger with several plugins, add a sheet after them:
+
+```ts
+const logger = new Logger({ plugins: [messagePlugin(), graphPlugin()] });
+logger.addStyles({ '*': { textDim: sec.dim } }); // all plugins, all levels
+logger.addStyles({ '*': { textBadge: sec.invert } }); // overrides per-level defaults too
+```
+
+`useStyles: false` on the logger bakes every style to an empty string, e.g.
+for log files or `useStyles: !process.env.NO_COLOR`; it costs nothing per
+log.
+
+## Writing a plugin
+
+A plugin is an object. Usually it is returned by a factory that takes the
+plugin's own typed options, so no global configuration is needed.
+
+```ts
+import type { LoggerPlugin, LogType } from '@mmutils/logger';
+
+interface CsvMethods {
+  /** Logs `values` as one CSV row. */
+  csv(values: readonly unknown[], type?: LogType): void;
+}
+
+export const csvPlugin = (): LoggerPlugin<CsvMethods> => ({
+  name: 'csv',
+  templateMaps: {
+    // per-kind templates, applied to each entry property
+    csv: { data: (value) => (value as unknown[]).map(String).join(',') },
+  },
+  outputs: {
+    // per-kind output; ctx.time: time of the log (whole epoch ms), ctx.timeNs:
+    // nanoseconds within it with the precise clock
+    csv: (entry, ctx) =>
+      process.stdout.write(`${ctx.time ?? ''},${entry.type},${entry.data}\n`),
+  },
+  methods: (logger) => ({
+    csv: (values, type = 'info') => logger.log(type, values, 'csv'),
+  }),
+});
+```
+
+A plugin can provide:
+
+- `styles`: style sheets available to all templates.
+- `templateMaps`: functions keyed by entry property, per kind.
+- `transformers`: pipeline steps `(entry, ctx) => entry`, with an optional
+  position. Copy keys from data with a spread (`{ ...entry, ...fields }`),
+  not with `Object.assign` or `entry[key] = value`: those treat a `__proto__`
+  key (e.g. from parsed JSON) as the entry's prototype, whose keys would then
+  be printed.
+- `outputs`: the final destination, per kind.
+- `methods`: returns a plain object of methods added to the logger, typed
+  through `LoggerPlugin<M>`. Class instances are rejected: their prototype
+  methods would not be copied.
+- `defaultKind`: makes the plugin's kind the default.
+
+Registration is atomic: every part is checked first (functions are
+functions, styles convert to strings, methods override nothing, including
+symbol keys), so a plugin that throws leaves the logger unchanged and can be
+fixed and used again.
+
+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    # every example, one after the other (after build)
+npm run images  # README images, their text and code, from examples/ (after build)
+```
+
+## AI use
+
+@mmutils/logger is developed with AI assistance: most of the code, tests,
+benchmarks and documentation was written with AI. The author designs the
+features, makes the decisions and reviews the changes, and every change
+passes the same checks (formatting, lint, strict type checking and tests)
+before it is committed.
+
+## License
+
+[MIT](LICENSE)