neonctl 2.22.2 → 2.23.0

package/psql/print/troff.js

@@ -0,0 +1,258 @@
+import { formatNumericLocale } from './units.js';
+/**
+ * Troff MS printer.
+ *
+ * Mirrors print.c `print_troff_ms_text` and `print_troff_ms_vertical`.
+ *
+ * Output shape (flat, with title and one footer):
+ *   .LP
+ *   .DS C
+ *   title
+ *   .DE
+ *   .LP
+ *   .TS
+ *   center;
+ *   l | l | r.
+ *   \fIcol1\fP	\fIcol2\fP	\fIcol3\fP
+ *   _
+ *   val1	val2	val3
+ *   .TE
+ *   .DS L
+ *   (N rows)
+ *   .DE
+ *
+ * Output shape (expanded, `\pset expanded on`):
+ *   .LP
+ *   .TS
+ *   center;
+ *   c s.
+ *   \fIRecord 1\fP
+ *   _              # if border>=1
+ *   .T&
+ *   c | l.         # `c l.` when border != 1
+ *   colname1	val1
+ *   colname2	val2
+ *   ...
+ *   .T&
+ *   c s.
+ *   \fIRecord 2\fP
+ *   ...
+ *   .TE
+ *   .DS L
+ *   .DE
+ *
+ * - `topt.border` is clamped to 0..2. `border == 2` uses `center box;`;
+ *   otherwise just `center;`. Border > 0 inserts ` | ` between column
+ *   spec letters.
+ * - Numeric columns get `r`, others `l` (per the OID heuristic).
+ * - Tab is the field separator (consistent with `.TS` defaults).
+ * - The only structurally-hostile character is `\\`, which becomes
+ *   `\(rs` (troff's "reverse solidus" glyph). Everything else passes
+ *   through verbatim — troff ms is a byte stream.
+ * - Expanded mode emits a `.T&\n<spec>.\n` re-spec block between the
+ *   "Record N" header (`c s.`) and the body (`c l.` / `c | l.`); under
+ *   tuples-only the body spec is set once as `c l;` after the table
+ *   header. No default `(N rows)` footer.
+ */
+// INT2, INT4, INT8, FLOAT4, FLOAT8, NUMERIC, INTERVAL.
+const NUMERIC_OIDS = new Set([21, 23, 20, 700, 701, 1700, 1186]);
+export const troffMsPrinter = {
+    format: 'troff-ms',
+    printQuery(rs, opts, out) {
+        const topt = opts.topt;
+        if (topt.expanded === 'on') {
+            return printExpanded(rs, opts, out);
+        }
+        return printFlat(rs, opts, out);
+    },
+};
+const printFlat = (rs, opts, out) => {
+    const topt = opts.topt;
+    const tuplesOnly = topt.tuplesOnly;
+    const startTable = topt.startTable;
+    const stopTable = topt.stopTable;
+    const border = clampBorder(topt.border);
+    const nullPrint = opts.nullPrint !== '' ? opts.nullPrint : topt.nullPrint;
+    const title = opts.title ?? topt.title;
+    const footers = opts.footers ?? topt.footers;
+    const headers = rs.fields.map((f) => f.name);
+    const ncols = rs.fields.length;
+    const aligns = rs.fields.map((f) => NUMERIC_OIDS.has(f.dataTypeID) ? 'r' : 'l');
+    const cells = rs.rows.map((row) => row.map((cell) => renderCell(cell, nullPrint, topt.numericLocale)));
+    let buf = '';
+    if (startTable) {
+        if (!tuplesOnly && title) {
+            buf += '.LP\n.DS C\n';
+            buf += escapeTroff(title);
+            buf += '\n.DE\n';
+        }
+        buf += '.LP\n.TS\n';
+        buf += border === 2 ? 'center box;\n' : 'center;\n';
+        aligns.forEach((a, idx) => {
+            buf += a;
+            if (border > 0 && idx < ncols - 1)
+                buf += ' | ';
+        });
+        buf += '.\n';
+        if (!tuplesOnly) {
+            headers.forEach((h, idx) => {
+                if (idx !== 0)
+                    buf += '\t';
+                buf += '\\fI' + escapeTroff(h) + '\\fP';
+            });
+            buf += '\n_\n';
+        }
+    }
+    cells.forEach((row) => {
+        row.forEach((value, idx) => {
+            buf += escapeTroff(value);
+            if (idx === ncols - 1)
+                buf += '\n';
+            else
+                buf += '\t';
+        });
+    });
+    if (stopTable) {
+        buf += '.TE\n.DS L\n';
+        if (!tuplesOnly) {
+            const effective = effectiveFooters(rs, topt, footers);
+            for (const f of effective) {
+                buf += escapeTroff(f) + '\n';
+            }
+        }
+        buf += '.DE\n';
+    }
+    out.write(buf);
+    return Promise.resolve();
+};
+const printExpanded = (rs, opts, out) => {
+    const topt = opts.topt;
+    const tuplesOnly = topt.tuplesOnly;
+    const startTable = topt.startTable;
+    const stopTable = topt.stopTable;
+    const border = clampBorder(topt.border);
+    const nullPrint = opts.nullPrint !== '' ? opts.nullPrint : topt.nullPrint;
+    const title = opts.title ?? topt.title;
+    const footers = opts.footers ?? topt.footers;
+    const headers = rs.fields.map((f) => f.name);
+    const cells = rs.rows.map((row) => row.map((cell) => renderCell(cell, nullPrint, topt.numericLocale)));
+    let buf = '';
+    // currentFormat: 0 = none yet, 1 = "Record N" header (c s),
+    // 2 = body (c l or c | l). Upstream uses the same tri-state to
+    // decide when to emit `.T&` separators.
+    let currentFormat = 0;
+    if (startTable) {
+        if (!tuplesOnly && title) {
+            buf += '.LP\n.DS C\n';
+            buf += escapeTroff(title);
+            buf += '\n.DE\n';
+        }
+        buf += '.LP\n.TS\n';
+        buf += border === 2 ? 'center box;\n' : 'center;\n';
+        // Under tuples-only, upstream emits a one-shot `c l;` body spec
+        // here so each Record's first .T& block is omitted.
+        if (tuplesOnly) {
+            buf += 'c l;\n';
+        }
+    }
+    else {
+        // Continuation: assume body spec is already in effect.
+        currentFormat = 2;
+    }
+    let record = topt.prior + 1;
+    cells.forEach((row, rowIdx) => {
+        if (!tuplesOnly) {
+            if (currentFormat !== 1) {
+                if (border === 2 && rowIdx > 0)
+                    buf += '_\n';
+                if (currentFormat !== 0)
+                    buf += '.T&\n';
+                buf += 'c s.\n';
+                currentFormat = 1;
+            }
+            buf += `\\fIRecord ${String(record)}\\fP\n`;
+            record += 1;
+        }
+        if (border >= 1)
+            buf += '_\n';
+        if (!tuplesOnly) {
+            if (currentFormat !== 2) {
+                if (currentFormat !== 0)
+                    buf += '.T&\n';
+                buf += border !== 1 ? 'c l.\n' : 'c | l.\n';
+                currentFormat = 2;
+            }
+        }
+        row.forEach((value, idx) => {
+            buf += escapeTroff(headers[idx]);
+            buf += '\t';
+            buf += escapeTroff(value);
+            buf += '\n';
+        });
+    });
+    if (stopTable) {
+        buf += '.TE\n.DS L\n';
+        // Expanded mode does NOT emit the default "(N rows)" footer.
+        if (!tuplesOnly && footers && footers.length > 0) {
+            for (const f of footers) {
+                buf += escapeTroff(f) + '\n';
+            }
+        }
+        buf += '.DE\n';
+    }
+    out.write(buf);
+    return Promise.resolve();
+};
+const clampBorder = (b) => {
+    if (b > 2)
+        return 2;
+    if (b < 0)
+        return 0;
+    return b;
+};
+const effectiveFooters = (rs, topt, footers) => {
+    if (footers && footers.length > 0)
+        return footers;
+    if (topt.defaultFooter) {
+        const n = rs.rows.length;
+        return [`(${String(n)} ${n === 1 ? 'row' : 'rows'})`];
+    }
+    return [];
+};
+const escapeTroff = (input) => {
+    // Only `\` is dangerous (it begins a troff escape). Map it to `\(rs`,
+    // which renders the reverse-solidus glyph. Newlines flow through
+    // unchanged — `.TS` treats each line as a new row, so we never want
+    // raw newlines inside a cell; that constraint is enforced upstream
+    // by the caller, not here. (`renderCell` similarly never emits a raw
+    // newline today.)
+    let out = '';
+    for (const ch of input) {
+        if (ch === '\\')
+            out += '\\(rs';
+        else
+            out += ch;
+    }
+    return out;
+};
+const renderCell = (cell, nullPrint, numericLocale) => {
+    if (cell === null || cell === undefined)
+        return nullPrint;
+    if (typeof cell === 'string') {
+        return formatNumericLocale(cell, numericLocale);
+    }
+    if (typeof cell === 'number' || typeof cell === 'bigint') {
+        return formatNumericLocale(cell.toString(), numericLocale);
+    }
+    if (typeof cell === 'boolean')
+        return cell ? 't' : 'f';
+    if (cell instanceof Date)
+        return cell.toISOString();
+    if (cell instanceof Uint8Array) {
+        let hex = '\\x';
+        for (const b of cell)
+            hex += b.toString(16).padStart(2, '0');
+        return hex;
+    }
+    return JSON.stringify(cell);
+};

