querylens 0.1.0

package/dist/src/engine/parser/print.js

@@ -0,0 +1,74 @@
+/** The canonical key an aggregate's value is stored under — `COUNT(*)`, `SUM(age)`, `SUM(t.age)`. */
+export function aggregateKeyOf(fn, arg) {
+    return `${fn}(${arg.kind === 'star' ? '*' : arg.table ? `${arg.table}.${arg.name}` : arg.name})`;
+}
+/**
+ * How tightly a node binds, for parenthesising: OR < AND < NOT < a predicate <
+ * `+ -` < `* / %` < unary minus < an atom. (plan.md §25.4 B1.)
+ */
+function precedence(expr) {
+    switch (expr.kind) {
+        case 'or':
+            return 1;
+        case 'and':
+            return 2;
+        case 'not':
+            return 3;
+        case 'compare':
+        case 'isNull':
+        case 'in':
+        case 'like':
+            return 4;
+        case 'arith':
+            return expr.op === '+' || expr.op === '-' ? 5 : 6;
+        case 'neg':
+            return 7;
+        case 'column':
+        case 'literal':
+        case 'aggregate':
+            return 8;
+    }
+}
+/**
+ * SQL text for `expr`, parenthesised exactly where the tree's shape needs it,
+ * so it re-parses to the same tree — and so it can serve as a result column's
+ * name (`SELECT price * qty` is a column called `price * qty`).
+ */
+export function exprToSql(expr) {
+    const at = (child, min) => precedence(child) < min ? `(${exprToSql(child)})` : exprToSql(child);
+    switch (expr.kind) {
+        case 'column':
+            return expr.table ? `${expr.table}.${expr.name}` : expr.name;
+        case 'literal':
+            return expr.raw;
+        case 'aggregate':
+            return aggregateKeyOf(expr.fn, expr.arg);
+        case 'compare':
+            return `${at(expr.left, 5)} ${expr.op} ${at(expr.right, 5)}`;
+        case 'and':
+            return `${at(expr.left, 2)} AND ${at(expr.right, 3)}`;
+        case 'or':
+            return `${at(expr.left, 1)} OR ${at(expr.right, 2)}`;
+        case 'not':
+            return `NOT ${at(expr.operand, 3)}`;
+        case 'isNull':
+            return `${at(expr.operand, 5)} IS ${expr.negated ? 'NOT ' : ''}NULL`;
+        case 'in':
+            return expr.subquery
+                ? `${at(expr.operand, 5)} ${expr.negated ? 'NOT ' : ''}IN (SELECT ${expr.subquery.column.name} FROM ${expr.subquery.from.name}${expr.subquery.where ? ` WHERE ${exprToSql(expr.subquery.where)}` : ''})`
+                : `${at(expr.operand, 5)} ${expr.negated ? 'NOT ' : ''}IN (${expr.items.map((i) => at(i, 5)).join(', ')})`;
+        case 'like':
+            return `${at(expr.operand, 5)} ${expr.negated ? 'NOT ' : ''}LIKE ${at(expr.pattern, 5)}`;
+        case 'arith': {
+            // Left-associative: the right operand of a same-level operator needs parentheses (`a - (b - c)`).
+            const p = precedence(expr);
+            return `${at(expr.left, p)} ${expr.op} ${at(expr.right, p + 1)}`;
+        }
+        case 'neg': {
+            // `- -x` would read as a comment, and `-(a + b)` needs its parentheses.
+            const inner = expr.operand;
+            const wrap = inner.kind === 'neg' || (inner.kind === 'literal' && inner.raw.startsWith('-'));
+            return wrap ? `-(${exprToSql(inner)})` : `-${at(inner, 7)}`;
+        }
+    }
+}

package/dist/src/engine/parser/tokenizer.js

