@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/explorer/filter.js

@@ -0,0 +1,121 @@
+// Filters on the rows of a table, as the row grid of the web page sends them.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { escapeLike } from './search.js';
+export const FILTER_OPS = [
+    'eq',
+    'ne',
+    'contains',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'null',
+    'notnull',
+    'in',
+    'between',
+];
+export const MAX_IN_VALUES = 100;
+export class FilterError extends Error {
+}
+const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
+/** The values of an `in` list: commas separate them, a backslash escapes a comma or a backslash. */
+export function splitList(text) {
+    const values = [];
+    let current = '';
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === '\\' && i + 1 < text.length)
+            current += text[++i];
+        else if (char === ',') {
+            values.push(current.trim());
+            current = '';
+        }
+        else
+            current += char;
+    }
+    values.push(current.trim());
+    return values.filter((value) => value !== '');
+}
+const comparisons = {
+    eq: '=',
+    ne: '<>',
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+/**
+ * The WHERE clause for the filters. Columns must be ones of the table, and values are bound as
+ * parameters (or written as literals when `inline` is set, for showing the statement); a value is
+ * compared with the column's own type, so Postgres reads `2024-01-01` as a date for a date column.
+ */
+export function buildWhere(columns, filters, { inline = false } = {}) {
+    const params = [];
+    const bind = (value) => {
+        if (inline)
+            return quoteLiteral(value);
+        params.push(value);
+        return `$${params.length}`;
+    };
+    const known = new Set(columns.map((column) => column.name));
+    const conditions = filters.map((filter) => {
+        if (!known.has(filter.column))
+            throw new FilterError(`no column "${filter.column}"`);
+        if (!FILTER_OPS.includes(filter.op))
+            throw new FilterError(`unknown operator "${filter.op}"`);
+        const name = quoteIdentifier(filter.column);
+        const { op } = filter;
+        if (op === 'null')
+            return `${name} IS NULL`;
+        if (op === 'notnull')
+            return `${name} IS NOT NULL`;
+        const value = filter.value ?? '';
+        if (op === 'in') {
+            const values = splitList(value);
+            if (values.length === 0)
+                throw new FilterError(`"${filter.column}" in needs a value`);
+            if (values.length > MAX_IN_VALUES) {
+                throw new FilterError(`in takes at most ${MAX_IN_VALUES} values`);
+            }
+            return `${name} IN (${values.map(bind).join(', ')})`;
+        }
+        if (op === 'between') {
+            if (value === '' || (filter.value2 ?? '') === '') {
+                throw new FilterError(`"${filter.column}" between needs two values`);
+            }
+            const low = bind(value);
+            return `${name} BETWEEN ${low} AND ${bind(filter.value2)}`;
+        }
+        if (op === 'contains')
+            return `${name}::text ILIKE ${bind(`%${escapeLike(value)}%`)}`;
+        return `${name} ${comparisons[op]} ${bind(value)}`;
+    });
+    return {
+        sql: conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '',
+        params,
+    };
+}
+/** Reads the filters of a request, which are untrusted, as `Filter`s. */
+export function parseFilters(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new FilterError('filters must be a list');
+    if (raw.length > 50)
+        throw new FilterError('too many filters');
+    return raw.map((item) => {
+        const entry = item;
+        if (typeof entry?.column !== 'string' || typeof entry.op !== 'string') {
+            throw new FilterError('a filter is {column, op, value}');
+        }
+        const text = (field) => (typeof field === 'string' ? field : undefined);
+        const value = text(entry.value);
+        const value2 = text(entry.value2);
+        return {
+            column: entry.column,
+            op: entry.op,
+            ...(value === undefined ? {} : { value }),
+            ...(value2 === undefined ? {} : { value2 }),
+        };
+    });
+}

package/dist/explorer/format.js

@@ -0,0 +1,134 @@
+// How results are written out: on one line in a grid cell, as an aligned table like psql's, as CSV
+// and as JSON. Values arrive as the text Postgres sent (see Session).
+import stringWidth from 'string-width';
+export const outputFormats = ['table', 'csv', 'json'];
+export const nullText = 'NULL';
+/** A value on one line: line breaks and tabs become visible marks, so a row stays one row. */
+export const cellText = (value) => value === null
+    ? nullText
+    : value
+        .replaceAll('\r\n', '↵')
+        .replace(/[\n\r]/g, '↵')
+        .replaceAll('\t', '  ');
+/** Text cut to `width` columns, ending in … when it was longer. */
+export function truncate(text, width) {
+    if (width <= 0)
+        return '';
+    if (stringWidth(text) <= width)
+        return text;
+    let out = '';
+    for (const char of text) {
+        if (stringWidth(out + char) > width - 1)
+            break;
+        out += char;
+    }
+    return `${out}…`;
+}
+export const pad = (text, width, right = false) => {
+    const gap = ' '.repeat(Math.max(0, width - stringWidth(text)));
+    return right ? gap + text : text + gap;
+};
+const numericTypes = new Set([
+    'smallint',
+    'integer',
+    'bigint',
+    'numeric',
+    'real',
+    'double precision',
+    'oid',
+    'money',
+]);
+/** Whether a column holds numbers, which read best aligned to the right. */
+export const isNumeric = (column) => numericTypes.has(column.type) || column.type.startsWith('numeric');
+export const widthOf = stringWidth;
+/** An aligned table with a header row and a "(n rows)" footer, like psql prints. */
+export function textTable(result, { maxColumnWidth = 60 } = {}) {
+    const { columns, rows } = result;
+    const texts = rows.map((row) => row.map((value) => truncate(cellText(value), maxColumnWidth)));
+    const widths = columns.map((column, index) => Math.max(stringWidth(truncate(column.name, maxColumnWidth)), ...texts.map((row) => stringWidth(row[index] ?? ''))));
+    const line = (cells, right) => cells
+        .map((cell, index) => pad(cell, widths[index] ?? 0, right(index)))
+        .join(' | ')
+        .trimEnd();
+    const header = line(columns.map((column) => truncate(column.name, maxColumnWidth)), () => false);
+    const rule = widths.map((width) => '-'.repeat(width)).join('-+-');
+    const body = texts.map((row) => line(row, (index) => isNumeric(columns[index])));
+    const count = `(${rows.length} ${rows.length === 1 ? 'row' : 'rows'})`;
+    return [header, rule, ...body, count].join('\n') + '\n';
+}
+const csvField = (value) => /[",\r\n]/.test(value) ? `"${value.replaceAll('"', '""')}"` : value;
+/** RFC 4180 CSV with a header row; NULL is an empty field. */
+export function csv(result) {
+    const lines = [
+        result.columns.map((column) => csvField(column.name)).join(','),
+        ...result.rows.map((row) => row.map((value) => (value === null ? '' : csvField(value))).join(',')),
+    ];
+    return lines.map((line) => `${line}\r\n`).join('');
+}
+const jsonNumberTypes = new Set(['smallint', 'integer', 'real', 'double precision', 'oid']);
+/**
+ * A value as JSON: numbers that fit a JS number, booleans and json columns as themselves, and
+ * everything else (bigint and numeric included, to keep every digit) as its text.
+ */
+export function jsonValue(value, column) {
+    if (value === null)
+        return null;
+    if (jsonNumberTypes.has(column.type)) {
+        const number = Number(value);
+        return Number.isFinite(number) ? number : value;
+    }
+    if (column.type === 'boolean')
+        return value === 't';
+    if (column.type === 'json' || column.type === 'jsonb') {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+/** The rows as an array of objects keyed by column name (a repeated name keeps its last value). */
+export function jsonRows(result) {
+    return result.rows.map((row) => Object.fromEntries(result.columns.map((column, index) => [column.name, jsonValue(row[index] ?? null, column)])));
+}
+export function formatResult(result, format) {
+    if (format === 'csv')
+        return csv(result);
+    if (format === 'json')
+        return `${JSON.stringify(jsonRows(result), null, 2)}\n`;
+    return textTable(result);
+}
+/** "SELECT 3", "UPDATE 1": what a statement did, in psql's words. */
+export function commandSummary(result) {
+    if (result.truncated)
+        return `${result.command} (first ${result.rows.length} rows)`;
+    return result.rowCount === null ? result.command : `${result.command} ${result.rowCount}`;
+}
+const units = ['B', 'kB', 'MB', 'GB', 'TB', 'PB'];
+/** 1536 → "1.5 kB", as pg_size_pretty but with one decimal. */
+export function formatBytes(bytes) {
+    if (bytes === null)
+        return '';
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return unit === 0 ? `${value} B` : `${value.toFixed(1)} ${units[unit]}`;
+}
+/** 1234567 → "1.2M": a row estimate is only ever approximate. */
+export function formatEstimate(rows) {
+    if (rows === null)
+        return '';
+    if (rows < 1000)
+        return `~${rows}`;
+    if (rows < 1_000_000)
+        return `~${(rows / 1000).toFixed(1)}k`;
+    if (rows < 1_000_000_000)
+        return `~${(rows / 1_000_000).toFixed(1)}M`;
+    return `~${(rows / 1_000_000_000).toFixed(1)}B`;
+}
+export const formatDuration = (ms) => ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`;