tablewalk 0.0.1

package/dist/adapters/adapter.js

@@ -0,0 +1,372 @@
+import { LIKE_ESCAPE, likePattern } from '../shared/like.js';
+/**
+ * The operators, as a value rather than only as a type.
+ *
+ * `Op` is checked by the compiler, and the compiler is not present when a
+ * request arrives: `/api/query`, `/api/count`, `/api/view/run` and
+ * `/api/references` all cast a request body straight to `Filter`, so the type
+ * was a comment as far as those paths were concerned. This is the list
+ * `buildWhere` actually checks against.
+ */
+export const OPS = new Set([
+    '=', '!=', '>', '>=', '<', '<=',
+    'contains', 'startsWith', 'endsWith', 'like', 'in', 'isNull', 'isNotNull',
+]);
+/* ---------- the limit policy ----------
+
+   One place, because a ceiling re-derived in four files is a ceiling that
+   disagrees with itself. Every read goes through `clampLimit`, so there is no
+   path to an unbounded query: a caller that omits a limit gets the default, a
+   caller that asks for too many gets the ceiling, and a caller that sends
+   nonsense gets the default rather than `LIMIT NaN`. */
+/** What a caller gets when it does not say. Small on purpose: the first page
+    of a browse should be instant, and paging is one click. */
+export const DEFAULT_LIMIT = 20;
+/** The hard ceiling. Nothing may exceed it, including an explicit request. */
+export const MAX_LIMIT = 100_000;
+/**
+ * Beyond this, a result is being fetched to be processed rather than read.
+ * Callers can use it to decide whether to warn; it is not enforced.
+ */
+export const LARGE_RESULT = 2_000;
+/**
+ * Above this many rows, an exact count is not worth what it costs.
+ *
+ * `COUNT(*)` is a scan. On a table of a few thousand rows that is free and the
+ * exact number is strictly better; on a table of fifty million it is seconds of
+ * work to compute a number that is stale before it is rendered, and it runs on
+ * *every* query — the header stat is not something anyone asked for.
+ *
+ * The threshold is deliberately well above anything a person would notice the
+ * difference on. Below it you get the true number; above it you get the
+ * catalog's estimate and are told that is what it is.
+ */
+export const ESTIMATE_ABOVE = 50_000;
+/**
+ * Only a number or a numeric string counts as a request. Everything else —
+ * undefined, null, '', [], {}, 'abc' — means "not specified" and gets the
+ * default.
+ *
+ * The `null` case is why this cannot just be `Number(value)`: `Number(null)`
+ * is 0, not NaN, so a null limit passed a finite check and clamped to 1. A
+ * caller that omitted a limit would have got a single row and no error.
+ */
+function asNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+/**
+ * A request an adapter will not carry out.
+ *
+ * Distinct from a database failure, and the distinction is the whole point:
+ * "that is not the whole primary key" and "the database is down" are both
+ * exceptions, and a server that cannot tell them apart answers both with a
+ * 500. The first is something the caller can fix by asking differently.
+ *
+ * Thrown only by guards that run *before* a statement is issued. Once the
+ * database has been asked, whatever comes back is the database's answer.
+ */
+export class Refusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'Refusal';
+    }
+}
+export function clampLimit(value, fallback = DEFAULT_LIMIT) {
+    const n = asNumber(value);
+    if (n === undefined)
+        return fallback;
+    return Math.min(Math.max(Math.floor(n), 1), MAX_LIMIT);
+}
+/** Offsets have no ceiling but must be a real, non-negative integer. */
+export function clampOffset(value) {
+    const n = asNumber(value);
+    if (n === undefined || n < 0)
+        return 0;
+    return Math.floor(n);
+}
+/**
+ * Refuse anything that is more than one statement.
+ *
+ * Not a SQL parser and not trying to be one — it answers exactly one question,
+ * "is there a second statement here", and it answers it by scanning for a
+ * semicolon that has something after it. Everything that can contain a
+ * semicolon harmlessly is skipped: single- and double-quoted strings,
+ * backquoted identifiers, line comments, block comments, and Postgres's
+ * dollar-quoted bodies, which is how a function definition carries semicolons
+ * without being several statements.
+ *
+ * Stacking is refused rather than truncated. Running the first half of what
+ * someone typed and discarding the rest is worse than refusing both: they
+ * asked for two things and would be told about neither.
+ *
+ * Returns null when the text is a single statement, or the reason it is not.
+ */
+export function refuseStacked(text) {
+    let i = 0;
+    const n = text.length;
+    while (i < n) {
+        const ch = text[i];
+        // Line comment, to end of line.
+        if (ch === '-' && text[i + 1] === '-') {
+            const nl = text.indexOf('\n', i);
+            i = nl < 0 ? n : nl + 1;
+            continue;
+        }
+        // Block comment. Not nested: no dialect here nests them.
+        if (ch === '/' && text[i + 1] === '*') {
+            const end = text.indexOf('*/', i + 2);
+            i = end < 0 ? n : end + 2;
+            continue;
+        }
+        // Dollar-quoted body: $$…$$ or $tag$…$tag$. Postgres only, harmless
+        // elsewhere because the opening tag simply will not match.
+        if (ch === '$') {
+            const tag = /^\$[A-Za-z_]\w*\$|^\$\$/.exec(text.slice(i))?.[0];
+            if (tag) {
+                const end = text.indexOf(tag, i + tag.length);
+                i = end < 0 ? n : end + tag.length;
+                continue;
+            }
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            i += 1;
+            while (i < n) {
+                if (text[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                // A doubled quote is an escaped quote, not the end of the string.
+                if (text[i] === ch && text[i + 1] === ch) {
+                    i += 2;
+                    continue;
+                }
+                if (text[i] === ch) {
+                    i += 1;
+                    break;
+                }
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === ';') {
+            // A trailing semicolon is punctuation, not a second statement.
+            if (text.slice(i + 1).trim() === '')
+                return null;
+            return 'One statement at a time. Remove the semicolon and everything after it, or run them separately.';
+        }
+        i += 1;
+    }
+    return null;
+}
+/**
+ * Output column names, with collisions given a suffix.
+ *
+ * `SELECT id, id FROM t` names both columns `id`. Left alone, the grid draws
+ * one header twice and nothing says which value belongs to which. The suffix
+ * is the same answer `compileView` gives an explicit collision, for the same
+ * reason: one column quietly standing in for two is worse than an ugly name.
+ */
+export function dedupe(names) {
+    const seen = new Map();
+    return names.map((name) => {
+        const count = seen.get(name) ?? 0;
+        seen.set(name, count + 1);
+        return count ? `${name}_${count + 1}` : name;
+    });
+}
+/** A statement with its trailing semicolon and surrounding space removed. */
+export function trimStatement(text) {
+    /* The whitespace *before* the semicolon goes too. `select 1 ;` left a
+       trailing space, which is invisible in the editor and shows up in the
+       reported statement as a difference between what ran and what was typed. */
+    return text.trim().replace(/\s*;+\s*$/, '');
+}
+/**
+ * Wrap a statement so it cannot return more rows than asked for.
+ *
+ * `clampLimit` is the invariant everywhere else in this file, and it has no
+ * application point in a statement this process did not build — there is no
+ * request object to clamp. Wrapping is the equivalent: the database is asked
+ * for a bounded result rather than trusted to have been asked politely.
+ *
+ * One more row than the caller wanted, so "there is more than this" is known
+ * without a second query — the same trick `runView` uses.
+ *
+ * The limit is interpolated rather than bound, which is the one deliberate
+ * exception to the rule that nothing is interpolated. It is an integer this
+ * process computed from `clampLimit`, never a value that came from outside,
+ * and it is asserted to be one before it is used. Binding it would need a
+ * dialect-specific placeholder here *and* MySQL's decimal-string workaround
+ * for row counts, which is a lot of machinery to parameterise a number we
+ * chose ourselves.
+ *
+ * Not every statement can be wrapped — `EXPLAIN`, `PRAGMA`, a `WITH` that ends
+ * in `INSERT … RETURNING` — so the caller is told whether it applied and can
+ * fall back to running the statement bare and saying so.
+ */
+export function boundStatement(text, limit) {
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw new Error(`A row limit must be a positive integer, not ${String(limit)}.`);
+    }
+    return `SELECT * FROM (${trimStatement(text)}) AS tablewalk_bounded LIMIT ${limit + 1}`;
+}
+/**
+ * Whether a statement is worth trying to wrap.
+ *
+ * A conservative first token test, and deliberately not a parse. Getting this
+ * wrong in the cautious direction costs a bounded result; getting it wrong in
+ * the other direction costs a confusing syntax error from the database about a
+ * statement the user did not write. `WITH` is included because a CTE ending in
+ * a SELECT is the common case, and the wrap failing on one that does not is
+ * handled by the fallback rather than by being clever here.
+ */
+export function looksWrappable(text) {
+    const first = trimStatement(text).replace(/^\s*(?:--[^\n]*\n|\/\*[\s\S]*?\*\/|\s)+/g, '');
+    return /^(select|with|table|values)\b/i.test(first);
+}
+/**
+ * A queue of one.
+ *
+ * Every adapter here writes through a single connection, and a transaction is
+ * a span of statements on it that nothing else may enter. Node is
+ * single-threaded but `await` is not: two requests arriving together interleave
+ * at every await point, so a plain `/api/update` can land in the middle of
+ * somebody's open transaction and be rolled back with it — a write that
+ * succeeded, reported success, and then quietly did not happen.
+ *
+ * So writes queue. The cost is that two concurrent edits are applied one after
+ * the other rather than at once, which is what a single connection was always
+ * going to do anyway.
+ */
+export class Serial {
+    tail = Promise.resolve();
+    run(work) {
+        /* The chain must not break on a failure: `catch` here keeps the *queue*
+           going while the caller still gets the rejection from `next`. */
+        const next = this.tail.then(work, work);
+        this.tail = next.catch(() => { });
+        return next;
+    }
+}
+export const ANSI_STYLE = {
+    // Doubling an embedded quote is the standard escape and is what makes a
+    // table called `weird"name` safe rather than a syntax error.
+    quote: (id) => `"${id.replace(/"/g, '""')}"`,
+    placeholder: () => '?',
+    likeOp: 'LIKE',
+    /* `strftime` has no quarter, so it is arithmetic on the month: 1–3 → 1.
+       Written with the engine's own integer division rather than a CASE, which
+       would be four branches to say one sum. */
+    dateBucket: (e, unit) => (unit === 'quarter'
+        ? `strftime('%Y', ${e}) || '-Q' || CAST((CAST(strftime('%m', ${e}) AS INTEGER) + 2) / 3 AS TEXT)`
+        : `strftime('${{ day: '%Y-%m-%d', month: '%Y-%m', year: '%Y' }[unit]}', ${e})`),
+};
+export const POSTGRES_STYLE = {
+    quote: ANSI_STYLE.quote,
+    placeholder: (i) => `$${i}`,
+    likeOp: 'ILIKE',
+    /* `to_char` rather than `date_trunc`, for the text the interface says it
+       returns. `Q` is a to_char field, so the quarter needs no arithmetic. */
+    dateBucket: (e, unit) => `to_char(${e}, '${{ day: 'YYYY-MM-DD', month: 'YYYY-MM', quarter: 'YYYY-"Q"Q', year: 'YYYY' }[unit]}')`,
+};
+export const MYSQL_STYLE = {
+    quote: (id) => `\`${id.replace(/`/g, '``')}\``,
+    placeholder: () => '?',
+    /* A column declared with a `_bin` or `_cs` collation compares case
+       sensitively even here. Forcing a collation in the predicate would fix
+       that and break every latin1 column, so this follows the column. */
+    likeOp: 'LIKE',
+    /* `DATE_FORMAT` has no quarter specifier either, and MySQL's `QUARTER()`
+       returns a number — concatenated rather than formatted, to land on the
+       same `2026-Q3` the other two produce. */
+    dateBucket: (e, unit) => (unit === 'quarter'
+        ? `CONCAT(DATE_FORMAT(${e}, '%Y'), '-Q', QUARTER(${e}))`
+        : `DATE_FORMAT(${e}, '${{ day: '%Y-%m-%d', month: '%Y-%m', year: '%Y' }[unit]}')`),
+};
+/**
+ * Compile a filter to a WHERE clause plus bound parameters.
+ *
+ * `startIndex` exists for Postgres, where placeholders are numbered across the
+ * whole statement rather than positional.
+ *
+ * `column` exists for views. A multi-table statement needs
+ * `"customer_1"."name"` where a single-table one needs `"name"`, and the
+ * difference is *only* how an identifier is written — the operators, the
+ * empty-IN case, the LIKE wrapping and the invariant that every value is a
+ * bound parameter are the same either way. Passing the resolver in keeps one
+ * predicate builder rather than two that can drift; a second copy of this
+ * function is a second chance to interpolate a value by accident.
+ */
+export function buildWhere(filter, style, startIndex = 1, column = (name) => style.quote(name)) {
+    if (!filter?.groups.length)
+        return { text: '', params: [] };
+    const params = [];
+    let index = startIndex;
+    const next = () => style.placeholder(index++);
+    const groupSql = filter.groups
+        .filter((g) => g.length)
+        .map((group) => group
+        .map((c) => {
+        const col = column(c.column);
+        switch (c.op) {
+            case 'isNull':
+                return `${col} IS NULL`;
+            case 'isNotNull':
+                return `${col} IS NOT NULL`;
+            case 'in': {
+                const list = Array.isArray(c.value) ? c.value : [c.value];
+                if (!list.length)
+                    return '1 = 0'; // an empty IN matches nothing
+                const holes = list.map((v) => {
+                    params.push(v ?? null);
+                    return next();
+                });
+                return `${col} IN (${holes.join(', ')})`;
+            }
+            /* All three go through one pattern builder, which escapes the
+               wildcards in the value: `contains 50%` is a search for a
+               percent sign, not a search for everything. */
+            case 'contains':
+            case 'startsWith':
+            case 'endsWith':
+                params.push(likePattern(c.value, c.op));
+                return `${col} ${style.likeOp} ${next()} ESCAPE '${LIKE_ESCAPE}'`;
+            /* Bound, not escaped: the wildcards belong to whoever typed them.
+               Still a parameter — the value never becomes SQL text — so the
+               safety argument is unchanged, and still `ESCAPE '#'`, so the
+               way to ask for a literal `%` is the same one `contains` uses
+               internally. */
+            case 'like':
+                params.push(String(c.value ?? ''));
+                return `${col} ${style.likeOp} ${next()} ESCAPE '${LIKE_ESCAPE}'`;
+            default: {
+                /* The one field in a structured request that becomes SQL text
+                   rather than a bound parameter — and until now it was checked
+                   only by the config-file parser, so every endpoint that casts
+                   a body to `Filter` accepted whatever it was sent. The column
+                   is quoted and the value is bound; this was the gap between
+                   those two, and the whole safety argument is that a structured
+                   request cannot express injection.
+  
+                   Checked here rather than at each caller: one choke point
+                   covers the four endpoints and anything added later. */
+                if (!OPS.has(c.op)) {
+                    throw new Refusal(`"${String(c.op)}" is not an operator this tool knows.`);
+                }
+                params.push(c.value ?? null);
+                return `${col} ${c.op} ${next()}`;
+            }
+        }
+    })
+        .join(' AND '));
+    if (!groupSql.length)
+        return { text: '', params: [] };
+    const text = groupSql.length === 1 ? groupSql[0] : groupSql.map((g) => `(${g})`).join(' OR ');
+    return { text: ` WHERE ${text}`, params };
+}