package/psql/print/unaligned.js

@@ -0,0 +1,118 @@
+import { formatNumericLocale } from './units.js';
+/**
+ * Unaligned tabular printer.
+ *
+ * Mirrors print.c `print_unaligned_text` / `print_unaligned_vertical`.
+ *
+ * Field separator defaults to `|`, record separator defaults to `\n`,
+ * both honor `opts.topt.fieldSep` / `recordSep`. NULL cells render
+ * `opts.nullPrint` (which falls back to `topt.nullPrint`, default `''`).
+ *
+ * Expanded (`\x`) mode prints `colname|value` per line with a blank
+ * record-sep gap between rows.
+ *
+ * The default footer `(N rows)` is only emitted when not in expanded
+ * mode and `topt.defaultFooter` is true; same as upstream psql.
+ */
+export const unalignedPrinter = {
+    format: 'unaligned',
+    printQuery(rs, opts, out) {
+        const topt = opts.topt;
+        const fieldSep = topt.fieldSep !== '' ? topt.fieldSep : '|';
+        const recordSep = topt.recordSep !== '' ? topt.recordSep : '\n';
+        const nullPrint = opts.nullPrint !== '' ? opts.nullPrint : topt.nullPrint;
+        const expanded = topt.expanded === 'on';
+        const tuplesOnly = topt.tuplesOnly;
+        const headers = rs.fields.map((f) => f.name);
+        const cells = rs.rows.map((row) => row.map((cell) => renderCell(cell, nullPrint, topt.numericLocale)));
+        let outBuf = '';
+        if (expanded) {
+            // Vertical mode mirrors print.c `print_unaligned_vertical`: each
+            // record gap is a DOUBLE recordSep, the title (if any) emits
+            // without a trailing separator (the loop handles that), inter-
+            // column lines get one recordSep, and the closing footer block is
+            // preceded by a recordSep with one more recordSep separating each
+            // footer entry.
+            let needRecordSep = false;
+            if (!tuplesOnly && opts.title) {
+                outBuf += opts.title;
+                needRecordSep = true;
+            }
+            cells.forEach((row) => {
+                if (needRecordSep) {
+                    outBuf += recordSep + recordSep;
+                    needRecordSep = false;
+                }
+                row.forEach((value, colIdx) => {
+                    outBuf += headers[colIdx] + fieldSep + value;
+                    if (colIdx < row.length - 1) {
+                        outBuf += recordSep;
+                    }
+                    else {
+                        needRecordSep = true;
+                    }
+                });
+            });
+            if (!tuplesOnly && opts.footers && opts.footers.length > 0) {
+                outBuf += recordSep;
+                for (const footer of opts.footers) {
+                    outBuf += recordSep + footer;
+                }
+                needRecordSep = true;
+            }
+            if (needRecordSep)
+                outBuf += recordSep;
+        }
+        else {
+            // Horizontal mode.
+            if (!tuplesOnly && opts.title) {
+                outBuf += opts.title + recordSep;
+            }
+            if (!tuplesOnly) {
+                outBuf += headers.join(fieldSep) + recordSep;
+            }
+            cells.forEach((row) => {
+                outBuf += row.join(fieldSep) + recordSep;
+            });
+            // Default `(N rows)` footer is suppressed when the caller supplied its
+            // own footers — upstream (and aligned.ts) print user footers INSTEAD of
+            // the row count, not in addition (review: unaligned footer duplication).
+            const hasUserFooters = opts.footers !== undefined &&
+                opts.footers !== null &&
+                opts.footers.length > 0;
+            if (!tuplesOnly && topt.defaultFooter && !hasUserFooters) {
+                const n = rs.rows.length;
+                outBuf += `(${String(n)} ${n === 1 ? 'row' : 'rows'})` + recordSep;
+            }
+            if (!tuplesOnly && hasUserFooters) {
+                for (const footer of opts.footers ?? []) {
+                    outBuf += footer + recordSep;
+                }
+            }
+        }
+        out.write(outBuf);
+        return Promise.resolve();
+    },
+};
+const renderCell = (cell, nullPrint, numericLocale) => {
+    if (cell === null || cell === undefined)
+        return nullPrint;
+    if (typeof cell === 'string') {
+        return formatNumericLocale(cell, numericLocale);
+    }
+    if (typeof cell === 'number' || typeof cell === 'bigint') {
+        return formatNumericLocale(cell.toString(), numericLocale);
+    }
+    if (typeof cell === 'boolean')
+        return cell ? 't' : 'f';
+    if (cell instanceof Date)
+        return cell.toISOString();
+    if (cell instanceof Uint8Array) {
+        // Bytea -> hex escape, matching libpq's `\x` form.
+        let hex = '\\x';
+        for (const b of cell)
+            hex += b.toString(16).padStart(2, '0');
+        return hex;
+    }
+    return JSON.stringify(cell);
+};

