@mmutils/logger 0.0.0-stage → 0.1.0

package/dist/cjs/plugins/columns.cjs

@@ -0,0 +1,782 @@
+'use strict';
+
+var text = require('../utils/text.cjs');
+var shared = require('./shared.cjs');
+
+/**
+ * Wrap modes used unless `wrap` overrides them: graphs are cut (a wrapped
+ * graph is unreadable, a cut one shows the width is off), everything else
+ * wraps hard.
+ */
+const DEFAULT_COLUMNS_WRAP = {
+    '*': 'hard',
+    graph: 'truncate',
+};
+const RESET = '\x1b[0m';
+const MAX_COLUMNS = 100;
+const MAX_WIDTH = 10_000;
+const MIN_WIDTH = 2;
+/**
+ * Width of a whole grid, frames included, at most. Output grows with the
+ * grid's width times the lines of a row.
+ */
+const MAX_TOTAL_WIDTH = 10_000;
+/** Lines of one cell at most; the last one becomes `CELL_CUT_NOTE`. */
+const MAX_CELL_LINES = 1000;
+/**
+ * Rows a streaming grid holds at most while waiting for a column: older
+ * rows are written as they are.
+ */
+const MAX_BUFFERED_ROWS = 1000;
+const CELL_CUT_NOTE = `… cut at ${String(MAX_CELL_LINES)} lines`;
+const TAB_SIZE = 8;
+/** Terminal height assumed when it is unknown. */
+const DEFAULT_ROWS = 24;
+/* eslint-disable no-control-regex -- matching control characters is the point */
+const CONTROL = /[\x00-\x1f\x7f-\x9f]/;
+const SGR_AT = /\x1B\[[0-9;:]*m/y;
+/* eslint-enable no-control-regex */
+/**
+ * SGR sequences in effect after `sgr`, replayed at the start of a wrapped
+ * line. A reset clears them.
+ */
+const applySgr = (active, sgr) => {
+    const params = sgr.slice(2, -1);
+    if (params === '' || params === '0')
+        return '';
+    return params.startsWith('0;') ? sgr : active + sgr;
+};
+/**
+ * Ends a wrapped line with a reset if styles are in effect, so they never
+ * reach the padding, the frame or the next column.
+ */
+const closeLine = (text, active) => active === '' ? text : `${text}${RESET}`;
+const SGR_GLOBAL = new RegExp(SGR_AT.source, 'g');
+/**
+ * Builds the wrapped lines of one cell. A single module-level instance:
+ * wrapping is synchronous and never re-entered, so nothing is allocated per
+ * log but the strings.
+ */
+class LineBuilder {
+    out = [];
+    /** Terminal columns of each line in `out`. */
+    widths = [];
+    width = 0;
+    word = false;
+    /** Spaces at the start of lines created by wrapping. */
+    indent = '';
+    /** Lines to produce at most; the rest of the line is skipped. */
+    limit = Infinity;
+    /** SGR sequences in effect, carried from line to line of a cell. */
+    active = '';
+    /** A line was left out because of `limit`. */
+    dropped = false;
+    text = '';
+    used = 0;
+    /** Columns taken before any text: the indent on wrapped lines. */
+    lineStart = 0;
+    /** Last space a word wrap can break at: index in `text`, or -1. */
+    breakAt = -1;
+    breakUsed = 0;
+    breakActive = '';
+    /**
+     * A word wrap broke the line and nothing visible followed yet: spaces
+     * are dropped with the break, also in the next runs.
+     */
+    atBreak = false;
+    resetDropped() {
+        this.dropped = false;
+    }
+    get full() {
+        return this.out.length >= this.limit;
+    }
+    start(out, widths, width, word, indent, limit) {
+        this.out = out;
+        this.widths = widths;
+        this.width = width;
+        this.word = word;
+        this.indent = ' '.repeat(indent);
+        this.limit = limit;
+        this.startLine(false);
+    }
+    /**
+     * @param wrapped A line created by wrapping: starts with the indent,
+     * before the styles in effect, so a background never fills it.
+     */
+    startLine(wrapped) {
+        const indent = wrapped ? this.indent : '';
+        this.text = indent + this.active;
+        this.used = indent.length;
+        this.lineStart = indent.length;
+        this.breakAt = -1;
+        this.atBreak = false;
+    }
+    /**
+     * Ends the line; `wrapped` when the same text continues. A line holding
+     * only what followed a word wrap break (spaces, styles) is left out.
+     */
+    endLine(wrapped = false) {
+        if (this.atBreak) ;
+        else if (this.full)
+            this.dropped = true;
+        else {
+            this.out.push(closeLine(this.text, this.active));
+            this.widths.push(this.used);
+        }
+        this.startLine(wrapped);
+    }
+    /** Plain text: every code unit is one column wide. */
+    addRun(run) {
+        let start = 0;
+        while (!this.full) {
+            if (this.atBreak) {
+                while (run.charCodeAt(start) === 0x20)
+                    start++;
+                if (start === run.length)
+                    return;
+                this.atBreak = false;
+            }
+            const rest = run.length - start;
+            const room = this.width - this.used;
+            if (rest <= room) {
+                if (this.word)
+                    this.markBreak(run, start);
+                this.text += start === 0 ? run : run.slice(start);
+                this.used += rest;
+                return;
+            }
+            if (this.word) {
+                const space = run.lastIndexOf(' ', start + room);
+                // a break that leaves an empty line is no break
+                if (space >= start && (space > start || this.used > this.lineStart)) {
+                    this.text += run.slice(start, space);
+                    this.used += space - start;
+                    this.endLine(true);
+                    this.atBreak = true;
+                    start = space + 1;
+                    continue;
+                }
+                if (this.breakAt >= 0) {
+                    this.splitAtBreak();
+                    continue;
+                }
+            }
+            this.text += run.slice(start, start + room);
+            this.used += room;
+            start += room;
+            this.endLine(true);
+        }
+    }
+    /**
+     * One code point that is not one column wide, or a control. A wide
+     * character that doesn't fit even on a fresh line is placed anyway.
+     */
+    addChar(char, columns) {
+        while (this.used + columns > this.width &&
+            this.used > this.lineStart &&
+            !this.full)
+            if (this.word && this.breakAt >= 0)
+                this.splitAtBreak();
+            else
+                this.endLine(true);
+        // no room next to the indent: this line goes without it
+        if (this.used === this.lineStart && this.used + columns > this.width) {
+            this.text = this.active;
+            this.used = 0;
+            this.lineStart = 0;
+        }
+        this.atBreak = false;
+        this.text += char;
+        this.used += columns;
+    }
+    addTab() {
+        this.atBreak = false;
+        if (this.used === this.width)
+            this.endLine(true);
+        const spaces = Math.min(TAB_SIZE - (this.used % TAB_SIZE), this.width - this.used);
+        this.text += ' '.repeat(spaces);
+        this.used += spaces;
+    }
+    addSgr(sgr) {
+        this.active = applySgr(this.active, sgr);
+        this.text += sgr;
+    }
+    /** Remembers the last space of a run appended whole. */
+    markBreak(run, start) {
+        const space = run.lastIndexOf(' ');
+        if (space < start)
+            return;
+        const used = this.used + space - start;
+        if (used === this.lineStart)
+            return;
+        this.breakAt = this.text.length + space - start;
+        this.breakUsed = used;
+        this.breakActive = this.active;
+    }
+    /** Ends the line at the last space; the text after it starts a new line. */
+    splitAtBreak() {
+        const { text, breakAt, breakActive, indent } = this;
+        if (this.full)
+            this.dropped = true;
+        else {
+            this.out.push(closeLine(text.slice(0, breakAt), breakActive));
+            this.widths.push(this.breakUsed);
+        }
+        this.used = indent.length + this.used - this.breakUsed - 1;
+        this.lineStart = indent.length;
+        this.text = indent + breakActive + text.slice(breakAt + 1);
+        this.breakAt = -1;
+        this.atBreak = this.used === this.lineStart;
+    }
+}
+const builder = new LineBuilder();
+const SPECIAL = new RegExp(text.SLOW_CHARS.source, 'g');
+/**
+ * A control character as `\xHH`, like the `'safe'` sanitizer.
+ */
+const hexEscape = (code) => `\\x${code.toString(16).toUpperCase().padStart(2, '0')}`;
+/**
+ * Feeds one line to the builder: runs of plain text are sliced, only escape
+ * codes, tabs and characters that are not one column wide are handled one
+ * by one. Stops when the builder is full.
+ *
+ * Control characters other than SGR sequences and tabs are shown as `\xHH`,
+ * even in text logged with `sanitize: 'none'`: their effect on the terminal
+ * (carriage returns, cursor moves, screen clears) can't be laid out, and in
+ * live mode they would break the redraw.
+ */
+const feedLine = (line) => {
+    // one scan: a line without special characters is a single run
+    let start = 0;
+    SPECIAL.lastIndex = 0;
+    for (let match = SPECIAL.exec(line); match !== null && !builder.full; match = SPECIAL.exec(line)) {
+        const { index } = match;
+        if (index > start)
+            builder.addRun(line.slice(start, index));
+        const code = line.charCodeAt(index);
+        start = index + 1;
+        if (code === 0x1b) {
+            SGR_AT.lastIndex = index;
+            const sgr = SGR_AT.exec(line);
+            if (sgr === null)
+                builder.addRun('\\x1B');
+            else {
+                builder.addSgr(sgr[0]);
+                start = index + sgr[0].length;
+            }
+        }
+        else if (code === 0x09)
+            builder.addTab();
+        else if (code < 0x20 || (code >= 0x7f && code <= 0x9f))
+            builder.addRun(hexEscape(code));
+        else {
+            const codePoint = line.codePointAt(index) ?? 0;
+            if (codePoint > 0xffff)
+                start = index + 2;
+            builder.addChar(line.slice(index, start), text.charWidth(codePoint));
+        }
+        SPECIAL.lastIndex = start;
+    }
+    if (start < line.length && !builder.full)
+        builder.addRun(line.slice(start));
+};
+/**
+ * Cuts one line at `width` columns with `marker` (one column) in the last
+ * one. Lines that fit are added as they are.
+ */
+const truncateLine = (line, width, out, widths, marker) => {
+    const { active } = builder;
+    const fitted = [];
+    const fittedWidths = [];
+    builder.start(fitted, fittedWidths, width, false, 0, 2);
+    feedLine(line);
+    builder.endLine();
+    if (fitted.length === 1) {
+        out.push(fitted[0] ?? '');
+        widths.push(fittedWidths[0] ?? 0);
+        return;
+    }
+    // too long: again, one column narrower, and the marker
+    builder.active = active;
+    const cut = [];
+    const cutWidths = [];
+    builder.start(cut, cutWidths, width - 1, false, 0, 1);
+    feedLine(line);
+    builder.endLine();
+    const used = cutWidths[0] ?? 0;
+    // the marker in the last column
+    out.push(`${cut[0] ?? ''}${' '.repeat(Math.max(0, width - 1 - used))}${marker}`);
+    widths.push(width);
+    // styles in effect after the whole line, for the cell's next line
+    let after = active;
+    if (line.includes('\x1b'))
+        for (const [sgr] of line.matchAll(SGR_GLOBAL))
+            after = applySgr(after, sgr);
+    builder.active = after;
+};
+/**
+ * Wraps text into lines of at most `width` terminal columns, not padded,
+ * with the columns of each line in `widths`.
+ *
+ * @param maxLines Lines to produce at most.
+ * @returns `true` if lines were left out because of `maxLines`.
+ */
+const wrapLines = (text, width, { mode = 'hard', marker = '…', indent = 0 }, out, widths, maxLines) => {
+    builder.active = '';
+    builder.resetDropped();
+    const truncate = mode === 'truncate';
+    for (const line of text.split('\n')) {
+        if (out.length >= maxLines)
+            return true;
+        builder.start(out, widths, width, mode === 'word', indent, maxLines);
+        if (truncate)
+            truncateLine(line, width, out, widths, marker);
+        else {
+            feedLine(line);
+            builder.endLine();
+            if (builder.dropped)
+                return true;
+        }
+    }
+    return false;
+};
+/**
+ * Splits rendered text into lines of exactly `width` terminal columns, each
+ * padded with spaces. Lines longer than the width are wrapped or cut, see
+ * `WrapMode`. Never splits an SGR sequence, a surrogate pair or a wide
+ * character; styles in effect are closed at the end of each line and
+ * reopened on the next one. Tabs become spaces up to the next multiple of 8.
+ */
+const wrapText = (text, width, options = {}) => {
+    const out = [];
+    const widths = [];
+    wrapLines(text, width, options, out, widths, Infinity);
+    return out.map((line, index) => `${line}${' '.repeat(Math.max(0, width - (widths[index] ?? 0)))}`);
+};
+/**
+ * Text without trailing spaces. A backwards scan: `/ +$/` is quadratic on
+ * lines with many spaces (graph rows), it took 40% of a graph in a column.
+ */
+const trimSpaces = (text) => {
+    let end = text.length;
+    while (end > 0 && text.charCodeAt(end - 1) === 0x20)
+        end--;
+    return end === text.length ? text : text.slice(0, end);
+};
+const rowHeight = (row) => {
+    let height = 1;
+    for (const cell of row)
+        if (cell !== undefined)
+            height = Math.max(height, cell.lines.length);
+    return height;
+};
+/**
+ * Joins rows of cells into terminal lines: each row as tall as its tallest
+ * cell (at least one line), empty cells blank, the frame painted with the
+ * styles of the row's first cell. The last column is not padded.
+ */
+const renderRows = (rows, settings) => {
+    const { columns, width, frame, frameEnd, frameStyle } = settings;
+    const blank = ' '.repeat(width);
+    const lines = [];
+    for (const row of rows) {
+        const { styles } = row.find((cell) => cell !== undefined) ?? {};
+        const style = styles?.[frameStyle] ?? '';
+        const reset = styles?.reset ?? '';
+        const painted = shared.paint(style, frame, reset);
+        const paintedEnd = shared.paint(style, frameEnd, reset);
+        const height = rowHeight(row);
+        for (let index = 0; index < height; index++) {
+            let line = '';
+            for (let column = 0; column < columns; column++) {
+                const cell = row[column];
+                let text = cell?.lines[index];
+                if (column === columns - 1)
+                    text = text === undefined ? '' : trimSpaces(text);
+                else if (text === undefined)
+                    text = blank;
+                else {
+                    const used = cell?.widths[index] ?? width;
+                    if (used < width)
+                        text += blank.slice(0, width - used);
+                }
+                if (column > 0)
+                    line += text === '' ? paintedEnd : painted;
+                line += text;
+            }
+            // a frame of spaces before an empty last column
+            lines.push(trimSpaces(line));
+        }
+    }
+    return lines;
+};
+/**
+ * Cells of one grid. Rows that can no longer change are written and
+ * dropped: `rows[0]` is row `written`.
+ */
+class Grid {
+    settings;
+    live;
+    /** Active column. */
+    active = 0;
+    /** Number of rows written, which can't change any more. */
+    written = 0;
+    /** Rows that can still change. */
+    rows = [];
+    /** Per column, the row the next log goes to. */
+    cursors;
+    /** Live mode: lines drawn for `rows`, redrawn on the next change. */
+    drawn = 0;
+    /** Live mode: `write` is drawing the rows. */
+    drawing = false;
+    constructor(settings, 
+    /** Redraw on every log instead of writing finished rows. */
+    live) {
+        this.settings = settings;
+        this.live = live;
+        this.cursors = Array.from({ length: settings.columns }, () => 0);
+    }
+    /** Number of rows, written or not. */
+    get rowCount() {
+        return this.written + this.rows.length;
+    }
+    /** Puts rendered text in the active column's cell at its cursor. */
+    put(text, styles, kind) {
+        this.assertNotDrawing();
+        const { active, settings } = this;
+        let row = this.cursors[active] ?? 0;
+        if (row < this.written)
+            row = this.firstFree(active);
+        while (this.rowCount <= row)
+            this.rows.push([]);
+        const cells = this.rows[row - this.written] ?? [];
+        const mode = settings.wrap[kind] ?? settings.wrap['*'] ?? 'hard';
+        const marker = mode === 'truncate' ?
+            shared.paint(styles.textDim ?? '', '…', styles.reset ?? '')
+            : '…';
+        const lines = [];
+        const widths = [];
+        const cut = wrapLines(text, settings.width, { mode, marker, indent: settings.indent }, lines, widths, MAX_CELL_LINES);
+        if (cut) {
+            const note = CELL_CUT_NOTE.slice(0, settings.width);
+            lines[MAX_CELL_LINES - 1] = shared.paint(styles.textDim ?? '', note, styles.reset ?? '');
+            widths[MAX_CELL_LINES - 1] = note.length;
+        }
+        cells[active] = { lines, widths, styles };
+        this.cursors[active] = row + 1;
+        if (this.live)
+            this.redraw();
+        else
+            this.writeReady();
+    }
+    /** Writes everything left. Live mode has it on screen already. */
+    end() {
+        if (!this.live && this.rows.length > 0)
+            this.settings.write(renderRows(this.rows, this.settings).join('\n'));
+        this.freeze(this.rows.length);
+    }
+    /** Live mode: leaves what is drawn on screen, before other output. */
+    freezeAll() {
+        if (!this.live)
+            return;
+        this.assertNotDrawing();
+        this.freeze(this.rows.length);
+    }
+    /**
+     * A live redraw can't be interleaved: a `write` that logs to the same
+     * logger would draw over the lines being drawn.
+     */
+    assertNotDrawing() {
+        if (this.drawing)
+            throw new Error('columnsPlugin: write logged to the same logger during a live redraw. Write to another logger or destination.');
+    }
+    firstFree(column) {
+        let index = 0;
+        while (index < this.rows.length && this.rows[index]?.[column] !== undefined)
+            index++;
+        return this.written + index;
+    }
+    freeze(count) {
+        this.rows.splice(0, count);
+        this.written += count;
+        this.drawn = 0;
+    }
+    /** Streaming: writes the rows every column's cursor has passed. */
+    writeReady() {
+        // rows beyond the buffer limit are written with their empty cells blank:
+        // a column that stopped logging can't hold back the others forever
+        const ready = Math.max(Math.min(...this.cursors) - this.written, this.rows.length - MAX_BUFFERED_ROWS);
+        if (ready <= 0)
+            return;
+        const rows = this.rows.splice(0, ready);
+        this.written += rows.length;
+        if (rows.length > 0)
+            this.settings.write(renderRows(rows, this.settings).join('\n'));
+    }
+    /**
+     * Live: moves up over the lines drawn last time, clears to the end of the
+     * screen and draws the rows again. Rows that would not fit on the screen
+     * stay written: the cursor can't reach lines that scrolled off.
+     */
+    redraw() {
+        const lines = renderRows(this.rows, this.settings);
+        const up = this.drawn > 0 ? `\x1b[${String(this.drawn)}F\x1b[J` : '';
+        this.drawing = true;
+        try {
+            this.settings.write(up + lines.join('\n'));
+        }
+        finally {
+            this.drawing = false;
+        }
+        const { rows = DEFAULT_ROWS } = process.stdout;
+        const room = Math.max(1, rows - 1);
+        let drawn = lines.length;
+        let frozen = 0;
+        while (drawn > room && frozen < this.rows.length)
+            drawn -= rowHeight(this.rows[frozen++] ?? []);
+        this.freeze(frozen);
+        this.drawn = drawn;
+    }
+}
+/**
+ * Column mode of one logger: swaps the outputs of the laid out kinds for
+ * one that fills the grid, and puts them back on `endColumns`. Outside
+ * column mode the logger's pipeline is untouched.
+ */
+class Columns {
+    logger;
+    settings;
+    grid;
+    saved = [];
+    /** Live mode: freezes the grid before logs of other kinds. */
+    freezer;
+    constructor(logger, settings) {
+        this.logger = logger;
+        this.settings = settings;
+    }
+    column(index) {
+        const { columns } = this.settings;
+        if (index !== undefined &&
+            !(Number.isInteger(index) && index >= 0 && index < columns))
+            throw new RangeError(`column: index must be an integer from 0 to ${String(columns - 1)}, got ${String(index)}.`);
+        const { grid } = this;
+        if (grid === undefined)
+            this.start().active = index ?? 0;
+        else if (index !== undefined)
+            grid.active = index;
+        else if (grid.active + 1 < columns)
+            grid.active++;
+        else {
+            grid.end();
+            this.grid = new Grid(this.settings, grid.live);
+        }
+    }
+    row(index) {
+        const grid = this.grid ?? this.start();
+        const { active } = grid;
+        if (index === undefined) {
+            grid.cursors[active] = (grid.cursors[active] ?? 0) + 1;
+            return;
+        }
+        if (!(Number.isInteger(index) && index >= 0 && index <= grid.rowCount))
+            throw new RangeError(`row: index must be an integer from 0 to ${String(grid.rowCount)} (the next new row), got ${String(index)}.`);
+        grid.cursors[active] = index;
+    }
+    endColumns() {
+        const { grid } = this;
+        if (grid === undefined)
+            return;
+        try {
+            grid.end();
+        }
+        finally {
+            this.grid = undefined;
+            for (const [kind, output] of this.saved)
+                this.logger.setOutput(kind, output);
+            this.saved = [];
+            if (this.freezer !== undefined) {
+                this.logger.removeTransformer(this.freezer);
+                this.freezer = undefined;
+            }
+        }
+    }
+    start() {
+        const { logger, settings } = this;
+        const { templateMaps } = logger;
+        const kinds = settings.kinds.filter((kind) => templateMaps[kind] !== undefined);
+        if (kinds.length === 0)
+            throw new Error(`columnsPlugin: no plugin renders the kinds ${settings.kinds.map((kind) => `"${kind}"`).join(', ')}. Use messagePlugin or graphPlugin before columnsPlugin, or set kinds.`);
+        const grid = new Grid(settings, this.isLive());
+        this.grid = grid;
+        const cellOutput = (entry, { styles, kind }) => {
+            let text = '';
+            for (const key in entry)
+                text += String(entry[key]);
+            this.grid?.put(text, styles, kind);
+        };
+        for (const kind of kinds) {
+            this.saved.push([kind, logger.getOutput(kind)]);
+            logger.setOutput(kind, cellOutput);
+        }
+        // logs of other kinds, whatever their output, would move the lines a
+        // live redraw moves over: the grid leaves its rows on screen first
+        if (grid.live) {
+            const laidOut = new Set(kinds);
+            this.freezer = (entry, { kind }) => {
+                if (!laidOut.has(kind))
+                    this.grid?.freezeAll();
+                return entry;
+            };
+            logger.addTransformer(this.freezer, 0);
+        }
+        return grid;
+    }
+    /**
+     * Live mode needs a terminal at least as wide as the grid; checked when
+     * column mode starts.
+     */
+    isLive() {
+        const { live, customWrite, columns, width, frame } = this.settings;
+        if (!live)
+            return false;
+        const stdout = process.stdout;
+        if (!customWrite && stdout.isTTY !== true)
+            return false;
+        const total = columns * width + (columns - 1) * text.textWidth(frame);
+        return total <= (stdout.columns ?? Infinity);
+    }
+}
+const assertInteger = (value, name, min, max) => {
+    if (!(typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value >= min &&
+        value <= max))
+        throw new RangeError(`columnsPlugin: ${name} must be an integer from ${String(min)} to ${String(max)}, got ${typeof value === 'number' ? String(value) : typeof value}.`);
+};
+const WRAP_MODES = ['hard', 'word', 'truncate'];
+const assertWrapMode = (mode, name) => {
+    if (!WRAP_MODES.includes(mode))
+        throw new RangeError(`columnsPlugin: ${name} must be 'hard', 'word' or 'truncate', got ${typeof mode === 'string' ? `'${mode}'` : typeof mode}.`);
+};
+/**
+ * Wrap modes by kind: the defaults, then the option. Own keys only, into an
+ * object without prototype, so kinds like `toString` or `__proto__` are
+ * plain names.
+ */
+const resolveWrap = (wrap) => {
+    const modes = Object.assign(Object.create(null), DEFAULT_COLUMNS_WRAP);
+    if (wrap === undefined)
+        return modes;
+    if (typeof wrap === 'string') {
+        assertWrapMode(wrap, 'wrap');
+        modes['*'] = wrap;
+        return modes;
+    }
+    if (typeof wrap !== 'object' || wrap === null || Array.isArray(wrap))
+        throw new TypeError(`columnsPlugin: wrap must be a mode or an object of modes by kind, got ${wrap === null ? 'null'
+            : Array.isArray(wrap) ? 'array'
+                : typeof wrap}.`);
+    for (const kind of Object.keys(wrap)) {
+        const mode = wrap[kind];
+        assertWrapMode(mode, `wrap["${kind}"]`);
+        modes[kind] = mode;
+    }
+    return modes;
+};
+const resolveSettings = (options) => {
+    const { columns = 2, frame = ' | ', frameStyle = 'textDim', kinds = ['message', 'graph'], live = false, write, } = options;
+    assertInteger(columns, 'columns', 1, MAX_COLUMNS);
+    if (typeof frame !== 'string')
+        throw new TypeError(`columnsPlugin: frame must be a string, got ${typeof frame}.`);
+    if (CONTROL.test(frame))
+        throw new RangeError('columnsPlugin: frame must not contain control characters.');
+    if (typeof frameStyle !== 'string')
+        throw new TypeError(`columnsPlugin: frameStyle must be a style name, got ${typeof frameStyle}.`);
+    if (!Array.isArray(kinds) ||
+        kinds.length === 0 ||
+        !kinds.every((kind) => typeof kind === 'string'))
+        throw new TypeError('columnsPlugin: kinds must be a non-empty array of kind names.');
+    if (typeof live !== 'boolean')
+        throw new TypeError(`columnsPlugin: live must be a boolean, got ${typeof live}.`);
+    if (write !== undefined && typeof write !== 'function')
+        throw new TypeError(`columnsPlugin: write must be a function, got ${typeof write}.`);
+    let { width } = options;
+    if (width === undefined) {
+        const { columns: terminal = 80 } = process.stdout;
+        const frames = (columns - 1) * text.textWidth(frame);
+        const room = Math.min(terminal, MAX_TOTAL_WIDTH) - frames;
+        width = Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, Math.floor(room / columns)));
+    }
+    assertInteger(width, 'width', MIN_WIDTH, MAX_WIDTH);
+    const total = columns * width + (columns - 1) * text.textWidth(frame);
+    if (total > MAX_TOTAL_WIDTH)
+        throw new RangeError(`columnsPlugin: the grid must be at most ${String(MAX_TOTAL_WIDTH)} terminal columns wide (columns × width + frames), got ${String(total)}.`);
+    const { indent = 0 } = options;
+    assertInteger(indent, 'indent', 0, width - 1);
+    return {
+        columns,
+        width,
+        frame,
+        frameEnd: frame.trimEnd(),
+        frameStyle,
+        kinds: [...kinds],
+        wrap: resolveWrap(options.wrap),
+        indent,
+        live,
+        customWrite: write !== undefined,
+        write: write ?? console.log,
+    };
+};
+/**
+ * Lays out logs in columns, side by side. Each log of the laid out kinds
+ * (by default messages and graphs) is a cell, and `column()` / `row()` pick
+ * the cell. Calls go call for call: the n-th log of each column shares a
+ * row, and a row is as tall as its tallest cell. Lines are wrapped at
+ * exactly `width` terminal columns (wide characters take two) and padded,
+ * except in the last column.
+ *
+ * ```ts
+ * const logger = new Logger()
+ *   .use(messagePlugin())
+ *   .use(graphPlugin({ width: 64 }))
+ *   .use(columnsPlugin({ columns: 2, width: 64 }));
+ * for (const column of [0, 1]) {
+ *   logger.column(column);
+ *   logger.info('styled by default');
+ *   logger.infoGraph(values);
+ * }
+ * logger.endColumns();
+ * ```
+ *
+ * Rows are written as soon as every column has moved past them or, with
+ * `live`, redrawn on every log. Outside `column()` … `endColumns()` the
+ * logger is not slowed down: the outputs are only swapped while a grid is
+ * open. Use after the plugins that render the kinds.
+ *
+ * @throws RangeError or TypeError for invalid options.
+ */
+const columnsPlugin = (options = {}) => {
+    const settings = resolveSettings(options);
+    return {
+        name: 'columns',
+        methods: (logger) => {
+            const columns = new Columns(logger, settings);
+            return {
+                column: (index) => {
+                    columns.column(index);
+                },
+                row: (index) => {
+                    columns.row(index);
+                },
+                endColumns: () => {
+                    columns.endColumns();
+                },
+            };
+        },
+    };
+};
+
+exports.DEFAULT_COLUMNS_WRAP = DEFAULT_COLUMNS_WRAP;
+exports.columnsPlugin = columnsPlugin;
+exports.wrapText = wrapText;
+//# sourceMappingURL=columns.cjs.map