package/dist/adapters/connect.js

@@ -0,0 +1,33 @@
+import { SqliteAdapter } from './sqlite.js';
+import { PostgresAdapter } from './postgres.js';
+import { MysqlAdapter } from './mysql.js';
+export function connect(target, options = {}) {
+    if (/^postgres(ql)?:\/\//i.test(target)) {
+        return new PostgresAdapter(target, options.label, options.schemas ?? []);
+    }
+    /* `mariadb://` too: MariaDB speaks the MySQL protocol and its catalog is
+       the same `information_schema`, so refusing the scheme would be turning
+       someone away from a database this adapter can already read. */
+    if (/^(mysql|mariadb):\/\//i.test(target)) {
+        return new MysqlAdapter(target, options.label, options.schemas ?? []);
+    }
+    if (/^sqlite:/i.test(target)) {
+        const file = target.replace(/^sqlite:(\/\/)?/i, '');
+        return new SqliteAdapter(file, options.label ?? file);
+    }
+    // A bare path is a SQLite file. This is the common case for the demo and
+    // for anyone poking at an app's local database, so it needs no scheme.
+    if (/\.(db|sqlite|sqlite3)$/i.test(target) || !target.includes('://')) {
+        return new SqliteAdapter(target, options.label ?? target);
+    }
+    /* The scheme, not the target.
+    
+       `target` here is the *resolved* connection string — the password has
+       already been expanded into it — and this message was stored on the
+       connection entry and served to the browser from then on. The scheme is
+       the whole of the useful content anyway: what is wrong is the protocol,
+       and repeating the credentials does not help anyone fix it. */
+    const scheme = target.match(/^([a-z][\w+.-]*):\/\//i)?.[1];
+    throw new Error(`Don't know how to open ${scheme ? `a "${scheme}://" connection` : 'that connection'}. `
+        + 'Supported: a SQLite file path, sqlite:<path>, postgres://… or mysql://…');
+}