package/psql/print/units.js

@@ -0,0 +1,135 @@
+/**
+ * Numeric, byte size, and duration formatting helpers.
+ *
+ * Mirrors psql's `\pset numericlocale`, the server-side
+ * `pg_size_pretty()` output, and the `\timing` line format.
+ */
+const NUMERIC_RE = /^-?\d+(\.\d+)?$/;
+/**
+ * Format a numeric string using locale-aware thousand separators and
+ * decimal point. Equivalent to print.c `format_numeric_locale` but
+ * implemented through the host's `Intl.NumberFormat`.
+ *
+ * When `useLocale` is false (the psql default) the input is returned
+ * unchanged. Only operates on values whose stringified form matches
+ * `^-?\d+(\.\d+)?$`; anything else (NaN, scientific notation, etc.) is
+ * returned as-is so we never mangle non-numeric data passed via
+ * `numericlocale`.
+ */
+export const formatNumericLocale = (value, useLocale, locale) => {
+    if (!useLocale)
+        return value;
+    if (!NUMERIC_RE.test(value))
+        return value;
+    const dotIdx = value.indexOf('.');
+    const fractionDigits = dotIdx === -1 ? 0 : value.length - dotIdx - 1;
+    // Use BigInt for the integer part to avoid float precision loss on
+    // very large integers; format the fractional component as a separate
+    // number so we keep the exact digit count the input had.
+    const negative = value.startsWith('-');
+    const unsigned = negative ? value.slice(1) : value;
+    const [intPart, fracPart = ''] = unsigned.split('.');
+    const intFormatted = new Intl.NumberFormat(locale, {
+        useGrouping: true,
+        maximumFractionDigits: 0,
+    }).format(BigInt(intPart));
+    if (fractionDigits === 0) {
+        return negative ? `-${intFormatted}` : intFormatted;
+    }
+    // Discover this locale's decimal separator.
+    const decimalSep = new Intl.NumberFormat(locale)
+        .formatToParts(1.1)
+        .find((p) => p.type === 'decimal')?.value ?? '.';
+    const out = `${intFormatted}${decimalSep}${fracPart}`;
+    return negative ? `-${out}` : out;
+};
+const BYTE_UNITS = [
+    { name: 'bytes', bits: 0 },
+    { name: 'kB', bits: 10 },
+    { name: 'MB', bits: 20 },
+    { name: 'GB', bits: 30 },
+    { name: 'TB', bits: 40 },
+    { name: 'PB', bits: 50 },
+];
+const SI_UNITS = [
+    { name: 'B', bits: 0 },
+    { name: 'kB', bits: 10 },
+    { name: 'MB', bits: 20 },
+    { name: 'GB', bits: 30 },
+    { name: 'TB', bits: 40 },
+    { name: 'PB', bits: 50 },
+];
+/**
+ * Pretty-print a byte count.
+ *
+ * Follows pg's `pg_size_pretty` ladder: values under 10 240 use the
+ * `bytes` unit, otherwise we promote until the magnitude is below
+ * 20 * 1024 in the next unit and emit one decimal place.
+ *
+ * `opts.si` swaps the smallest unit name from `bytes` to `B`. (psql
+ * itself does not have an SI flag, but we expose one because callers
+ * outside the print path want a shorter `0 B` rendering.)
+ */
+export const formatByteSize = (bytes, opts) => {
+    const units = opts?.si ? SI_UNITS : BYTE_UNITS;
+    const sign = bytes < 0 ? '-' : '';
+    let abs = Math.abs(bytes);
+    // Bytes unit: render integer count.
+    if (abs < 10 * 1024) {
+        return `${sign}${abs.toString()} ${units[0].name}`;
+    }
+    // Promote until the value, scaled to the next unit, would be below
+    // 20 * 1024. Mirrors the original loop's threshold check.
+    let unitIndex = 1;
+    abs = abs / 1024;
+    while (unitIndex < units.length - 1 && abs >= 20 * 1024) {
+        abs = abs / 1024;
+        unitIndex++;
+    }
+    // One decimal place once we leave the `bytes` regime, matching the
+    // `0 B`, `1.0 kB`, `1.5 MB` shape the WP spec calls out.
+    return `${sign}${abs.toFixed(1)} ${units[unitIndex].name}`;
+};
+/**
+ * Render a duration in the upstream `\timing` style. psql scales the
+ * granularity to keep the line compact:
+ *
+ *   - `< 1 ms`     → `Time: 0.123 ms` (three decimal digits)
+ *   - `< 1 s`      → `Time: 123.456 ms`
+ *   - `< 1 min`    → `Time: 12.345 s`
+ *   - `< 1 hour`   → `Time: 12 m 34.567 s`
+ *   - `>= 1 hour`  → `Time: 1 h 23 m 45.678 s`
+ *
+ * Mirrors the `PrintTiming()` ladder in `src/bin/psql/common.c`. Negative
+ * or non-finite inputs fall through the ladder as `0`.
+ */
+export const formatDurationMs = (ms) => {
+    return `Time: ${formatDurationBody(ms)}`;
+};
+/**
+ * Format just the scaled-duration body (without the `Time: ` prefix) so
+ * callers like the `\watch` header can reuse the same ladder without
+ * dragging the prefix along.
+ */
+export const formatDurationBody = (ms) => {
+    const safe = Number.isFinite(ms) && ms > 0 ? ms : 0;
+    // Under one second: render in milliseconds with three decimal places.
+    if (safe < 1000) {
+        return `${safe.toFixed(3)} ms`;
+    }
+    const totalSeconds = safe / 1000;
+    // Under one minute: render in seconds with three decimal places.
+    if (totalSeconds < 60) {
+        return `${totalSeconds.toFixed(3)} s`;
+    }
+    // Under one hour: `M m SS.sss s`.
+    const totalMinutes = Math.floor(totalSeconds / 60);
+    const remainingSeconds = totalSeconds - totalMinutes * 60;
+    if (totalMinutes < 60) {
+        return `${String(totalMinutes)} m ${remainingSeconds.toFixed(3)} s`;
+    }
+    // One hour or more: `H h MM m SS.sss s`.
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes - hours * 60;
+    return `${String(hours)} h ${String(minutes)} m ${remainingSeconds.toFixed(3)} s`;
+};