tablewalk 0.0.1

package/dist/shared/query.js

@@ -0,0 +1,831 @@
+/**
+ * A small query language for browsing.
+ *
+ *   customers country = "Australia" and credit_limit > 1000
+ *   invoices where total >= 50 sort invoice_date desc limit 20
+ *   employees title contains manager show first_name, last_name, email
+ *   orders order_date = last 30 days
+ *
+ * The table comes first, because that is how people say it out loud. Every
+ * other clause is optional, and `where` / `order by` are accepted as aliases
+ * for `filter` / `sort` so SQL habits do not have to be unlearned.
+ *
+ * Why a language at all, when the thing underneath is SQL?
+ *
+ * Because this one compiles to a `Filter` — a structure — and never to SQL
+ * text. The adapter turns that structure into a parameterised statement, so
+ * there is no path from what a user types to what the database parses as
+ * syntax. A tool that let people type SQL directly would have to either trust
+ * them or write a SQL parser to untrust them; this sidesteps both by making
+ * the dangerous shape unrepresentable.
+ *
+ * Two things fall out of it for free. Because the compiler holds the schema,
+ * a mistyped column is an error at the caret instead of a database exception
+ * — and, worse, a mistyped *value* on a real column can be caught too. And
+ * because the compiled statement is shown next to the query, the language
+ * teaches SQL rather than hiding it.
+ */
+import { MAX_LIMIT } from '../adapters/adapter.js';
+import { LIKE_ESCAPE, likePattern } from './like.js';
+import { columnKind, findTable, } from './schema.js';
+/**
+ * What can appear in a field position.
+ *
+ * `\w`, plus `.` for reference paths, `$` because some dialects allow it in
+ * identifiers, and `+` for the composite-hop syntax a view uses:
+ * `invoice_id+line_no.sku` follows a two-column foreign key. Without `+`
+ * those hops were addressable only by their constraint name, which is a
+ * database artefact nobody wants to type.
+ *
+ * `+` is safe to admit because the language has no arithmetic — there is
+ * nothing it could otherwise have meant — and it cannot appear in a real
+ * column name, so it can never be ambiguous with one.
+ */
+const FIELD = String.raw `[\w.$+]+`;
+/** Operator words users type, mapped to the filter's operators. */
+const OPERATORS = {
+    '=': '=',
+    '!=': '!=',
+    '<': '<',
+    '<=': '<=',
+    '>': '>',
+    '>=': '>=',
+    contains: 'contains',
+    startswith: 'startsWith',
+    endswith: 'endsWith',
+    like: 'like',
+    in: 'in',
+};
+/* Re-exported: the classifier moved to schema.ts to keep adapters from
+   importing this module, but callers here have always got it from here. */
+export { columnKind } from './schema.js';
+export const QUERY_OPERATORS = Object.keys(OPERATORS);
+export const QUERY_KEYWORDS = ['filter', 'where', 'show', 'sort', 'order by', 'limit', 'and', 'or', 'desc', 'asc'];
+/* Written as a range and compiled as two comparisons — see `between` in
+   parseCondition. Listed separately because it is an operator to whoever is
+   typing, whatever it becomes afterwards. */
+export const QUERY_RANGE_OPERATOR = 'between';
+function startOfDay(d) {
+    const c = new Date(d);
+    c.setHours(0, 0, 0, 0);
+    return c;
+}
+function addDays(d, n) {
+    const c = new Date(d);
+    c.setDate(c.getDate() + n);
+    return c;
+}
+/**
+ * `now` is a parameter rather than a call to the clock, so the compiler is a
+ * pure function of its inputs. That is what makes the tests below able to
+ * assert on an exact timestamp instead of a range.
+ */
+export function dateWindow(phrase, now) {
+    const p = phrase.toLowerCase().trim();
+    const today = startOfDay(now);
+    const fixed = {
+        today: [today, addDays(today, 1)],
+        yesterday: [addDays(today, -1), today],
+        tomorrow: [addDays(today, 1), addDays(today, 2)],
+    };
+    if (fixed[p])
+        return { label: p, start: fixed[p][0], end: fixed[p][1] };
+    if (p === 'this week' || p === 'last week') {
+        // Weeks start Monday, which is what a working calendar means by "this week".
+        const dow = (today.getDay() + 6) % 7;
+        const monday = addDays(today, -dow);
+        const start = p === 'this week' ? monday : addDays(monday, -7);
+        return { label: p, start, end: addDays(start, 7) };
+    }
+    if (p === 'this month' || p === 'last month') {
+        const base = new Date(today.getFullYear(), today.getMonth() + (p === 'last month' ? -1 : 0), 1);
+        const end = new Date(base.getFullYear(), base.getMonth() + 1, 1);
+        return { label: p, start: base, end };
+    }
+    if (p === 'this year' || p === 'last year') {
+        const year = today.getFullYear() + (p === 'last year' ? -1 : 0);
+        return { label: p, start: new Date(year, 0, 1), end: new Date(year + 1, 0, 1) };
+    }
+    const span = p.match(/^(last|next)\s+(\d+)\s+(hour|day|week|month|year)s?$/);
+    if (span) {
+        const [, dir, amountRaw, unit] = span;
+        const amount = Number(amountRaw);
+        const past = dir === 'last';
+        if (unit === 'hour') {
+            const ms = amount * 3600_000;
+            return past
+                ? { label: p, start: new Date(now.getTime() - ms), end: now }
+                : { label: p, start: now, end: new Date(now.getTime() + ms) };
+        }
+        const days = unit === 'week' ? amount * 7 : amount;
+        if (unit === 'month' || unit === 'year') {
+            /* Counted in calendar units rather than in days, so `last 3 months`
+               from the 31st lands on a date that exists and `last 1 year` from a
+               leap day does not drift. `Date` normalises an overflowing day of the
+               month, which is the behaviour wanted here: three months before the
+               31st of May is the 28th of February, not a date in March. */
+            const months = unit === 'year' ? amount * 12 : amount;
+            const other = new Date(today.getFullYear(), today.getMonth() + (past ? -months : months), today.getDate());
+            return past ? { label: p, start: other, end: addDays(today, 1) } : { label: p, start: today, end: other };
+        }
+        return past
+            ? { label: p, start: addDays(today, -days), end: addDays(today, 1) }
+            : { label: p, start: today, end: addDays(today, days) };
+    }
+    return undefined;
+}
+/**
+ * Split on a keyword at depth zero, honouring quotes and parentheses so that
+ * `a and (b or c)` and `name = "Smith and Sons"` both survive intact.
+ */
+/** Whether `word` sits at `i` as a whole word rather than inside a longer one. */
+function isWord(text, i, word) {
+    const before = text[i - 1];
+    const after = text[i + word.length];
+    return (before === undefined || /[\s(]/.test(before))
+        && (after === undefined || /[\s(]/.test(after));
+}
+function splitTopLevel(text, keyword, offset) {
+    const parts = [];
+    let current = '';
+    let start = 0;
+    let quote = null;
+    let depth = 0;
+    /** Set when a `between` is open and its `and` has not been seen yet. */
+    let pendingBetween = false;
+    const lower = text.toLowerCase();
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quote) {
+            /* An escaped character cannot end the quote — the same rule
+               `maskQuotedValues` applies below, and the reason this loop needed it:
+               without it `name = "a \\" and b"` closed its quote at the escaped
+               one, found a top-level `and` inside the value, and split a single
+               condition in half. Two quote scanners in one file disagreeing about
+               whether the grammar has escapes. */
+            if (ch === '\\' && i + 1 < text.length) {
+                current += ch + text[i + 1];
+                i += 1;
+                continue;
+            }
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '(')
+            depth++;
+        if (ch === ')')
+            depth = Math.max(0, depth - 1);
+        /* `between 10 and 20` contains an `and` that joins a range rather than two
+           conditions. Splitting there cut one condition in half and left `20` as
+           a condition of its own, which parsed as nothing and reported an error
+           about `20` — so the word had to be tracked rather than the grammar
+           reworded. The first top-level `and` after a `between` belongs to it. */
+        if (keyword === 'and' && lower.startsWith('between', i) && isWord(text, i, 'between')) {
+            pendingBetween = true;
+        }
+        const atBoundary = depth === 0 &&
+            lower.startsWith(keyword, i) &&
+            (i === 0 || /[\s)]/.test(text[i - 1])) &&
+            /[\s(]/.test(text[i + keyword.length] ?? ' ');
+        if (atBoundary && pendingBetween) {
+            pendingBetween = false;
+            current += text[i];
+            continue;
+        }
+        if (atBoundary) {
+            parts.push({ text: current, at: offset + start });
+            i += keyword.length - 1;
+            current = '';
+            start = i + 1;
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim())
+        parts.push({ text: current, at: offset + start });
+    return parts.filter((p) => p.text.trim());
+}
+/** Strip one layer of wrapping parentheses, when they wrap the whole term. */
+function unwrap(text) {
+    const t = text.trim();
+    const lead = text.length - text.trimStart().length;
+    if (!t.startsWith('(') || !t.endsWith(')'))
+        return { text: t, shift: lead };
+    let depth = 0;
+    for (let i = 0; i < t.length; i++) {
+        if (t[i] === '(')
+            depth++;
+        else if (t[i] === ')') {
+            depth--;
+            if (depth === 0 && i < t.length - 1)
+                return { text: t, shift: lead }; // `)(` — not one wrap
+        }
+    }
+    return { text: t.slice(1, -1).trim(), shift: lead + 1 };
+}
+/** `or` binds loosest, then `and`, then parentheses. */
+function parseExpression(text, offset) {
+    const { text: inner, shift } = unwrap(text);
+    const base = offset + shift;
+    const ors = splitTopLevel(inner, 'or', base);
+    if (ors.length > 1)
+        return { kind: 'or', children: ors.map((p) => parseExpression(p.text, p.at)) };
+    const ands = splitTopLevel(inner, 'and', base);
+    if (ands.length > 1)
+        return { kind: 'and', children: ands.map((p) => parseExpression(p.text, p.at)) };
+    return { kind: 'cond', text: inner, at: base };
+}
+/**
+ * Flatten to OR-of-ANDs, which is exactly the shape `Filter` holds.
+ *
+ * The distribution can blow up on a pathological query — `(a or b) and (c or
+ * d) and (e or f)` is eight groups — so it is capped. Better to refuse than
+ * to build a statement with ten thousand clauses in it.
+ */
+const MAX_GROUPS = 64;
+function toGroups(node) {
+    if (node.kind === 'cond')
+        return [[node]];
+    if (node.kind === 'or')
+        return node.children.flatMap(toGroups);
+    return node.children.reduce((groups, child) => {
+        const childGroups = toGroups(child);
+        const out = groups.flatMap((g) => childGroups.map((c) => [...g, ...c]));
+        return out.slice(0, MAX_GROUPS + 1);
+    }, [[]]);
+}
+/* ---------- value coercion ----------
+
+   The schema is the reason this is possible at all. Knowing the column's
+   declared type lets `active = true` mean the boolean `true` on Postgres and
+   the integer `1` on SQLite, without the user thinking about either. */
+/**
+ * Take the quotes off a value, and the escapes out of it.
+ *
+ * The unescaping half was missing, and its absence was invisible because the
+ * *tokenizer* has always understood `\"` — `maskQuotedValues` skips an
+ * escaped character precisely so it cannot end the quote. So `name =
+ * "Harbour \"HQ\""` was split into a clause correctly and then bound as the
+ * literal `Harbour \"HQ\"`, backslashes and all, which matches no row. Two
+ * halves of one grammar disagreeing about whether it has escapes.
+ *
+ * Only `\"`, `\'` and `\\` are unescaped. This is not C: `\n` in a value
+ * is a backslash and an n, because that is what someone typing a Windows path
+ * into a filter means by it.
+ */
+function unquoteValue(raw) {
+    const t = raw.trim();
+    if ((t.startsWith('"') && t.endsWith('"') && t.length > 1)
+        || (t.startsWith("'") && t.endsWith("'") && t.length > 1)) {
+        return { value: unescapeValue(t.slice(1, -1)), quoted: true };
+    }
+    return { value: t, quoted: false };
+}
+/**
+ * Write a value back into the grammar, quoting only when it needs it.
+ *
+ * The exact counterpart of `unquoteValue` above, and the reason it lives here
+ * rather than beside the caller: quoting used to be written out wherever a
+ * value had to be turned back into query text — three times in the client and
+ * once here — and the four disagreed about an embedded `"`, so the same value
+ * produced a different filter depending on which button was pressed.
+ *
+ * The backslash is escaped before the quote, or a value ending in one would
+ * escape its own closing quote and swallow the rest of the query. The client
+ * has its own copy in `core.quote`, because the browser cannot import this
+ * file; `mirrors.test.ts` asserts the two agree character for character.
+ */
+export function quoteValue(value) {
+    const text = String(value);
+    if (/^[\w.-]+$/.test(text))
+        return text;
+    return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function unescapeValue(text) {
+    return text.replace(/\\(["'\\])/g, '$1');
+}
+/**
+ * Dates are bound as ISO strings because both target dialects compare them
+ * correctly that way: Postgres casts on the way in, and SQLite's documented
+ * text-date format is exactly ISO-8601. A `Date` object handed to a driver
+ * is at the mercy of whatever it decides to do with the local timezone.
+ */
+function bindDate(d) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`);
+}
+function coerce(column, value, quoted) {
+    const kind = column ? columnKind(column.type) : 'other';
+    if (quoted)
+        return value; // an explicit quote is an explicit "this is text"
+    const truthy = /^(true|yes)$/i.test(value);
+    const falsy = /^(false|no)$/i.test(value);
+    if (kind === 'boolean') {
+        if (truthy || value === '1')
+            return true;
+        if (falsy || value === '0')
+            return false;
+    }
+    if (kind === 'number') {
+        /* SQLite has no boolean type, so a flag column is declared INTEGER and
+           stores 1 and 0. Someone typing `active = true` against it means the
+           integer, and binding the string 'true' would match nothing while
+           looking exactly like an empty table. */
+        if (truthy)
+            return 1;
+        if (falsy)
+            return 0;
+        const n = Number(value);
+        if (Number.isFinite(n) && value !== '')
+            return n;
+    }
+    if (kind === 'other') {
+        /* An untyped column compared to a bare number is still probably a number
+           — SQLite's dynamic typing makes untyped columns common. */
+        if (/^-?\d+(\.\d+)?$/.test(value))
+            return Number(value);
+        if (truthy)
+            return true;
+        if (falsy)
+            return false;
+    }
+    return value;
+}
+/* ---------- condition compilation ---------- */
+/** Levenshtein distance, capped — only used to suggest a near-miss column. */
+export 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 resolveColumn(table, name) {
+    if (!table)
+        return {};
+    const exact = table.columns.find((c) => c.name === name);
+    if (exact)
+        return { column: exact };
+    // Case-insensitive next: people type `Name` for `name` constantly, and
+    // both dialects fold unquoted identifiers anyway.
+    const insensitive = table.columns.find((c) => c.name.toLowerCase() === name.toLowerCase());
+    if (insensitive)
+        return { column: insensitive };
+    const near = table.columns
+        .map((c) => ({ name: c.name, d: distance(name.toLowerCase(), c.name.toLowerCase()) }))
+        .sort((a, b) => a.d - b.d)[0];
+    const suggestion = near && near.d <= 3 ? ` Did you mean "${near.name}"?` : '';
+    return { error: `"${name}" is not a column on ${table.name}.${suggestion}` };
+}
+function compileCondition(raw, table, now) {
+    const text = raw.trim();
+    /**
+     * `column between a and b`.
+     *
+     * Expanded into `>= a` and `<= b` rather than carried as an operator of its
+     * own. The filter model would need a new `Op` in three adapters to express
+     * a range it can already express, and every one of them would have to get
+     * the inclusive ends right. Two conditions is the same set of rows, needs
+     * nothing new, and shows in the SQL panel as exactly what it does.
+     *
+     * Inclusive at both ends, which is what SQL's BETWEEN means and what
+     * someone typing `total between 100 and 500` expects of `500`.
+     */
+    const between = text.match(new RegExp(String.raw `^(${FIELD})\s+(not\s+)?between\s+(.+?)\s+and\s+(.+)$`, 'i'));
+    if (between) {
+        const [, field, not, lowRaw, highRaw] = between;
+        const { column, error } = resolveColumn(table, field);
+        if (error)
+            return { error };
+        const name = column?.name ?? field;
+        if (not) {
+            return {
+                error: `"not between" is not supported. Write it as two conditions: `
+                    + `${name} < ${lowRaw.trim()} or ${name} > ${highRaw.trim()}`,
+            };
+        }
+        const low = unquoteValue(lowRaw);
+        const high = unquoteValue(highRaw);
+        if (!low.value || !high.value) {
+            return { error: `"between" needs two values, as in ${name} between 10 and 20` };
+        }
+        /* Each end coerced on its own, so a date range gets the same treatment a
+           single date comparison does — `between 2024-01-01 and 2024-06-30` binds
+           two timestamps, not two strings. */
+        return {
+            conditions: [
+                { column: name, op: '>=', value: coerce(column, low.value, low.quoted) },
+                { column: name, op: '<=', value: coerce(column, high.value, high.quoted) },
+            ],
+        };
+    }
+    const empty = text.match(new RegExp(String.raw `^([\w.$+"]+)\s+is\s+(not\s+)?empty$`, 'i'));
+    if (empty) {
+        const [, field, not] = empty;
+        const { column, error } = resolveColumn(table, field);
+        if (error)
+            return { error };
+        return { conditions: [{ column: column?.name ?? field, op: not ? 'isNotNull' : 'isNull' }] };
+    }
+    // Word operators are tried first because they are multi-character and a
+    // symbol match would otherwise never see them.
+    const word = text.match(new RegExp(String.raw `^(${FIELD})\s+(not\s+contains|contains|startswith|endswith|like|not\s+in|in)\s+(.+)$`, 'i'));
+    if (word) {
+        const [, field, opRaw, valueRaw] = word;
+        const { column, error } = resolveColumn(table, field);
+        if (error)
+            return { error };
+        const name = column?.name ?? field;
+        const key = opRaw.toLowerCase().replace(/\s+/g, ' ');
+        const negated = key.startsWith('not ');
+        const op = OPERATORS[negated ? key.slice(4) : key];
+        if (!op)
+            return { error: `Unknown operator "${opRaw}"` };
+        if (op === 'in') {
+            // `in (a, b)` and `in [a, b]` read more naturally than a bare list.
+            const list = valueRaw.trim().replace(/^[([]\s*/, '').replace(/\s*[)\]]$/, '');
+            const items = list
+                .split(',')
+                .map((s) => unquoteValue(s))
+                .filter((s) => s.value !== '');
+            if (!items.length)
+                return { error: `"${opRaw}" needs at least one value` };
+            const values = items.map((i) => coerce(column, i.value, i.quoted));
+            if (negated) {
+                /* There is no NOT IN in the filter model, and adding one would mean a
+                   new operator in every adapter. An expanded chain of != is the same
+                   set and needs nothing new. */
+                return { conditions: values.map((v) => ({ column: name, op: '!=', value: v })) };
+            }
+            return { conditions: [{ column: name, op: 'in', value: values }] };
+        }
+        if (negated) {
+            return { error: `"not ${op}" is not supported yet — use "is empty" or a different operator` };
+        }
+        const { value, quoted } = unquoteValue(valueRaw);
+        // LIKE operands stay text even on a numeric column; `contains 5` on an
+        // integer is a substring question, not an equality one.
+        return { conditions: [{ column: name, op, value: quoted ? value : value }] };
+    }
+    const symbol = text.match(new RegExp(String.raw `^(${FIELD})\s*(!=|<=|>=|=|<|>)\s*(.+)$`));
+    if (symbol) {
+        const [, field, opRaw, valueRaw] = symbol;
+        const { column, error } = resolveColumn(table, field);
+        if (error)
+            return { error };
+        const name = column?.name ?? field;
+        const op = OPERATORS[opRaw];
+        const { value, quoted } = unquoteValue(valueRaw);
+        /* A date phrase is a range, not a point, so `=` becomes two conditions.
+           Getting this wrong is the failure this language is built to avoid: an
+           unparseable phrase sent through as a literal matches nothing, and a
+           filter that silently matches nothing looks exactly like a table that is
+           genuinely empty. */
+        if (!quoted) {
+            const window = dateWindow(value, now);
+            if (window) {
+                if (op === '=') {
+                    return {
+                        conditions: [
+                            { column: name, op: '>=', value: bindDate(window.start) },
+                            { column: name, op: '<', value: bindDate(window.end) },
+                        ],
+                    };
+                }
+                if (op === '>=' || op === '<')
+                    return { conditions: [{ column: name, op, value: bindDate(window.start) }] };
+                if (op === '>' || op === '<=')
+                    return { conditions: [{ column: name, op, value: bindDate(window.end) }] };
+                return { error: `"${value}" is a date range — use =, >=, >, <= or < with it, not ${opRaw}` };
+            }
+        }
+        /* A bare multi-word value is nearly always a missing pair of quotes. It
+           would otherwise bind as a literal that matches nothing, which reads as
+           "no results" rather than "you made a mistake". */
+        if (!quoted && /\s/.test(value)) {
+            return {
+                error: `"${value}" has spaces — quote it ("${value}"), or use a date phrase like today or last 30 days`,
+            };
+        }
+        return { conditions: [{ column: name, op, value: coerce(column, value, quoted) }] };
+    }
+    /* A bare column name is a common half-typed state, and it is ambiguous in a
+       useful way: the user may be starting a filter, or may want projection and
+       not know the word for it. Naming both is how `show` gets discovered —
+       an error that only suggests filtering teaches that projection does not
+       exist. */
+    if (new RegExp(String.raw `^${FIELD}$`).test(text) && table) {
+        const { column } = resolveColumn(table, text);
+        if (column) {
+            return {
+                error: `What about "${text}"? To filter, try ${text} = … or ${text} is not empty. ` +
+                    `To show only that column, put "show" first: show ${text}`,
+            };
+        }
+    }
+    return { error: `Could not read "${text}" — try e.g. status = open, or amount > 100` };
+}
+/* ---------- the parser ---------- */
+/**
+ * What makes a clause word a column name instead: an operator right after it.
+ * A table with a column called `filter`, `sort` or `limit` is not unusual, and
+ * eating the word as a clause turns `limit is empty` into a nonsense query.
+ */
+const FOLLOWED_BY_OPERATOR = /^\s*(?:=|!=|>=|<=|>|<|\bis\s+not\s+empty\b|\bis\s+empty\b|\bis\b|\bcontains\b|\bstartswith\b|\bendswith\b|\blike\b|\bnot\s+in\b|\bin\b)/i;
+const CLAUSE_RE = /\b(filter|where|show|select|sort|order\s+by|limit)\b/gi;
+/**
+ * A copy of the query with the contents of quoted values replaced by spaces.
+ *
+ * Same length as the input and the quote characters left in place, so an index
+ * into this string is an index into the original. That is the whole trick: the
+ * scan happens on a version where a value cannot be mistaken for syntax, and
+ * every position it reports still points at the text the person typed.
+ *
+ * An unterminated quote blanks to the end, which is the safe direction — the
+ * alternative is reading the tail of a half-typed value as clauses while
+ * someone is still typing it.
+ */
+function maskQuotedValues(text) {
+    let out = '';
+    let quote = null;
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === '\\' && i + 1 < text.length) {
+                // An escaped character cannot end the quote, and both halves of it are
+                // inside the value.
+                out += '  ';
+                i += 1;
+                continue;
+            }
+            out += ch === quote ? ((quote = null), ch) : ' ';
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * What to say about a clause given twice.
+ *
+ * `filter` is the one that combines, and it is not routed here: two conditions
+ * genuinely narrow one result, so they are joined with `and`. Nothing else
+ * does. `show a show b` used to compile as a single column literally named
+ * "a and b" and then fail as an unknown column — an error naming a word the
+ * user never typed, about a mistake it never mentioned.
+ *
+ * Refusing beats picking one. There is no reading of two `limit`s under which
+ * the discarded number was not asked for, and a silently dropped clause is the
+ * failure this language exists to avoid: the answer looks like an answer. So
+ * the clause is named, and — where the language has a way to say both things
+ * at once — the comma that does it is shown.
+ */
+function repeatedClause(keyword) {
+    const combine = {
+        show: 'Name every column in one, separated by commas: show first_name, last_name',
+        sort: 'Name every field in one, separated by commas: sort invoice_date desc, id',
+        limit: 'Only one number can be the number of rows — keep the one you meant.',
+    };
+    return `Two "${keyword}" clauses, and the second cannot add to the first. ${combine[keyword] ?? 'Say it once.'}`;
+}
+function normalizeClause(word) {
+    const w = word.toLowerCase().replace(/\s+/g, ' ');
+    if (w === 'where')
+        return 'filter';
+    if (w === 'order by')
+        return 'sort';
+    if (w === 'select')
+        return 'show';
+    return w;
+}
+export function parseQuery(input, options = {}) {
+    const text = input.trim();
+    const now = options.now ?? new Date();
+    if (!text)
+        return { errors: [{ message: 'Start with a table name.' }] };
+    const errors = [];
+    /* Clause keywords are found in a copy with the *insides* of quoted values
+       blanked out, and then used as offsets into the real text.
+      
+       Scanning the raw string made a value that happens to contain a clause word
+       into a clause: `name = "order by"` split at the quote, and the error came
+       back "\"\"\" is not a column on customer. Did you mean \"id\"?" — confident,
+       specific, and about a column nobody typed. The blanking preserves length
+       and the quote characters themselves, so every offset still lines up with
+       the original and error positions stay honest. */
+    const scannable = maskQuotedValues(text);
+    CLAUSE_RE.lastIndex = 0;
+    const marks = [];
+    let m;
+    while ((m = CLAUSE_RE.exec(scannable))) {
+        if (FOLLOWED_BY_OPERATOR.test(scannable.slice(CLAUSE_RE.lastIndex)))
+            continue;
+        marks.push({ keyword: normalizeClause(m[1]), start: m.index, end: CLAUSE_RE.lastIndex });
+    }
+    const head = (marks.length ? text.slice(0, marks[0].start) : text).trim();
+    const tableName = head.split(/\s+/)[0] ?? '';
+    if (!tableName)
+        return { errors: [{ message: 'Which table?' }] };
+    /* The table has to resolve before anything else can be checked, since every
+       column error is relative to it. An unqualified name is matched on the
+       bare table name too, so `customers` finds `public.customers`. */
+    let table;
+    if (options.schema) {
+        table = findTable(options.schema, tableName);
+        if (!table) {
+            const candidates = options.schema.tables.filter((t) => t.name === tableName);
+            if (candidates.length === 1)
+                table = candidates[0];
+            else if (candidates.length > 1) {
+                errors.push({
+                    message: `"${tableName}" is ambiguous — it exists in ${candidates.map((c) => c.schema).join(', ')}. Qualify it, e.g. ${candidates[0].id}.`,
+                    at: 0,
+                });
+            }
+            else {
+                const near = options.schema.tables
+                    .map((t) => ({ id: t.id, d: Math.min(distance(tableName, t.name), distance(tableName, t.id)) }))
+                    .sort((a, b) => a.d - b.d)[0];
+                errors.push({
+                    message: `No table called "${tableName}".${near && near.d <= 3 ? ` Did you mean "${near.id}"?` : ''}`,
+                    at: 0,
+                });
+            }
+        }
+    }
+    // Anything after the table name and before the first clause word is already
+    // a filter. `where` stays as optional sugar, but making it mandatory would
+    // be ceremony with nothing to disambiguate.
+    const implied = head.slice(tableName.length).trim();
+    const clauses = {};
+    const clauseAt = {};
+    if (implied) {
+        clauses.filter = implied;
+        clauseAt.filter = tableName.length + 1;
+    }
+    marks.forEach((mark, i) => {
+        const bodyEnd = i + 1 < marks.length ? marks[i + 1].start : text.length;
+        const body = text.slice(mark.end, bodyEnd).trim();
+        if (clauses[mark.keyword] === undefined) {
+            clauses[mark.keyword] = body;
+            clauseAt[mark.keyword] = mark.end;
+            return;
+        }
+        // Repeated conditions concatenate: `where a where b` is `a and b`, which
+        // is also how the implied filter and an explicit `where` are joined.
+        if (mark.keyword === 'filter') {
+            clauses.filter = `${clauses.filter} and ${body}`;
+            return;
+        }
+        /* Everything else refuses. Located at the repeat rather than the first
+           one, because that is the word that made the query ambiguous — and the
+           first clause is left standing, so the partial result the editor shows
+           is still something that was typed. */
+        errors.push({ message: repeatedClause(mark.keyword), at: mark.start });
+    });
+    const filter = { groups: [] };
+    if (clauses.filter) {
+        const tree = parseExpression(clauses.filter, clauseAt.filter ?? 0);
+        const groups = toGroups(tree);
+        if (groups.length > MAX_GROUPS) {
+            errors.push({ message: `That expands to more than ${MAX_GROUPS} OR branches. Simplify it or filter in two steps.` });
+        }
+        else {
+            for (const group of groups) {
+                const conditions = [];
+                for (const node of group) {
+                    if (node.kind !== 'cond')
+                        continue;
+                    const { conditions: got, error } = compileCondition(node.text, table, now);
+                    if (error)
+                        errors.push({ message: error, at: node.at });
+                    else if (got)
+                        conditions.push(...got);
+                }
+                if (conditions.length)
+                    filter.groups.push(conditions);
+            }
+        }
+    }
+    const orderBy = [];
+    if (clauses.sort) {
+        for (const part of clauses.sort.split(/\s*,\s*|\s+and\s+/i)) {
+            const [field, dir] = part.trim().split(/\s+/);
+            if (!field)
+                continue;
+            const { column, error } = resolveColumn(table, field);
+            if (error)
+                errors.push({ message: error, at: clauseAt.sort });
+            else
+                orderBy.push({ column: column?.name ?? field, direction: (dir ?? '').toLowerCase() === 'desc' ? 'desc' : 'asc' });
+        }
+    }
+    const columns = [];
+    for (const raw of (clauses.show ?? '').split(',')) {
+        const field = raw.trim();
+        if (!field)
+            continue;
+        const { column, error } = resolveColumn(table, field);
+        if (error)
+            errors.push({ message: error, at: clauseAt.show });
+        else
+            columns.push(column?.name ?? field);
+    }
+    let limit;
+    if (clauses.limit) {
+        const n = Number(clauses.limit.split(/\s+/)[0]);
+        if (Number.isFinite(n) && n > 0)
+            limit = Math.min(Math.floor(n), MAX_LIMIT);
+        else
+            errors.push({ message: `limit expects a number, got "${clauses.limit}"`, at: clauseAt.limit });
+    }
+    /* A query is returned even when there are errors, so the editor can show a
+       partial result while someone is still typing. The caller decides whether
+       errors are fatal; only a missing table makes the query unusable. */
+    if (!tableName)
+        return { errors };
+    return {
+        query: { table: table?.id ?? tableName, filter, columns, orderBy, limit },
+        errors,
+    };
+}
+/**
+ * Render a parsed query back as the SQL it will become.
+ *
+ * This is for the explain panel, not for execution — the adapter builds the
+ * real statement from the same `Filter` with bound parameters. Showing values
+ * inline here is safe because the string never reaches a database, and it is
+ * the whole point: seeing `country = $1` next to `country = 'Australia'` is
+ * how someone learns what the tool is doing on their behalf.
+ */
+export function explain(query) {
+    const cols = query.columns.length ? query.columns.join(', ') : '*';
+    const lines = [`SELECT ${cols}`, `  FROM ${query.table}`];
+    if (query.filter.groups.length) {
+        const groups = query.filter.groups.map((g) => g
+            .map((c) => {
+            if (c.op === 'isNull')
+                return `${c.column} IS NULL`;
+            if (c.op === 'isNotNull')
+                return `${c.column} IS NOT NULL`;
+            if (c.op === 'in') {
+                const list = (Array.isArray(c.value) ? c.value : [c.value]).map(literal).join(', ');
+                return `${c.column} IN (${list})`;
+            }
+            if (c.op === 'like') {
+                /* Shown with its ESCAPE clause always, unlike the searches above.
+                   There the clause is plumbing behind a plain search; here the
+                   escape character is part of the operator someone chose to write
+                   by hand, and the preview is where they find out it exists. */
+                return `${c.column} LIKE ${literal(String(c.value ?? ''))} ESCAPE '${LIKE_ESCAPE}'`;
+            }
+            if (c.op === 'contains' || c.op === 'startsWith' || c.op === 'endsWith') {
+                const pattern = likePattern(c.value, c.op);
+                /* The ESCAPE clause is shown only when the value needed escaping.
+                   It is always sent — but printing it on every plain search would
+                   put dialect plumbing in front of the thing this preview exists
+                   to teach, and printing the escaped pattern *without* it would
+                   be a statement that means something else. */
+                const escape = pattern.includes(LIKE_ESCAPE) ? ` ESCAPE '${LIKE_ESCAPE}'` : '';
+                return `${c.column} LIKE ${literal(pattern)}${escape}`;
+            }
+            return `${c.column} ${c.op} ${literal(c.value)}`;
+        })
+            .join(' AND '));
+        lines.push(` WHERE ${groups.length === 1 ? groups[0] : groups.map((g) => `(${g})`).join('\n    OR ')}`);
+    }
+    if (query.orderBy.length) {
+        lines.push(` ORDER BY ${query.orderBy.map((o) => `${o.column} ${o.direction.toUpperCase()}`).join(', ')}`);
+    }
+    if (query.limit !== undefined)
+        lines.push(` LIMIT ${query.limit}`);
+    return lines.join('\n');
+}
+function literal(value) {
+    if (value === null || value === undefined)
+        return 'NULL';
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return `'${String(value).replace(/'/g, "''")}'`;
+}