@@ -0,0 +1,146 @@
+/**
+ * Hand-written tokenizer. Every token carries its character span so the parser
+ * can point CodeMirror at the exact text that went wrong.
+ */
+/**
+ * Includes keywords v0 does NOT support. Recognising them is what lets the
+ * parser say "GROUP BY is not supported yet" instead of "unexpected identifier".
+ */
+export const KEYWORDS = new Set([
+    'SELECT', 'FROM', 'WHERE', 'AND', 'OR', 'NOT', 'AS', 'NULL', 'TRUE', 'FALSE', 'BETWEEN', 'IN', 'IS', 'LIKE',
+    'JOIN', 'INNER', 'LEFT', 'RIGHT', 'OUTER', 'FULL', 'CROSS', 'ON', 'USING',
+    'GROUP', 'ORDER', 'BY', 'ASC', 'DESC', 'HAVING', 'LIMIT', 'OFFSET', 'DISTINCT', 'UNION',
+    'INSERT', 'UPDATE', 'DELETE', 'INTO', 'VALUES', 'SET', 'CREATE', 'DROP', 'EXPLAIN', 'ANALYZE',
+]);
+export class TokenizeError extends Error {
+    from;
+    to;
+    hint;
+    constructor(message, from, to, hint) {
+        super(message);
+        this.name = 'TokenizeError';
+        this.from = from;
+        this.to = to;
+        if (hint !== undefined)
+            this.hint = hint;
+    }
+}
+const isSpace = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r';
+const isDigit = (c) => c >= '0' && c <= '9';
+const isIdentStart = (c) => (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_';
+const isIdentPart = (c) => isIdentStart(c) || isDigit(c);
+const SINGLE = {
+    '*': 'star',
+    // Tokenised, not supported: it lets the parser explain qualified names
+    // rather than failing at the character level before it sees the real problem.
+    '.': 'dot',
+    ',': 'comma',
+    '(': 'lparen',
+    ')': 'rparen',
+    ';': 'semicolon',
+    '=': 'operator',
+    '<': 'operator',
+    '>': 'operator',
+    // Arithmetic (plan.md §25.4 B1b). `*` is `star` above: the parser reads it as
+    // multiplication wherever an operand has just been parsed, and as "every column" elsewhere.
+    '+': 'operator',
+    '-': 'operator',
+    '/': 'operator',
+    '%': 'operator',
+};
+export function tokenize(sql) {
+    const tokens = [];
+    let i = 0;
+    while (i < sql.length) {
+        const c = sql[i];
+        if (isSpace(c)) {
+            i++;
+            continue;
+        }
+        // -- line comment
+        if (c === '-' && sql[i + 1] === '-') {
+            while (i < sql.length && sql[i] !== '\n')
+                i++;
+            continue;
+        }
+        // /* block comment */
+        if (c === '/' && sql[i + 1] === '*') {
+            const start = i;
+            i += 2;
+            while (i < sql.length && !(sql[i] === '*' && sql[i + 1] === '/'))
+                i++;
+            if (i >= sql.length) {
+                throw new TokenizeError('Unterminated block comment.', start, sql.length);
+            }
+            i += 2;
+            continue;
+        }
+        const start = i;
+        if (isIdentStart(c)) {
+            while (i < sql.length && isIdentPart(sql[i]))
+                i++;
+            const value = sql.slice(start, i);
+            const upper = value.toUpperCase();
+            tokens.push({
+                type: KEYWORDS.has(upper) ? 'keyword' : 'identifier',
+                value,
+                upper,
+                from: start,
+                to: i,
+            });
+            continue;
+        }
+        if (isDigit(c)) {
+            while (i < sql.length && isDigit(sql[i]))
+                i++;
+            if (sql[i] === '.') {
+                i++;
+                while (i < sql.length && isDigit(sql[i]))
+                    i++;
+            }
+            const value = sql.slice(start, i);
+            tokens.push({ type: 'number', value, upper: value, from: start, to: i });
+            continue;
+        }
+        if (c === "'") {
+            i++;
+            let text = '';
+            for (;;) {
+                if (i >= sql.length) {
+                    throw new TokenizeError('Unterminated string literal.', start, sql.length, "Add a closing ' quote.");
+                }
+                if (sql[i] === "'") {
+                    // '' is an escaped quote inside a string.
+                    if (sql[i + 1] === "'") {
+                        text += "'";
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                text += sql[i];
+                i++;
+            }
+            tokens.push({ type: 'string', value: text, upper: text, from: start, to: i });
+            continue;
+        }
+        // Two-character operators are tokenised so the parser can reject them with
+        // a message about v0 scope rather than a confusing character-level error.
+        const two = sql.slice(i, i + 2);
+        if (two === '<=' || two === '>=' || two === '<>' || two === '!=') {
+            i += 2;
+            tokens.push({ type: 'operator', value: two, upper: two, from: start, to: i });
+            continue;
+        }
+        const single = SINGLE[c];
+        if (single) {
+            i++;
+            tokens.push({ type: single, value: c, upper: c, from: start, to: i });
+            continue;
+        }
+        throw new TokenizeError(`Unexpected character ${JSON.stringify(c)}.`, start, start + 1);
+    }
+    tokens.push({ type: 'eof', value: '', upper: '', from: sql.length, to: sql.length });
+    return tokens;
+}

package/dist/src/engine/planner/buildPlan.js

@@ -0,0 +1,208 @@
+/**
+ * AST → canonical logical plan, built bottom-up:
+ *
+ *   Limit n                          -- only when there is a LIMIT
+ *     └─ Project [columns]
+ *          └─ Sort column [ASC|DESC] -- only when there is an ORDER BY
+ *               └─ Filter (predicate)     -- only when there is a WHERE
+ *                    └─ SeqScan table
+ *
+ * This is the *unoptimised* shape on purpose. It is a direct, obvious
+ * translation of the query text, which is what makes the optimizer's rewrite
+ * legible when the two are shown side by side.
+ */
+import { exprToSql } from "../parser/print.js";
+import { aggregateKeyOf, columnKey, selectItemArgColumn, selectItemKey, walkExpr } from "../parser/index.js";
+import { indexNameOf, joinIndexFor } from "../index/spec.js";
+/**
+ * A `DELETE`'s canonical plan is just the scan that finds the rows to
+ * remove — `Filter → SeqScan`, or a bare `SeqScan` with no `WHERE`. No
+ * `Project`: a delete produces no columns for a client to read.
+ */
+export function buildDeletePlan(ast) {
+    const scan = { op: 'SeqScan', table: ast.from.name };
+    return ast.where ? { op: 'Filter', predicate: ast.where, child: scan } : scan;
+}
+/**
+ * An `UPDATE`'s canonical plan is the same shape as a `DELETE`'s — the scan
+ * that finds the rows to modify. The SET clause plays no part in planning:
+ * it only takes effect once execution has already found a row.
+ */
+export function buildUpdatePlan(ast) {
+    const scan = { op: 'SeqScan', table: ast.table.name };
+    return ast.where ? { op: 'Filter', predicate: ast.where, child: scan } : scan;
+}
+/** Whether this SELECT needs a `HashAggregate`: it has `GROUP BY`, or any aggregate call in its list. */
+export function isAggregateQuery(ast) {
+    return (ast.groupBy !== undefined ||
+        ast.having !== undefined ||
+        (ast.select.kind === 'columns' && ast.select.items.some((item) => item.kind === 'aggregate')));
+}
+/**
+ * Every aggregate the query needs computed per group: the SELECT list's, then any
+ * that only a HAVING predicate mentions (`SELECT dept … HAVING COUNT(*) > 2` needs a
+ * count nobody selected), each once, keyed by its canonical text.
+ */
+export function aggregateSpecsOf(ast) {
+    const specs = new Map();
+    if (ast.select.kind === 'columns') {
+        for (const item of ast.select.items) {
+            if (item.kind !== 'aggregate')
+                continue;
+            const key = selectItemKey(item);
+            specs.set(key, { key, fn: item.fn, column: selectItemArgColumn(item) });
+        }
+    }
+    if (ast.having) {
+        walkExpr(ast.having, (e) => {
+            if (e.kind !== 'aggregate')
+                return;
+            const key = aggregateKeyOf(e.fn, e.arg);
+            if (!specs.has(key))
+                specs.set(key, { key, fn: e.fn, column: e.arg.kind === 'star' ? null : columnKey(e.arg) });
+        });
+    }
+    return [...specs.values()];
+}
+/**
+ * Builds the aggregate node — `HashAggregate` by default, or `SortAggregate`
+ * when `strategy` says so — for a `SELECT` that groups or aggregates. Shared
+ * with `emit.ts`'s progressive plan-tree narration, so the two never drift
+ * on how a `SelectItem` becomes an `AggregateSpec`. Nothing in the pipeline
+ * picks `strategy` on its own; it defaults to `'hash'` (the shipped
+ * behaviour) and only `/compare`'s third mode ever passes `'sort'`, via
+ * `EngineOptions.aggregateStrategy` (plan.md §22.2).
+ */
+export function buildAggregatePlan(ast, child, strategy = 'hash') {
+    const groupBy = ast.groupBy?.columns.map((c) => c.name) ?? [];
+    const aggregates = aggregateSpecsOf(ast);
+    return { op: strategy === 'sort' ? 'SortAggregate' : 'HashAggregate', groupBy, aggregates, child };
+}
+/**
+ * The algorithm a `JOIN` will actually run. Three of them work on any pair of tables; `index-nested-loop`
+ * (plan.md §25.4 B4) needs the inner table to have a B+Tree on the join column, so without one it cannot run
+ * and the join is an ordinary `nested-loop` — never an error, and never silent: `emit.ts` says so in the plan.
+ */
+export function effectiveJoinAlgorithm(requested, joinTable, rightColumn) {
+    if (requested !== 'index-nested-loop')
+        return requested;
+    // An index whose *leading* column is the join column will do — a composite one that starts with it is entered
+    // through that one-column leftmost prefix.
+    return joinTable && joinIndexFor(joinTable, rightColumn) ? requested : 'nested-loop';
+}
+/**
+ * Builds the whole `Join` chain for `FROM t1 JOIN t2 ON … [JOIN t3 ON …]…` (plan.md §25.4 C3 slice b) — left-deep,
+ * one `Join` node per clause, each nesting the previous one as its `left`. A bare `SeqScan` starts the fold, and
+ * each step adds a bare `SeqScan` (or, for `index-nested-loop`, an `IndexProbe`) on the one table its own clause
+ * introduces — v1 never pushes a predicate into any scan here, plan.md §22.2 — with the ON equality's two columns
+ * resolved to whichever side is the new table and whichever is a table already in the chain, whichever order they
+ * were written in. `checkJoinOn`/`checkJoinChain` already guarantee this at parse time; the `kind` check below is
+ * just how the type system is told what that already ensures. Shared with `emit.ts`'s progressive plan-tree
+ * narration, like `buildAggregatePlan` already is, so the two never drift. `algorithm` defaults to `'nested-loop'`
+ * (the shipped behaviour); only `/compare`'s join mode ever passes another, via `EngineOptions.joinStrategy` — the
+ * same one for every step, though `index-nested-loop` still falls back per step (see `effectiveJoinAlgorithm`)
+ * whenever that step's own table has no usable index. For a single join this is exactly the old two-table shape.
+ */
+export function buildJoinPlan(joins, fromTable, algorithm = 'nested-loop', joinTables) {
+    let plan = { op: 'SeqScan', table: fromTable };
+    for (const join of joins) {
+        const { left, right } = join.on;
+        if (left.kind !== 'column' || right.kind !== 'column') {
+            throw new Error('unreachable: checkJoinOn guarantees a JOIN ON is column = column');
+        }
+        const newTable = join.table.name;
+        // checkJoinChain already guarantees exactly one side names newTable and the other a table already in scope.
+        const newTableIsLeftOperand = left.table === newTable;
+        const rightColumn = newTableIsLeftOperand ? left.name : right.name;
+        const leftColumn = newTableIsLeftOperand ? right.name : left.name;
+        const leftTable = (newTableIsLeftOperand ? right.table : left.table);
+        const joinTable = joinTables?.[newTable];
+        const effective = effectiveJoinAlgorithm(algorithm, joinTable, rightColumn);
+        plan = {
+            op: 'Join',
+            algorithm: effective,
+            ...(join.joinType ? { joinType: join.joinType } : {}),
+            left: plan,
+            right: effective === 'index-nested-loop'
+                ? {
+                    op: 'IndexProbe',
+                    table: newTable,
+                    // The index's name: the join column itself for a plain index, the composite's columns joined for one that leads with it.
+                    column: indexNameOf(joinIndexFor(joinTable, rightColumn).columns),
+                    outerTable: leftTable,
+                    outerColumn: leftColumn,
+                }
+                : { op: 'SeqScan', table: newTable },
+            leftTable,
+            rightTable: newTable,
+            leftColumn,
+            rightColumn,
+        };
+    }
+    return plan;
+}
+/**
+ * The `Project` list for a SELECT list. Plain columns and aggregates are read
+ * off the row by name; as soon as any item is *computed* (plan.md §25.4 B1b) the
+ * whole list becomes expressions — each item is then evaluated, a plain column
+ * just being the simplest expression. Shared with `emit.ts`'s narration so the
+ * two never disagree.
+ */
+export function projectListFor(select) {
+    if (select.kind === 'star')
+        return { kind: 'star' };
+    if (!select.items.some((item) => item.kind === 'expression')) {
+        return { kind: 'columns', names: select.items.map(selectItemKey) };
+    }
+    return {
+        kind: 'expressions',
+        items: select.items.map((item) => {
+            const expr = item.kind === 'expression'
+                ? item.expr
+                : { kind: 'column', name: item.kind === 'column' ? item.name : selectItemKey(item), ...(item.kind === 'column' && item.table ? { table: item.table } : {}), span: item.span };
+            const key = selectItemKey(item);
+            return { key, expr, sql: item.kind === 'expression' && item.alias ? `${exprToSql(item.expr)} AS ${item.alias}` : key };
+        }),
+    };
+}
+/**
+ * The `DISTINCT` node above the projection (plan.md §25.4 B2): a `HashDistinct` by
+ * default, a `SortDistinct` when `aggregateStrategy` says `'sort'` — the same
+ * option `GROUP BY` reads, so `/compare` can force each side. A sort-based one
+ * also needs the query's `ORDER BY` column (the parser has checked it is in the
+ * select list): it sorts on that first, so the order the caller asked for survives.
+ * Shared with `emit.ts`'s narration.
+ */
+export function distinctNodeFor(ast, child, strategy) {
+    if (strategy !== 'sort')
+        return { op: 'HashDistinct', child };
+    return {
+        op: 'SortDistinct',
+        ...(ast.orderBy ? { sortKey: { column: ast.orderBy.column, direction: ast.orderBy.direction } } : {}),
+        child,
+    };
+}
+export function buildPlan(ast, aggregateStrategy = 'hash', joinStrategy = 'nested-loop', joinTables) {
+    const scan = ast.joins && ast.joins.length > 0
+        ? buildJoinPlan(ast.joins, ast.from.name, joinStrategy, joinTables)
+        : { op: 'SeqScan', table: ast.from.name };
+    const filtered = ast.where
+        ? { op: 'Filter', predicate: ast.where, child: scan }
+        : scan;
+    const aggregated = isAggregateQuery(ast)
+        ? buildAggregatePlan(ast, filtered, aggregateStrategy)
+        : filtered;
+    // HAVING runs after the aggregate, on the groups it produced.
+    const having = ast.having ? { op: 'Having', predicate: ast.having, child: aggregated } : aggregated;
+    // ORDER BY and GROUP BY are mutually exclusive (the parser enforces this),
+    // so Sort only ever sits above the filtered scan, never above an aggregate.
+    const sorted = ast.orderBy
+        ? { op: 'Sort', column: ast.orderBy.column, direction: ast.orderBy.direction, child: having }
+        : having;
+    const columns = projectListFor(ast.select);
+    const projected = { op: 'Project', columns, child: sorted };
+    const distinct = ast.distinct ? distinctNodeFor(ast, projected, aggregateStrategy) : projected;
+    return ast.limit === undefined
+        ? distinct
+        : { op: 'Limit', count: ast.limit.value, ...(ast.limit.offset ? { offset: ast.limit.offset } : {}), child: distinct };
+}