neonctl 2.22.2 → 2.23.0

package/psql/print/latex.js

@@ -0,0 +1,396 @@
+import { formatNumericLocale } from './units.js';
+/**
+ * LaTeX printers — `latex` (tabular) and `latex-longtable` (longtable).
+ *
+ * Mirrors print.c `print_latex_text`, `print_latex_vertical`, and
+ * `print_latex_longtable_text`. Expanded mode for both `latex` and
+ * `latex-longtable` falls through to the vertical renderer
+ * (`print_latex_vertical`) — that's how upstream dispatches.
+ *
+ * Border behavior (flat tabular, from print.c):
+ *   - `topt.border` is clamped to 0..3.
+ *   - tabular column spec gets ` | ` between columns when border > 0,
+ *     and a leading/trailing `|` at border >= 2.
+ *   - border == 2 emits `\hline` around header and at end of table.
+ *   - border == 3 emits `\hline` after every row.
+ *
+ * Border behavior (expanded, from print.c):
+ *   - `topt.border` is clamped to 0..2 (note: not 0..3).
+ *   - tabular column spec is `cl`, `c|l`, or `|c|l|` for border 0/1/2.
+ *   - border >= 1 emits `\hline` between records.
+ *   - border == 2 wraps each "Record N" header in `\hline` lines.
+ *
+ * Numeric columns (per the OID heuristic) get the `r` alignment letter;
+ * everything else gets `l`. That letter is passed straight through to
+ * LaTeX's column spec.
+ *
+ * Escape: 14 LaTeX-special characters are rewritten. Embedded newlines
+ * in a cell turn into `\\` (LaTeX line break) for `latex`. The
+ * longtable variant uses the same escape but wraps cells in
+ * `\raggedright{...}` and ends rows with `\tabularnewline`.
+ */
+// INT2, INT4, INT8, FLOAT4, FLOAT8, NUMERIC, INTERVAL.
+const NUMERIC_OIDS = new Set([21, 23, 20, 700, 701, 1700, 1186]);
+export const latexPrinter = {
+    format: 'latex',
+    printQuery(rs, opts, out) {
+        const topt = opts.topt;
+        if (topt.expanded === 'on') {
+            return printLatexVertical(rs, opts, out);
+        }
+        return printLatexFlat(rs, opts, out);
+    },
+};
+const printLatexFlat = (rs, opts, out) => {
+    const topt = opts.topt;
+    const tuplesOnly = topt.tuplesOnly;
+    const startTable = topt.startTable;
+    const stopTable = topt.stopTable;
+    const border = clampBorder(topt.border, 3);
+    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 += '\\begin{center}\n';
+            buf += escapeLatex(title);
+            buf += '\n\\end{center}\n\n';
+        }
+        buf += '\\begin{tabular}{';
+        if (border >= 2)
+            buf += '| ';
+        aligns.forEach((a, idx) => {
+            buf += a;
+            if (border !== 0 && idx < ncols - 1)
+                buf += ' | ';
+        });
+        if (border >= 2)
+            buf += ' |';
+        buf += '}\n';
+        if (!tuplesOnly && border >= 2)
+            buf += '\\hline\n';
+        if (!tuplesOnly) {
+            headers.forEach((h, idx) => {
+                if (idx !== 0)
+                    buf += ' & ';
+                buf += '\\textit{' + escapeLatex(h) + '}';
+            });
+            buf += ' \\\\\n';
+            buf += '\\hline\n';
+        }
+    }
+    cells.forEach((row) => {
+        row.forEach((value, idx) => {
+            buf += escapeLatex(value);
+            if (idx === ncols - 1) {
+                buf += ' \\\\\n';
+                if (border === 3)
+                    buf += '\\hline\n';
+            }
+            else {
+                buf += ' & ';
+            }
+        });
+    });
+    if (stopTable) {
+        if (border === 2)
+            buf += '\\hline\n';
+        buf += '\\end{tabular}\n\n\\noindent ';
+        if (!tuplesOnly) {
+            const effective = effectiveFooters(rs, topt, footers);
+            for (const f of effective) {
+                buf += escapeLatex(f) + ' \\\\\n';
+            }
+        }
+        buf += '\n';
+    }
+    out.write(buf);
+    return Promise.resolve();
+};
+const printLatexVertical = (rs, opts, out) => {
+    const topt = opts.topt;
+    const tuplesOnly = topt.tuplesOnly;
+    const startTable = topt.startTable;
+    const stopTable = topt.stopTable;
+    const border = clampBorder(topt.border, 2);
+    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 = '';
+    if (startTable) {
+        if (!tuplesOnly && title) {
+            buf += '\\begin{center}\n';
+            buf += escapeLatex(title);
+            buf += '\n\\end{center}\n\n';
+        }
+        buf += '\\begin{tabular}{';
+        if (border === 0)
+            buf += 'cl';
+        else if (border === 1)
+            buf += 'c|l';
+        else
+            buf += '|c|l|';
+        buf += '}\n';
+    }
+    let record = topt.prior + 1;
+    cells.forEach((row) => {
+        if (!tuplesOnly) {
+            if (border === 2) {
+                buf += '\\hline\n';
+                buf += `\\multicolumn{2}{|c|}{\\textit{Record ${String(record)}}} \\\\\n`;
+            }
+            else {
+                buf += `\\multicolumn{2}{c}{\\textit{Record ${String(record)}}} \\\\\n`;
+            }
+            record += 1;
+        }
+        if (border >= 1)
+            buf += '\\hline\n';
+        row.forEach((value, idx) => {
+            buf += escapeLatex(headers[idx]);
+            buf += ' & ';
+            buf += escapeLatex(value);
+            buf += ' \\\\\n';
+        });
+    });
+    if (stopTable) {
+        if (border === 2)
+            buf += '\\hline\n';
+        buf += '\\end{tabular}\n\n\\noindent ';
+        // Expanded mode does NOT include the default "(N rows)" footer;
+        // only user-supplied footers (matches print_latex_vertical).
+        if (!tuplesOnly && footers && footers.length > 0) {
+            for (const f of footers) {
+                buf += escapeLatex(f) + ' \\\\\n';
+            }
+        }
+        buf += '\n';
+    }
+    out.write(buf);
+    return Promise.resolve();
+};
+export const latexLongtablePrinter = {
+    format: 'latex-longtable',
+    printQuery(rs, opts, out) {
+        // Upstream dispatch sends both `latex` and `latex-longtable` to
+        // `print_latex_vertical` when expanded is on (cf. print.c).
+        if (opts.topt.expanded === 'on') {
+            return printLatexVertical(rs, opts, out);
+        }
+        const topt = opts.topt;
+        const tuplesOnly = topt.tuplesOnly;
+        const startTable = topt.startTable;
+        const stopTable = topt.stopTable;
+        const border = clampBorder(topt.border, 3);
+        const nullPrint = opts.nullPrint !== '' ? opts.nullPrint : topt.nullPrint;
+        const title = opts.title ?? topt.title;
+        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)));
+        // `topt.tableAttr` for longtable encodes per-column widths in a
+        // whitespace-separated list, consumed left-to-right with a fall
+        // back to the previous value once exhausted.
+        const widths = (topt.tableAttr ?? '')
+            .split(/[\s]+/)
+            .filter((w) => w !== '');
+        let widthCursor = 0;
+        let lastWidth = null;
+        let buf = '';
+        if (startTable) {
+            buf += '\\begin{longtable}{';
+            if (border >= 2)
+                buf += '| ';
+            aligns.forEach((a, idx) => {
+                if (a === 'l' && widths.length > 0) {
+                    let w = null;
+                    if (widthCursor < widths.length) {
+                        w = widths[widthCursor];
+                        widthCursor += 1;
+                        lastWidth = w;
+                    }
+                    else if (lastWidth !== null) {
+                        w = lastWidth;
+                    }
+                    if (w !== null) {
+                        buf += `p{${w}\\textwidth}`;
+                    }
+                    else {
+                        buf += 'l';
+                    }
+                }
+                else {
+                    buf += a;
+                }
+                if (border !== 0 && idx < ncols - 1)
+                    buf += ' | ';
+            });
+            if (border >= 2)
+                buf += ' |';
+            buf += '}\n';
+            if (!tuplesOnly) {
+                // firsthead
+                if (border >= 2)
+                    buf += '\\toprule\n';
+                headers.forEach((h, idx) => {
+                    if (idx !== 0)
+                        buf += ' & ';
+                    buf += '\\small\\textbf{\\textit{' + escapeLatex(h) + '}}';
+                });
+                buf += ' \\\\\n';
+                buf += '\\midrule\n\\endfirsthead\n';
+                // continuation heads
+                if (border >= 2)
+                    buf += '\\toprule\n';
+                headers.forEach((h, idx) => {
+                    if (idx !== 0)
+                        buf += ' & ';
+                    buf += '\\small\\textbf{\\textit{' + escapeLatex(h) + '}}';
+                });
+                buf += ' \\\\\n';
+                if (border !== 3)
+                    buf += '\\midrule\n';
+                buf += '\\endhead\n';
+                if (title) {
+                    if (border === 2)
+                        buf += '\\bottomrule\n';
+                    buf +=
+                        '\\caption[' +
+                            escapeLatex(title) +
+                            ' (Continued)]{' +
+                            escapeLatex(title) +
+                            '}\n\\endfoot\n';
+                    if (border === 2)
+                        buf += '\\bottomrule\n';
+                    buf +=
+                        '\\caption[' +
+                            escapeLatex(title) +
+                            ']{' +
+                            escapeLatex(title) +
+                            '}\n\\endlastfoot\n';
+                }
+                else if (border >= 2) {
+                    buf += '\\bottomrule\n\\endfoot\n';
+                    buf += '\\bottomrule\n\\endlastfoot\n';
+                }
+            }
+        }
+        // Cells. Upstream interleaves `\n&\n` between in-row cells (and
+        // emits `\tabularnewline` to end a row), wrapping each value in
+        // `\raggedright{...}`.
+        let cellIdx = 0;
+        cells.forEach((row) => {
+            row.forEach((value) => {
+                if (cellIdx !== 0 && cellIdx % ncols !== 0)
+                    buf += '\n&\n';
+                buf += '\\raggedright{' + escapeLatex(value) + '}';
+                if ((cellIdx + 1) % ncols === 0) {
+                    buf += ' \\tabularnewline\n';
+                    if (border === 3)
+                        buf += ' \\hline\n';
+                }
+                cellIdx += 1;
+            });
+        });
+        if (stopTable)
+            buf += '\\end{longtable}\n';
+        out.write(buf);
+        return Promise.resolve();
+    },
+};
+const clampBorder = (b, max) => {
+    if (b > max)
+        return max;
+    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 escapeLatex = (input) => {
+    let out = '';
+    for (const ch of input) {
+        switch (ch) {
+            case '#':
+                out += '\\#';
+                break;
+            case '$':
+                out += '\\$';
+                break;
+            case '%':
+                out += '\\%';
+                break;
+            case '&':
+                out += '\\&';
+                break;
+            case '<':
+                out += '\\textless{}';
+                break;
+            case '>':
+                out += '\\textgreater{}';
+                break;
+            case '\\':
+                out += '\\textbackslash{}';
+                break;
+            case '^':
+                out += '\\^{}';
+                break;
+            case '_':
+                out += '\\_';
+                break;
+            case '{':
+                out += '\\{';
+                break;
+            case '|':
+                out += '\\textbar{}';
+                break;
+            case '}':
+                out += '\\}';
+                break;
+            case '~':
+                out += '\\~{}';
+                break;
+            case '\n':
+                out += '\\\\';
+                break;
+            default:
+                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/pager.js

@@ -0,0 +1,265 @@
+import { spawn } from 'child_process';
+import { accessSync, constants as fsConstants } from 'node:fs';
+import { basename, delimiter, isAbsolute, join } from 'path';
+/**
+ * Can `command` be spawned with `shell:false`? A bare name is searched on
+ * `$PATH`; a path is checked directly. Used to avoid `spawn(missingBinary,
+ * { shell:false })`, which does NOT throw synchronously (our try/catch never
+ * fires) but emits an async ENOENT — leaving writes to the dead child's stdin
+ * to vanish into a blank terminal (review item #19).
+ */
+const pagerCommandResolvable = (command) => {
+    const ok = (p) => {
+        try {
+            accessSync(p, fsConstants.X_OK);
+            return true;
+        }
+        catch {
+            // On Windows X_OK is not meaningful and a bare name omits `.exe`; fall
+            // back to a plain existence probe with common executable extensions.
+            if (process.platform === 'win32') {
+                for (const ext of ['', '.exe', '.cmd', '.bat']) {
+                    try {
+                        accessSync(p + ext, fsConstants.F_OK);
+                        return true;
+                    }
+                    catch {
+                        /* keep trying */
+                    }
+                }
+            }
+            return false;
+        }
+    };
+    if (command.includes('/') || command.includes('\\') || isAbsolute(command)) {
+        return ok(command);
+    }
+    return (process.env.PATH ?? '')
+        .split(delimiter)
+        .filter((d) => d.length > 0)
+        .some((dir) => ok(join(dir, command)));
+};
+/**
+ * Resolve the pager command string. Mirrors upstream:
+ *   PSQL_PAGER → PAGER → DEFAULT_PAGER (`less` on POSIX, none on Windows).
+ *
+ * Empty / whitespace-only env values FALL THROUGH to the next candidate. This
+ * deliberately diverges from strict upstream (where `PSQL_PAGER=''` would
+ * disable the pager outright) because in Node a spawned child cannot easily
+ * "unset" an inherited env var — tests have to override it with the empty
+ * string. Treating empty values as "unset" matches the conformance spec
+ * (`tests/psql-conformance/tap/030_pager.spec.ts`) and lets `PSQL_PAGER=''`
+ * fall through to PAGER, which is the user-friendly interpretation.
+ *
+ * Users who want to disable the pager unconditionally should set
+ * `\pset pager off` (preferred) or unset both env vars before launch.
+ */
+const resolvePagerCmd = (opts) => {
+    const env = opts.env ?? process.env;
+    const candidates = [
+        opts.pagerCmd,
+        env.PSQL_PAGER,
+        env.PAGER,
+    ];
+    for (const c of candidates) {
+        if (c === undefined)
+            continue;
+        // Empty or whitespace-only → treat as "not set" and try the next slot.
+        if (/^\s*$/.test(c))
+            continue;
+        return c;
+    }
+    // DEFAULT_PAGER: `less` on POSIX; nothing on Windows.
+    if (process.platform === 'win32')
+        return '';
+    return 'less';
+};
+const getIsTty = (opts) => {
+    if (opts.isTty !== undefined)
+        return opts.isTty;
+    const stream = opts.stdout ?? process.stdout;
+    // Some test streams won't have isTTY.
+    const tty = stream.isTTY;
+    return Boolean(tty);
+};
+const getTerminalHeight = (opts) => {
+    if (opts.terminalHeight !== undefined)
+        return opts.terminalHeight;
+    const stream = opts.stdout ?? process.stdout;
+    const rows = stream.rows;
+    // If we can't tell, fall back to 24 (classic VT100 default).
+    return typeof rows === 'number' && rows > 0 ? rows : 24;
+};
+/** Standalone helper to determine whether a pager is needed at all. */
+export const isPagerNeeded = (opts) => {
+    if (opts.pager === 'off')
+        return false;
+    const cmd = resolvePagerCmd(opts);
+    if (cmd === '')
+        return false;
+    if (opts.pager === 'always')
+        return true;
+    // pager === 'on'
+    if (!getIsTty(opts))
+        return false;
+    if (opts.lines === undefined)
+        return false;
+    const threshold = Math.max(opts.pagerMinLines, getTerminalHeight(opts));
+    return opts.lines >= threshold;
+};
+/**
+ * Decide whether a result of `rowCount` rows by `colCount` columns should be
+ * routed through the pager when written to `output`.
+ *
+ * NOTE on `pager === 'always'`: the TTY check is INTENTIONALLY skipped in
+ * this case. Upstream's `\pset pager always` is a user-explicit "force the
+ * pager on" override; honouring it on a pipe matches the integration test
+ * harness contract (see `tests/psql-conformance/tap/030_pager.spec.ts`) where
+ * the child process has no controlling TTY but the spec still requires the
+ * configured PAGER to be invoked. For `pager === 'on'` (auto mode) we keep
+ * the TTY guard so non-interactive runs don't spuriously spawn `less`.
+ */
+export const shouldPage = (opts) => {
+    if (opts.pager === 'off')
+        return false;
+    if (opts.redirectedOutput)
+        return false;
+    // Rough heuristic for "lines" — header (3) + rows + footer (1). Matches
+    // upstream `IsPagerNeeded` which counts rendered table lines.
+    const HEADER_LINES = 3;
+    const FOOTER_LINES = 1;
+    const estimatedLines = HEADER_LINES + Math.max(0, opts.rowCount) + FOOTER_LINES;
+    // TTY check: explicit override wins, else inspect the stream's own isTTY.
+    const isTty = opts.isTty !== undefined
+        ? opts.isTty
+        : Boolean(opts.output.isTTY);
+    // `pager === 'always'` bypasses the TTY guard — see the docstring above.
+    // The remaining gates (resolved cmd, redirected output, off) are enforced
+    // inside `isPagerNeeded`.
+    if (opts.pager !== 'always' && !isTty)
+        return false;
+    return isPagerNeeded({
+        pager: opts.pager,
+        pagerMinLines: opts.pagerMinLines,
+        pagerCmd: opts.pagerCmd,
+        env: opts.env,
+        stdout: opts.output,
+        isTty,
+        terminalHeight: opts.terminalHeight,
+        lines: estimatedLines,
+    });
+};
+const SHELL_META = /[\s|;><]/;
+const parsePagerCmd = (cmd) => {
+    // Match upstream behavior: when the value looks shell-y, hand it off to
+    // /bin/sh -c. Otherwise treat it as a direct argv[0].
+    if (SHELL_META.test(cmd)) {
+        return { command: cmd, args: [], shell: true };
+    }
+    return { command: cmd, args: [], shell: false };
+};
+const buildPagerEnv = (cmd, baseEnv) => {
+    const env = { ...baseEnv };
+    // psql sets LESS=FRX by default; mirror it when the resolved pager is
+    // `less` and the caller hasn't already set LESS.
+    if (env.LESS === undefined) {
+        // Pull out the first whitespace-separated token to detect `less` even
+        // when args follow (e.g. "less -S").
+        const firstToken = cmd.trim().split(/\s+/, 1)[0] ?? '';
+        const program = basename(firstToken);
+        if (program === 'less') {
+            env.LESS = 'FRX';
+        }
+    }
+    return env;
+};
+const noOpHandle = (out) => ({
+    out,
+    spawned: false,
+    close: () => Promise.resolve(0),
+});
+/**
+ * Returns a PagerHandle. Caller writes data to `out`, then calls `close()`.
+ * If no pager spawned (pager='off', not a TTY, or fewer lines than threshold),
+ * `out` is `stdout`.
+ */
+export const openPager = (opts) => {
+    const stdout = opts.stdout ?? process.stdout;
+    if (!isPagerNeeded(opts)) {
+        return noOpHandle(stdout);
+    }
+    const cmd = resolvePagerCmd(opts);
+    // isPagerNeeded already verified cmd is non-empty, but guard for safety.
+    if (cmd === '') {
+        return noOpHandle(stdout);
+    }
+    const { command, shell } = parsePagerCmd(cmd);
+    // A missing pager binary with shell:false emits an async ENOENT that the
+    // try/catch below cannot catch, and the result would be silently-discarded
+    // output. Pre-check and fall back to stdout instead (review item #19).
+    // shell:true goes through `sh -c`, which always exists.
+    if (!shell && !pagerCommandResolvable(command)) {
+        return noOpHandle(stdout);
+    }
+    const baseEnv = opts.env ?? process.env;
+    const childEnv = buildPagerEnv(cmd, baseEnv);
+    let child;
+    try {
+        child = spawn(command, [], {
+            stdio: ['pipe', 'inherit', 'inherit'],
+            shell,
+            env: childEnv,
+        });
+    }
+    catch {
+        // If the pager fails to spawn, fall back to stdout (matches upstream:
+        // `if (pagerpipe) return pagerpipe; restore_sigpipe_trap(); ... return stdout`).
+        return noOpHandle(stdout);
+    }
+    const stdin = child.stdin;
+    if (stdin === null) {
+        // Should not happen given stdio: ['pipe', ...], but be defensive.
+        return noOpHandle(stdout);
+    }
+    // Swallow EPIPE: the user can quit the pager early, after which any
+    // pending writes will fail with EPIPE. Upstream relies on SIGPIPE being
+    // ignored to short-circuit the write loop; we just drop the error.
+    stdin.on('error', (err) => {
+        if (err.code !== 'EPIPE') {
+            // Re-throw anything unexpected.
+            throw err;
+        }
+    });
+    const exitPromise = new Promise((resolve) => {
+        const settle = (code) => {
+            resolve(code ?? 0);
+        };
+        child.once('exit', (code) => {
+            settle(code);
+        });
+        child.once('error', () => {
+            // If the child errored (e.g. ENOENT), surface a non-zero exit code
+            // but don't throw — the caller's writes will have hit EPIPE which
+            // we already swallow.
+            settle(127);
+        });
+    });
+    return {
+        out: stdin,
+        spawned: true,
+        close: () => {
+            // End stdin then wait for the pager to drain & exit.
+            if (!stdin.writableEnded) {
+                try {
+                    stdin.end();
+                }
+                catch (err) {
+                    const e = err;
+                    if (e.code !== 'EPIPE')
+                        throw err;
+                }
+            }
+            return exitPromise;
+        },
+    };
+};