tablewalk 0.0.1

package/dist/shared/view.js

@@ -0,0 +1,981 @@
+/**
+ * Multi-table views, built out of **reference paths**.
+ *
+ * The `Filter` in adapter.ts addresses exactly one table and must keep doing
+ * so: it is the shape every read goes through, and widening it to carry joins
+ * would put join-building into every code path that filters anything. So the
+ * multi-table story is a separate idea rather than a bigger filter, and the
+ * idea is dot-walking:
+ *
+ *     invoice     customer_id.name contains Harbour
+ *     work_order  assigned_to.last_name = Petrova
+ *                 and customer_id.country_code.name = Australia
+ *
+ * A path is a chain of foreign keys starting at the base table, ending at a
+ * column. `customer_id.name` means "follow invoice.customer_id to customer,
+ * then take name". Nothing about it is guessed: the foreign key graph is
+ * already introspected, so every hop is derivable, checkable, and reversible
+ * into SQL — a path compiles to a LEFT JOIN chain and a qualified column.
+ *
+ * One mechanism answers three separate questions. Filtering across a long
+ * walk, showing a field from a related table, and the composer UI are all the
+ * same thing seen from three angles; the composer is a visual editor for the
+ * path set.
+ *
+ * Two properties are load-bearing and are pinned by tests:
+ *
+ *   - **LEFT JOIN, never INNER.** A null foreign key must leave the base row
+ *     in the result with nulls beside it. A composer that quietly drops rows
+ *     is worse than no composer at all, because the number it shows you is
+ *     wrong in a direction you cannot see.
+ *   - **Every value is a bound parameter.** Only identifiers are ever quoted
+ *     into the text, and they are quoted by the dialect's `SqlStyle`. The
+ *     WHERE clause is still built by `buildWhere`, which now takes an
+ *     identifier resolver so a path can become `"customer_1"."name"` without
+ *     a second predicate builder existing to disagree with the first.
+ */
+import { ANSI_STYLE, buildWhere, clampLimit, clampOffset, } from '../adapters/adapter.js';
+import { findTable, referencesFrom, } from './schema.js';
+import { parseQuery } from './query.js';
+/**
+ * How many foreign keys a path may follow.
+ *
+ * A cap is not a nicety: `work_order.parent_id` points at `work_order`, so the
+ * path space is infinite and any breadth-first enumeration of it runs forever.
+ * Four hops is past the point where anyone can still read the result, and the
+ * limit is stated in the error rather than left to be discovered.
+ */
+export const MAX_PATH_DEPTH = 4;
+/* ---------- errors ---------- */
+/**
+ * A path that does not resolve, with the segment that failed.
+ *
+ * The segment matters more than the path: `customer_id.country_code.nmae` is
+ * four words of which one is wrong, and an error that repeats the whole path
+ * makes you find the wrong one yourself.
+ */
+export class PathError extends Error {
+    path;
+    segment;
+    index;
+    constructor(message, path, segment, 
+    /** Index of the failing segment within the path, 0-based. */
+    index) {
+        super(message);
+        this.path = path;
+        this.segment = segment;
+        this.index = index;
+        this.name = 'PathError';
+    }
+}
+/** Levenshtein distance, capped. Only ever used to suggest a near miss. */
+function distance(a, b) {
+    if (Math.abs(a.length - b.length) > 3)
+        return 99;
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let last = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, last + (a[i - 1] === b[j - 1] ? 0 : 1));
+            last = tmp;
+        }
+    }
+    return prev[b.length];
+}
+function nearest(name, candidates) {
+    const near = candidates
+        .map((c) => ({ c, d: distance(name.toLowerCase(), c.toLowerCase()) }))
+        .sort((a, b) => a.d - b.d)[0];
+    return near && near.d <= 3 ? near.c : undefined;
+}
+/** A short list for an error message; long lists help nobody. */
+function shortList(items) {
+    return items.length > 6 ? `${items.slice(0, 6).join(', ')}, …` : items.join(', ');
+}
+/* ---------- hops ---------- */
+/**
+ * What a hop is called in a path.
+ *
+ * A single-column foreign key is named by its column, which is what anyone
+ * would write and what the composer shows. A composite key has no single
+ * column to name it, so its columns are joined with `+` — deterministic,
+ * derivable from the model alone, and impossible to confuse with a column
+ * name because `+` is not legal in one.
+ */
+export function hopName(fk) {
+    return fk.from.columns.length === 1 ? fk.from.columns[0] : fk.from.columns.join('+');
+}
+/** Every forward hop available from a table, in a stable order. */
+export function hopsFrom(schema, tableId) {
+    const table = findTable(schema, tableId);
+    return referencesFrom(schema, tableId).map((fk) => ({
+        name: hopName(fk),
+        fk,
+        target: fk.to.table,
+        optional: fk.from.columns.some((c) => table?.columns.find((col) => col.name === c)?.nullable !== false),
+    }));
+}
+/**
+ * Resolve a path against the schema, or explain precisely why it does not.
+ *
+ * Every hop is checked against the foreign key graph, so an unknown segment is
+ * an error here rather than a database exception later — or, far worse, a
+ * silently empty result that looks like a table with nothing in it.
+ */
+export function resolvePath(schema, baseId, path) {
+    const raw = String(path ?? '').trim();
+    if (!raw)
+        throw new PathError('A path cannot be empty.', raw, '', 0);
+    const segments = raw.split('.');
+    const blank = segments.findIndex((s) => s.trim() === '');
+    if (blank !== -1) {
+        throw new PathError(`"${raw}" has an empty segment — two dots in a row, or a trailing dot.`, raw, '', blank);
+    }
+    const hopCount = segments.length - 1;
+    if (hopCount > MAX_PATH_DEPTH) {
+        throw new PathError(`"${raw}" follows ${hopCount} references; at most ${MAX_PATH_DEPTH} are allowed. ` +
+            'Deeper walks are usually two views rather than one.', raw, segments[MAX_PATH_DEPTH], MAX_PATH_DEPTH);
+    }
+    let table = findTable(schema, baseId);
+    if (!table) {
+        throw new PathError(`No table called "${baseId}" in this database.`, raw, segments[0], 0);
+    }
+    const hops = [];
+    const hopNames = [];
+    for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i];
+        const available = hopsFrom(schema, table.id);
+        const matches = available.filter((h) => h.name === segment || h.fk.name === segment);
+        if (!matches.length) {
+            /* A real column that simply is not a reference is the commonest
+               mistake, and deserves its own sentence: "total is not a reference"
+               beats "total is not one of customer_id, sold_by". */
+            const isColumn = table.columns.some((c) => c.name === segment);
+            const names = available.map((h) => h.name);
+            const suggestion = nearest(segment, names);
+            const hint = suggestion
+                ? ` Did you mean "${suggestion}"?`
+                : names.length
+                    ? ` ${table.name} references: ${shortList(names)}.`
+                    : ` ${table.name} has no foreign keys.`;
+            throw new PathError(isColumn
+                ? `"${segment}" is a column on ${table.name}, not a reference, so nothing can follow it.${hint}`
+                : `"${segment}" is not a reference on ${table.name}.${hint}`, raw, segment, i);
+        }
+        if (matches.length > 1) {
+            throw new PathError(`"${segment}" is ambiguous on ${table.name} — ${matches.length} foreign keys match. ` +
+                `Name the constraint instead: ${shortList(matches.map((m) => m.fk.name))}.`, raw, segment, i);
+        }
+        const next = findTable(schema, matches[0].target);
+        if (!next) {
+            throw new PathError(`"${segment}" points at "${matches[0].target}", which is not in this schema.`, raw, segment, i);
+        }
+        hops.push(matches[0].fk);
+        hopNames.push(matches[0].name);
+        table = next;
+    }
+    const last = segments[segments.length - 1];
+    const column = table.columns.find((c) => c.name === last) ??
+        table.columns.find((c) => c.name.toLowerCase() === last.toLowerCase());
+    if (!column) {
+        const suggestion = nearest(last, table.columns.map((c) => c.name));
+        throw new PathError(`"${last}" is not a column on ${table.name}.${suggestion ? ` Did you mean "${suggestion}"?` : ''}`, raw, last, segments.length - 1);
+    }
+    return { path: raw, hops, hopNames, table, column };
+}
+/** Every foreign key pointing at a table: the "what refers to me" direction. */
+export function backrefsTo(schema, tableId) {
+    return schema.foreignKeys
+        .filter((fk) => fk.to.table === tableId)
+        .map((fk) => ({ name: fk.name, fk, child: fk.from.table }));
+}
+const AGGREGATE_FNS = ['count', 'sum', 'min', 'max', 'avg'];
+export function resolveAggregate(schema, baseId, aggregate) {
+    const on = (aggregate.on ?? '').trim();
+    const fail = (message, segment) => {
+        throw new PathError(message, aggregate.via, segment, 0);
+    };
+    if (!AGGREGATE_FNS.includes(aggregate.fn)) {
+        fail(`"${String(aggregate.fn)}" is not a summary. Use one of: ${AGGREGATE_FNS.join(', ')}.`, String(aggregate.fn));
+    }
+    /* The parent is the base table, or whatever a path prefix reaches. Resolved
+       by resolving a path *through* it — the same code, so a prefix that is not
+       a real chain of keys fails here exactly as it would anywhere else. */
+    const parent = tableAtPrefix(schema, baseId, on);
+    if (!parent) {
+        fail(on
+            ? `"${on}" is not a chain of references from ${baseId}.`
+            : `No table called "${baseId}" in this database.`, on || baseId);
+    }
+    const candidates = backrefsTo(schema, parent.id);
+    const match = candidates.find((b) => b.name === aggregate.via) ??
+        candidates.find((b) => `${b.child}.${b.fk.from.columns.join('+')}` === aggregate.via);
+    if (!match) {
+        fail(`Nothing called "${aggregate.via}" points at ${parent.name}.` +
+            (candidates.length
+                ? ` It is referred to by: ${shortList(candidates.map((c) => c.name))}.`
+                : ' Nothing refers to it.'), aggregate.via);
+    }
+    const child = findTable(schema, match.child);
+    if (!child)
+        fail(`"${match.child}" is not in this schema.`, aggregate.via);
+    let column;
+    if (aggregate.fn !== 'count') {
+        if (!aggregate.column) {
+            fail(`${aggregate.fn} needs a column on ${child.name} to summarise.`, aggregate.via);
+        }
+        column = child.columns.find((c) => c.name === aggregate.column);
+        if (!column) {
+            const suggestion = nearest(aggregate.column, child.columns.map((c) => c.name));
+            fail(`"${aggregate.column}" is not a column on ${child.name}.${suggestion ? ` Did you mean "${suggestion}"?` : ''}`, aggregate.column);
+        }
+    }
+    const subject = `${on ? `${on}.` : ''}${child.name}${column ? `.${column.name}` : ''}`;
+    return {
+        aggregate,
+        fk: match.fk,
+        child: child,
+        parent: parent,
+        on,
+        column,
+        name: aggregate.alias?.trim() || `${aggregate.fn}(${subject})`,
+    };
+}
+/** The table a chain of hop names lands on. Empty prefix is the base itself. */
+export function tableAtPrefix(schema, baseId, prefix) {
+    let table = findTable(schema, baseId);
+    if (!prefix)
+        return table;
+    for (const segment of prefix.split('.')) {
+        if (!table)
+            return undefined;
+        const hop = hopsFrom(schema, table.id).find((h) => h.name === segment || h.fk.name === segment);
+        if (!hop)
+            return undefined;
+        table = findTable(schema, hop.target);
+    }
+    return table;
+}
+/** Resolve without throwing — for callers collecting several errors at once. */
+export function tryResolvePath(schema, baseId, path) {
+    try {
+        return { resolved: resolvePath(schema, baseId, path) };
+    }
+    catch (err) {
+        if (err instanceof PathError)
+            return { error: err };
+        throw err;
+    }
+}
+/**
+ * Alias generation.
+ *
+ * Two requirements pull in opposite directions. Aliases must never collide —
+ * `work_order` in the demo has three separate references to `employee`, so a
+ * scheme keyed on the target table alone produces three joins all called
+ * `employee` and a statement that does not parse. And they must be stable, so
+ * the same view compiles to the same SQL every time and a diff of the explain
+ * panel means something.
+ *
+ * Both fall out of keying on the *path prefix* rather than the table: a prefix
+ * identifies a join uniquely, so the same path used twice reuses one join and
+ * two paths through the same table get two. The readable table name is kept as
+ * a prefix and made unique by an ordinal assigned in first-use order.
+ */
+export class JoinPlan {
+    schema;
+    style;
+    joins = [];
+    byPrefix = new Map();
+    n = 0;
+    constructor(schema, base, style) {
+        this.schema = schema;
+        this.style = style;
+        this.byPrefix.set('', alias(base.name, 0));
+    }
+    get baseAlias() {
+        return this.byPrefix.get('');
+    }
+    /** The alias for a path prefix, creating the join chain if it is new. */
+    aliasFor(hops, hopNames) {
+        let prefix = '';
+        for (let i = 0; i < hops.length; i++) {
+            prefix = prefix ? `${prefix}.${hopNames[i]}` : hopNames[i];
+            /* Already planned: the same path used twice must reuse one join, not
+               add a second copy of the same table under a different alias. */
+            if (this.byPrefix.has(prefix))
+                continue;
+            const target = findTable(this.schema, hops[i].to.table);
+            this.byPrefix.set(prefix, alias(target.name, ++this.n));
+            this.joins.push({ alias: this.byPrefix.get(prefix), table: target.id, path: prefix });
+        }
+        return this.byPrefix.get(prefix) ?? this.baseAlias;
+    }
+    /** The fully qualified, quoted SQL for a resolved path's final column. */
+    qualify(resolved) {
+        const owner = this.aliasFor(resolved.hops, resolved.hopNames);
+        return `${this.style.quote(owner)}.${this.style.quote(resolved.column.name)}`;
+    }
+    /** The alias of a path prefix that has already been planned, or the base. */
+    aliasOfPrefix(prefix) {
+        return this.byPrefix.get(prefix) ?? this.baseAlias;
+    }
+    /**
+     * A fresh alias for something that is not a join — a subquery's table.
+     *
+     * It draws from the same counter as the joins, which is what guarantees a
+     * correlated subquery over `employee` cannot pick the alias a LEFT JOIN
+     * over `employee` is already using. Two `employee_3`s in one statement is
+     * a self-join nobody asked for, and the wrong answer rather than an error.
+     */
+    subAlias(name) {
+        return alias(name, ++this.n);
+    }
+    /**
+     * The JOIN clauses, in the order the aliases were created.
+     *
+     * Order matters for more than tidiness: a join may only reference an alias
+     * introduced before it, and creation order is exactly path order, so a
+     * nested hop always follows the hop it hangs off.
+     */
+    clauses() {
+        return this.joins.map((join) => {
+            const parts = join.path.split('.');
+            const parentPrefix = parts.slice(0, -1).join('.');
+            const parent = this.byPrefix.get(parentPrefix);
+            const fk = this.fkFor(join.path);
+            const target = findTable(this.schema, join.table);
+            /* Every column of the key, not just the first. A composite foreign key
+               joined on one column is a cross product wearing a join's clothes. */
+            const on = fk.to.columns
+                .map((toCol, i) => `${this.style.quote(join.alias)}.${this.style.quote(toCol)} = ` +
+                `${this.style.quote(parent)}.${this.style.quote(fk.from.columns[i] ?? fk.from.columns[0])}`)
+                .join(' AND ');
+            /* LEFT, always. An INNER JOIN here would drop every base row whose
+               foreign key is null — silently, and in a direction that looks like
+               the data simply is not there. */
+            return `  LEFT JOIN ${qualifiedTable(this.schema, target.id, this.style)} ${this.style.quote(join.alias)} ON ${on}`;
+        });
+    }
+    fkChain = new Map();
+    /** Remember which key produced each join, so `clauses` can rebuild the ON. */
+    record(path, fk) {
+        if (!this.fkChain.has(path))
+            this.fkChain.set(path, fk);
+    }
+    fkFor(path) {
+        return this.fkChain.get(path);
+    }
+}
+/** Alias text: the table's own name, made unique by an ordinal. */
+function alias(name, n) {
+    /* Truncated because Postgres silently cuts identifiers at 63 bytes, and a
+       silent cut is exactly how two long table names become one alias. */
+    const safe = name.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 40) || 't';
+    return `${safe}_${n}`;
+}
+/** A table reference: two identifiers when the dialect has schemas, one when not. */
+export function qualifiedTable(schema, tableId, style) {
+    const table = findTable(schema, tableId);
+    if (!table)
+        return style.quote(tableId);
+    return table.schema ? `${style.quote(table.schema)}.${style.quote(table.name)}` : style.quote(table.name);
+}
+/**
+ * Compile a view to one parameterised SELECT.
+ *
+ * Order of work is deliberate and is what makes the output deterministic:
+ * columns, then the filter, then the sort. Aliases are handed out on first
+ * use, so the same view always produces the same statement.
+ */
+export function compileView(schema, view, style, offset = 0) {
+    const base = findTable(schema, view.base);
+    if (!base) {
+        throw new PathError(`No table called "${view.base}" in this database, so the view has nothing to start from.`, view.base, view.base, 0);
+    }
+    const plan = new JoinPlan(schema, base, style);
+    /* Resolution and alias creation are one step, because a join only exists
+       once some path needs it. Recording the key alongside keeps `clauses` from
+       having to re-resolve anything. */
+    const qualify = (path) => {
+        const resolved = resolvePath(schema, view.base, path);
+        let prefix = '';
+        for (let i = 0; i < resolved.hops.length; i++) {
+            prefix = prefix ? `${prefix}.${resolved.hopNames[i]}` : resolved.hopNames[i];
+            plan.record(prefix, resolved.hops[i]);
+        }
+        return plan.qualify(resolved);
+    };
+    /* An empty column list means the base table's own columns. Expanding it
+       here rather than emitting `SELECT *` keeps the result's column list
+       knowable without running the statement, which is what the composer's
+       field checklist reads. */
+    const wanted = view.columns?.length
+        ? view.columns
+        : base.columns.map((c) => ({ path: c.name }));
+    const seen = new Map();
+    const columns = [];
+    const select = [];
+    for (const col of wanted) {
+        const resolved = resolvePath(schema, view.base, col.path);
+        const sql = qualify(col.path);
+        /* Two paths can legitimately end on the same name — `customer_id.name`
+           and `sold_by.name` are both "name" if aliased carelessly. The path is
+           already unique, so it is the default; an explicit collision gets a
+           numeric suffix rather than one column quietly overwriting the other. */
+        let name = col.alias?.trim() || resolved.path;
+        const count = seen.get(name) ?? 0;
+        seen.set(name, count + 1);
+        if (count)
+            name = `${name}_${count + 1}`;
+        columns.push({
+            path: resolved.path,
+            name,
+            table: resolved.table.id,
+            column: resolved.column.name,
+            type: resolved.column.type,
+            /* A column on a joined table is nullable in the result even when the
+               column itself is NOT NULL: the LEFT JOIN can produce no row at all.
+               Saying otherwise would have the UI render a real null as an error. */
+            nullable: resolved.column.nullable || resolved.hops.length > 0,
+            primaryKey: resolved.column.primaryKey,
+            hops: resolved.hops.length,
+        });
+        select.push(`${sql} AS ${style.quote(name)}`);
+    }
+    /* Aggregates come after the plain columns, and after them on purpose: a
+       summary hanging off a joined table needs that join's alias to exist, and
+       resolving columns first is what puts it there. */
+    for (const aggregate of view.aggregates ?? []) {
+        const resolved = resolveAggregate(schema, view.base, aggregate);
+        /* The parent side is a path prefix, so an aggregate can hang off a joined
+           table as easily as off the base — "invoice lines on the invoice this
+           shipment belongs to" is the same construction one hop along. */
+        if (resolved.on) {
+            /* Qualifying any column on the parent is what plans the joins leading
+               to it and records their keys. Doing it through the same `qualify`
+               the columns use is deliberate: two ways of planning a join is two
+               ways for the aliases to disagree. */
+            qualify(`${resolved.on}.${resolved.parent.columns[0].name}`);
+        }
+        const parentAlias = resolved.on ? plan.aliasOfPrefix(resolved.on) : plan.baseAlias;
+        const childAlias = plan.subAlias(resolved.child.name);
+        const on = resolved.fk.to.columns
+            .map((toCol, i) => `${style.quote(childAlias)}.${style.quote(resolved.fk.from.columns[i] ?? resolved.fk.from.columns[0])} = ` +
+            `${style.quote(parentAlias)}.${style.quote(toCol)}`)
+            .join(' AND ');
+        /* COUNT(*) rather than COUNT(column): a column count skips nulls, which
+           turns "how many parts" into "how many parts have a quantity" without
+           saying so. SUM over no rows is left as NULL rather than coerced to 0 —
+           a work order with no parts has no total, and 0 is a claim about money
+           that nobody made. */
+        const expression = resolved.aggregate.fn === 'count'
+            ? 'COUNT(*)'
+            : `${resolved.aggregate.fn.toUpperCase()}(${style.quote(childAlias)}.${style.quote(resolved.column.name)})`;
+        let name = resolved.name;
+        const count = seen.get(name) ?? 0;
+        seen.set(name, count + 1);
+        if (count)
+            name = `${name}_${count + 1}`;
+        select.push(`(SELECT ${expression} FROM ${qualifiedTable(schema, resolved.child.id, style)} ${style.quote(childAlias)}`
+            + ` WHERE ${on}) AS ${style.quote(name)}`);
+        columns.push({
+            path: resolved.name,
+            name,
+            table: resolved.child.id,
+            column: resolved.column?.name ?? '*',
+            type: resolved.aggregate.fn === 'count' ? 'integer' : (resolved.column?.type ?? 'integer'),
+            // COUNT is never null; every other summary is, over an empty child set.
+            nullable: resolved.aggregate.fn !== 'count',
+            primaryKey: false,
+            hops: resolved.on ? resolved.on.split('.').length : 0,
+            aggregate: resolved.aggregate.fn,
+        });
+    }
+    /* The filter is compiled by `buildWhere`, not beside it. One predicate
+       builder means one place where a value could stop being a parameter. */
+    const conditions = view.filter?.groups.length
+        ? {
+            groups: view.filter.groups.map((group) => group.map((c) => ({ column: c.path, op: c.op, value: c.value }))),
+        }
+        : undefined;
+    const where = buildWhere(conditions, style, 1, qualify);
+    const aliasNames = new Set((view.aggregates ?? []).map((a) => a.alias?.trim()).filter(Boolean));
+    const order = (view.orderBy ?? []).map((o) => {
+        if (o.alias) {
+            /* Refused by name rather than left to the engine: SQLite quietly
+               treats an unknown ORDER BY identifier as a new error anyway, but
+               "no such column: invoicez" would not say the fix is the alias two
+               words back. */
+            if (!aliasNames.has(o.path)) {
+                throw new PathError(`"${o.path}" is not an aggregate alias on this view.`, o.path, o.path, 0);
+            }
+            return `${style.quote(o.path)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`;
+        }
+        return `${qualify(o.path)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`;
+    });
+    const limit = clampLimit(view.limit);
+    const skip = clampOffset(offset);
+    /* Placeholder numbering continues across the whole statement, which is the
+       one thing Postgres needs and SQLite does not — and the exact place a join
+       builder gets it wrong, because the joins sit between the SELECT list and
+       the WHERE clause and are easy to count as if they carried parameters. */
+    const n = where.params.length;
+    const lines = [
+        `SELECT ${select.join(',\n       ')}`,
+        `  FROM ${qualifiedTable(schema, base.id, style)} ${style.quote(plan.baseAlias)}`,
+        ...plan.clauses(),
+    ];
+    if (where.text)
+        lines.push(where.text.replace(/^ WHERE /, ' WHERE '));
+    if (order.length)
+        lines.push(` ORDER BY ${order.join(', ')}`);
+    lines.push(` LIMIT ${style.placeholder(n + 1)} OFFSET ${style.placeholder(n + 2)}`);
+    return {
+        text: lines.join('\n'),
+        params: [...where.params, limit, skip],
+        columns,
+        joins: plan.joins,
+        limit,
+    };
+}
+/* ---------- the query language, over paths ----------
+
+   The composer's filter box takes the same language as the bar at the top,
+   because two languages for one idea is one too many. It is parsed by the
+   same parser, too: `parseQuery` already handles and/or, parentheses, quoting,
+   relative dates and per-column value coercion, and a second implementation
+   of those would be a second set of bugs.
+
+   The trick that makes it work is a *synthetic* table. `parseQuery` resolves
+   every field against a table's column list, so the base table is handed to it
+   with one extra column per path mentioned in the text, each carrying the
+   declared type of the column the path actually ends on. Coercion, date
+   handling and "did you mean" then work over paths for free.
+
+   Paths are resolved on demand rather than enumerated: `work_order.parent_id`
+   points back at `work_order`, so the set of paths four hops deep is tens of
+   thousands of entries and building it per keystroke would be absurd. */
+/* One segment of a path: a column name, or — for a composite key — the
+   columns of it joined with `+`, exactly as `hopName` writes them.
+
+   `+` has to be admitted here as well as in `parseQuery`'s FIELD, or the two
+   disagree about where a token begins: the scanner reads only `line_no.sku`
+   out of `invoice_id+line_no.sku`, builds the synthetic column for a path that
+   does not exist, and a composite hop becomes something you can show but never
+   filter. It is legal only *between* identifier characters, never leading —
+   a leading `+` would let a signed number start a path. */
+const SEGMENT = String.raw `[A-Za-z_$][\w$]*(?:\+[A-Za-z_$][\w$]*)*`;
+/* A dotted token. `@` and `+` are excluded from the lookbehind on purpose:
+   without `@`, `email = ops@harbour.example` reads its own value as a path and
+   reports a confident error about a table that was never mentioned; without
+   `+`, the tail of a composite hop matches on its own and reports the same
+   kind of confident error about half a key. */
+const DOTTED_TOKEN = new RegExp(String.raw `(?<![\w.$@+])(${SEGMENT}(?:\.${SEGMENT})+)`, 'g');
+/** What makes a token a *field* rather than a value: an operator after it. */
+const OPERATOR_AFTER = /^\s*(?:!=|<=|>=|=|<|>|\bcontains\b|\bstartswith\b|\bendswith\b|\blike\b|\bnot\s+in\b|\bin\b|\bis\b)/i;
+/** …or a word before it that can only be followed by a field. */
+const FIELD_BEFORE = /(?:^|[\s(,])(?:and|or|where|filter|show|select|sort|by)\s*$|(?:^|,)\s*$/i;
+/**
+ * Blank out quoted spans, keeping the length so offsets still line up.
+ *
+ * A quoted value is text by definition — `name = "Smith.Jones"` contains no
+ * path — and scanning into one produces errors about words the user never
+ * meant as fields.
+ */
+function maskQuoted(text) {
+    let out = '';
+    let quote = null;
+    for (const ch of text) {
+        if (quote) {
+            out += ch === quote ? ((quote = null), ch) : ' ';
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * Parse the composer's filter/clause text against a base table.
+ *
+ * Returns errors rather than throwing, because this runs on every keystroke
+ * and a half-typed path is the normal state of the input, not an exception.
+ */
+export function parseViewQuery(schema, baseId, text, now, options = {}) {
+    const empty = { filter: { groups: [] }, columns: [], orderBy: [], errors: [] };
+    const base = findTable(schema, baseId);
+    if (!base) {
+        return { ...empty, errors: [{ message: `No table called "${baseId}" in this database.` }] };
+    }
+    const body = String(text ?? '').trim();
+    if (!body)
+        return empty;
+    const errors = [];
+    const extra = [];
+    const added = new Set();
+    /* Paths already reported as broken. The synthetic table cannot contain
+       them, so the parser will reach them too and say "not a column on invoice"
+       — true, useless, and directly under a message that named the real
+       problem. Two errors for one mistake reads as two mistakes. */
+    const failed = new Set();
+    const scanned = maskQuoted(body);
+    for (const match of scanned.matchAll(DOTTED_TOKEN)) {
+        const path = match[1];
+        const start = match.index ?? 0;
+        /* Whether this token is being used as a field decides whether a failure
+           to resolve is worth reporting. In value position — `external_ref =
+           a.b` — a dotted word that is not a path is simply a value, and an error
+           about it would be noise on a query that is perfectly correct. */
+        const isField = OPERATOR_AFTER.test(scanned.slice(start + path.length)) ||
+            FIELD_BEFORE.test(scanned.slice(0, start));
+        if (added.has(path))
+            continue;
+        added.add(path);
+        const { resolved, error } = tryResolvePath(schema, baseId, path);
+        if (error) {
+            /* Located at the token so the composer can underline the right word.
+               The offset is into the filter text, and the caller shifts it. */
+            if (isField) {
+                errors.push({ message: error.message, at: start });
+                failed.add(path);
+            }
+            continue;
+        }
+        if (!resolved)
+            continue;
+        /* The synthetic column keeps the *declared* type of the real column, so
+           `signed_up = last 30 days` through a path behaves exactly as it does
+           on the base table. Nullability is widened because the join can miss. */
+        extra.push({
+            name: resolved.path,
+            type: resolved.column.type,
+            nullable: true,
+            primaryKey: false,
+            references: resolved.column.references,
+        });
+    }
+    /* Aggregate aliases join the synthetic table so `sort invoices desc`
+       parses — and only sort. A WHERE runs before the SELECT list exists, so
+       filtering by an alias is refused below with the reason, not with
+       "not a column", which is true and useless. */
+    const aliases = new Set(options.aggregateAliases ?? []);
+    for (const alias of aliases) {
+        if (!added.has(alias))
+            extra.push({ name: alias, type: 'NUMERIC', nullable: true, primaryKey: false });
+    }
+    const synthetic = {
+        ...schema,
+        tables: schema.tables.map((t) => t.id === base.id ? { ...t, columns: [...t.columns, ...extra] } : t),
+    };
+    /* The parser wants `<table> <clauses>`, which is also what the composer's
+       hint text shows, so the base name is prepended rather than the grammar
+       being special-cased. */
+    const offset = base.id.length + 1;
+    const parsed = parseQuery(`${base.id} ${body}`, { schema: synthetic, now });
+    for (const err of parsed.errors) {
+        if ([...failed].some((path) => err.message.includes(`"${path}"`)))
+            continue;
+        errors.push({ message: err.message, at: err.at === undefined ? undefined : Math.max(0, err.at - offset) });
+    }
+    const query = parsed.query;
+    if (!query)
+        return { ...empty, errors };
+    for (const group of query.filter.groups) {
+        for (const c of group) {
+            if (aliases.has(c.column)) {
+                errors.push({
+                    message: `"${c.column}" is an aggregate result, and a filter runs before it exists. `
+                        + 'Filter on the child table instead.',
+                });
+            }
+        }
+    }
+    for (const column of query.columns ?? []) {
+        if (aliases.has(column)) {
+            errors.push({ message: `"${column}" is already shown — the aggregate adds its own column.` });
+        }
+    }
+    return {
+        filter: {
+            groups: query.filter.groups.map((group) => group.map((c) => ({ path: c.column, op: c.op, value: c.value }))),
+        },
+        columns: query.columns,
+        orderBy: query.orderBy.map((o) => aliases.has(o.column)
+            ? { path: o.column, direction: o.direction, alias: true }
+            : { path: o.column, direction: o.direction }),
+        limit: query.limit,
+        errors,
+    };
+}
+/**
+ * How many rows the view matches, ignoring the page.
+ *
+ * A separate compilation rather than a wrapper around the other one, because
+ * the two differ in more than a keyword: the SELECT list, the ORDER BY and the
+ * page are all irrelevant here, and every aggregate in the view would be a
+ * correlated subquery evaluated per row for a number nobody reads.
+ *
+ * The count is exact rather than estimated, and it is *base rows* — which is
+ * only true because every join is to-one. That is the same property the whole
+ * design rests on: a view never multiplies, so counting it is counting the
+ * table it started from.
+ */
+export function compileViewCount(schema, view, style) {
+    const base = findTable(schema, view.base);
+    if (!base) {
+        throw new PathError(`No table called "${view.base}" in this database, so the view has nothing to start from.`, view.base, view.base, 0);
+    }
+    const plan = new JoinPlan(schema, base, style);
+    const qualify = (path) => {
+        const resolved = resolvePath(schema, view.base, path);
+        let prefix = '';
+        for (let i = 0; i < resolved.hops.length; i++) {
+            prefix = prefix ? `${prefix}.${resolved.hopNames[i]}` : resolved.hopNames[i];
+            plan.record(prefix, resolved.hops[i]);
+        }
+        return plan.qualify(resolved);
+    };
+    const conditions = view.filter?.groups.length
+        ? {
+            groups: view.filter.groups.map((group) => group.map((c) => ({ column: c.path, op: c.op, value: c.value }))),
+        }
+        : undefined;
+    const where = buildWhere(conditions, style, 1, qualify);
+    /* The joins are emitted after the WHERE clause has been built, because
+       building it is what discovers which joins the filter needs. */
+    const text = `SELECT COUNT(*) AS n\n  FROM ${qualifiedTable(schema, base.id, style)} ${style.quote(plan.baseAlias)}`
+        + (plan.clauses().length ? `\n${plan.clauses().join('\n')}` : '')
+        + where.text;
+    return { text, params: where.params };
+}
+/**
+ * Render a view as the SQL it will become, values inline.
+ *
+ * The mirror of `explain` in query.ts and used the same way: this string never
+ * reaches a database, and showing `"customer_1"."name" LIKE '%Harbour%'` next
+ * to the path that produced it is how someone learns what the composer is
+ * doing on their behalf.
+ */
+export function explainView(schema, view, style) {
+    const compiled = compileView(schema, view, style);
+    let i = 0;
+    return compiled.text.replace(/\$\d+|\?/g, () => sqlLiteral(compiled.params[i++]));
+}
+/**
+ * One parameter, written the way SQL would have to spell it.
+ *
+ * Exported because a breakdown explains itself the same way a view does, and
+ * two spellings of `NULL` — or two different ideas about escaping a quote —
+ * would show up as a difference between two panes that claim to be the same
+ * statement.
+ */
+export function sqlLiteral(value) {
+    if (value === null || value === undefined)
+        return 'NULL';
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return `'${String(value).replace(/'/g, "''")}'`;
+}
+/* ---------- config file support ----------
+
+   Views can be predefined in `tablewalk.json` beside `connections`, and are
+   validated the same strict way: a malformed entry is an error naming the
+   entry, never a silent skip. Quietly dropping a view someone wrote is the
+   worst outcome — they see a shorter list and no reason for it. */
+export function parseViewsConfig(raw, where) {
+    const views = raw?.views;
+    if (views === undefined)
+        return [];
+    if (!Array.isArray(views))
+        throw new Error(`${where}: "views" must be an array.`);
+    const seen = new Set();
+    return views.map((entry, i) => {
+        const at = `${where}: view ${i + 1}`;
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error(`${at} is not an object.`);
+        }
+        const v = entry;
+        if (typeof v.name !== 'string' || !v.name.trim())
+            throw new Error(`${at} has no "name".`);
+        /* A view may be written down instead of built out of objects. The text
+           form needs a schema to resolve, which a config file does not have, so
+           it is carried through and expanded when a connection is open — and any
+           error it holds is reported against that view rather than swallowed. */
+        const text = v.text === undefined ? undefined : String(v.text).trim();
+        if (v.text !== undefined && (typeof v.text !== 'string' || !text)) {
+            throw new Error(`${at} ("${v.name}") has a "text" that is not a non-empty string.`);
+        }
+        if (text && v.base !== undefined) {
+            throw new Error(`${at} ("${v.name}") has both "text" and "base". The text form already names its table.`);
+        }
+        if (!text && (typeof v.base !== 'string' || !v.base.trim())) {
+            throw new Error(`${at} ("${v.name}") has no "base" table.`);
+        }
+        const id = v.id === undefined ? `config-${slug(v.name)}` : String(v.id);
+        if (v.id !== undefined && (typeof v.id !== 'string' || !v.id.trim())) {
+            throw new Error(`${at} ("${v.name}") has an "id" that is not a non-empty string.`);
+        }
+        if (seen.has(id))
+            throw new Error(`${at} ("${v.name}") repeats the id "${id}".`);
+        seen.add(id);
+        const columns = parseColumns(v.columns, at, String(v.name));
+        const aggregates = parseAggregates(v.aggregates, at, String(v.name));
+        const filter = parseFilter(v.filter, at, String(v.name));
+        const orderBy = parseOrder(v.orderBy, at, String(v.name));
+        if (v.limit !== undefined && (typeof v.limit !== 'number' || !Number.isFinite(v.limit))) {
+            throw new Error(`${at} ("${v.name}") has a "limit" that is not a number.`);
+        }
+        if (v.connection !== undefined && typeof v.connection !== 'string') {
+            throw new Error(`${at} ("${v.name}") has a "connection" that is not a string.`);
+        }
+        return {
+            id,
+            name: v.name.trim(),
+            base: text ? text.trim().split(/\s+/)[0] : v.base.trim(),
+            text,
+            columns,
+            aggregates,
+            filter,
+            orderBy,
+            limit: v.limit,
+            connection: v.connection,
+            source: 'config',
+        };
+    });
+}
+function parseColumns(raw, at, name) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error(`${at} ("${name}") has "columns" that is not an array.`);
+    return raw.map((col, j) => {
+        const where = `${at} ("${name}"), column ${j + 1}`;
+        if (typeof col === 'string') {
+            if (!col.trim())
+                throw new Error(`${where} is empty.`);
+            return { path: col.trim() };
+        }
+        if (!col || typeof col !== 'object')
+            throw new Error(`${where} is not a string or an object.`);
+        const c = col;
+        if (typeof c.path !== 'string' || !c.path.trim())
+            throw new Error(`${where} has no "path".`);
+        if (c.alias !== undefined && (typeof c.alias !== 'string' || !c.alias.trim())) {
+            throw new Error(`${where} has an "alias" that is not a non-empty string.`);
+        }
+        return { path: c.path.trim(), alias: c.alias };
+    });
+}
+function parseAggregates(raw, at, name) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw))
+        throw new Error(`${at} ("${name}") has "aggregates" that is not an array.`);
+    return raw.map((entry, j) => {
+        const where = `${at} ("${name}"), aggregate ${j + 1}`;
+        if (!entry || typeof entry !== 'object')
+            throw new Error(`${where} is not an object.`);
+        const a = entry;
+        if (typeof a.fn !== 'string' || !AGGREGATE_FNS.includes(a.fn)) {
+            throw new Error(`${where} has an unknown "fn". Use one of: ${AGGREGATE_FNS.join(', ')}.`);
+        }
+        if (typeof a.via !== 'string' || !a.via.trim())
+            throw new Error(`${where} has no "via".`);
+        if (a.fn !== 'count' && (typeof a.column !== 'string' || !a.column.trim())) {
+            throw new Error(`${where} is a ${a.fn} and needs a "column" to summarise.`);
+        }
+        if (a.on !== undefined && typeof a.on !== 'string') {
+            throw new Error(`${where} has an "on" that is not a string.`);
+        }
+        if (a.alias !== undefined && (typeof a.alias !== 'string' || !a.alias.trim())) {
+            throw new Error(`${where} has an "alias" that is not a non-empty string.`);
+        }
+        return {
+            fn: a.fn,
+            via: a.via.trim(),
+            on: a.on,
+            column: typeof a.column === 'string' ? a.column.trim() : undefined,
+            alias: a.alias,
+        };
+    });
+}
+const OPS = [
+    '=', '!=', '>', '>=', '<', '<=', 'contains', 'startsWith', 'endsWith', 'like', 'in', 'isNull', 'isNotNull',
+];
+function parseFilter(raw, at, name) {
+    if (raw === undefined)
+        return undefined;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`${at} ("${name}") has a "filter" that is not an object.`);
+    }
+    const groups = raw.groups;
+    if (!Array.isArray(groups))
+        throw new Error(`${at} ("${name}") has a "filter" with no "groups" array.`);
+    return {
+        groups: groups.map((group, g) => {
+            if (!Array.isArray(group))
+                throw new Error(`${at} ("${name}"), filter group ${g + 1} is not an array.`);
+            return group.map((cond, c) => {
+                const where = `${at} ("${name}"), filter group ${g + 1} condition ${c + 1}`;
+                if (!cond || typeof cond !== 'object')
+                    throw new Error(`${where} is not an object.`);
+                const x = cond;
+                if (typeof x.path !== 'string' || !x.path.trim())
+                    throw new Error(`${where} has no "path".`);
+                if (typeof x.op !== 'string' || !OPS.includes(x.op)) {
+                    throw new Error(`${where} has an unknown operator "${String(x.op)}". Use one of: ${OPS.join(', ')}.`);
+                }
+                return { path: x.path.trim(), op: x.op, value: x.value };
+            });
+        }),
+    };
+}
+function parseOrder(raw, at, name) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw))
+        throw new Error(`${at} ("${name}") has an "orderBy" that is not an array.`);
+    return raw.map((entry, j) => {
+        const where = `${at} ("${name}"), orderBy ${j + 1}`;
+        if (typeof entry === 'string')
+            return { path: entry, direction: 'asc' };
+        if (!entry || typeof entry !== 'object')
+            throw new Error(`${where} is not a string or an object.`);
+        const o = entry;
+        if (typeof o.path !== 'string' || !o.path.trim())
+            throw new Error(`${where} has no "path".`);
+        const direction = o.direction === undefined ? 'asc' : o.direction;
+        if (direction !== 'asc' && direction !== 'desc') {
+            throw new Error(`${where} has a "direction" that is not "asc" or "desc".`);
+        }
+        return { path: o.path.trim(), direction };
+    });
+}
+function slug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'view';
+}
+/**
+ * Check a view against a schema without running it.
+ *
+ * Used by `GET /api/views` so a config view naming a table that does not exist
+ * on this connection is listed *with its reason*, rather than either vanishing
+ * or blowing up the endpoint for every other view beside it.
+ */
+export function validateView(schema, view) {
+    try {
+        /* Any style will do: this compiles to throw away the text and keep the
+           error, and no dialect refuses a view another accepts. */
+        compileView(schema, view, ANSI_STYLE);
+        return undefined;
+    }
+    catch (err) {
+        return err.message;
+    }
+}