querylens 0.1.0

package/dist/src/engine/exec/evaluate.js

@@ -0,0 +1,174 @@
+/**
+ * Predicate evaluation with SQL's three-valued logic.
+ *
+ * A comparison against NULL is UNKNOWN, not false — and only TRUE passes a
+ * filter. That distinction is the reason `WHERE age > 30` and
+ * `WHERE NOT (age <= 30)` do not partition a table with NULLs, which is a
+ * genuine and commonly-missed piece of SQL semantics, so it is modelled rather
+ * than flattened to booleans.
+ *
+ * plan.md §25.4 B1 adds `OR`, `NOT`, `IS [NOT] NULL`, `IN` and `LIKE`, each with
+ * its own truth table below. The two that surprise people:
+ *
+ *   NOT UNKNOWN is UNKNOWN          so `NOT (x = 1)` still rejects the NULL rows
+ *   x NOT IN (1, NULL) is never TRUE   because `x <> NULL` is UNKNOWN for every x
+ *
+ * The tests in `oracle/` (ternary-logic partitioning, and a differential run
+ * against SQLite) check these tables against an outside authority.
+ */
+import { aggregateKeyOf, columnKey } from "../parser/index.js";
+import { arithmetic, negate as negateValue } from "../value.js";
+export function evaluateValue(expr, row) {
+    switch (expr.kind) {
+        case 'literal':
+            return expr.value;
+        case 'column':
+            return row[columnKey(expr)] ?? null;
+        // Arithmetic is a value (plan.md §25.4 B1b): NULL in, NULL out; `x / 0` is NULL; whole-number `/` truncates.
+        case 'arith':
+            return arithmetic(expr.op, evaluateValue(expr.left, row), evaluateValue(expr.right, row));
+        case 'neg':
+            return negateValue(evaluateValue(expr.operand, row));
+        // A HAVING aggregate is a value the aggregate operator already computed for this group (plan.md §25.4 B2).
+        case 'aggregate':
+            return row[aggregateKeyOf(expr.fn, expr.arg)] ?? null;
+        default:
+            return evaluatePredicate(expr, row);
+    }
+}
+/** Exported for `operators.ts`'s `HashAggregate` — MIN/MAX order values the same way a `<`/`>` predicate does. */
+export function compare(op, left, right) {
+    if (left === null || right === null)
+        return null; // UNKNOWN
+    if (typeof left === 'number' && typeof right === 'number') {
+        return compareOrdered(op, left, right);
+    }
+    const a = typeof left === 'boolean' ? String(Number(left)) : String(left);
+    const b = typeof right === 'boolean' ? String(Number(right)) : String(right);
+    return compareOrdered(op, a, b);
+}
+function compareOrdered(op, a, b) {
+    switch (op) {
+        case '=':
+            return a === b;
+        case '<>':
+            return a !== b;
+        case '<':
+            return a < b;
+        case '>':
+            return a > b;
+        case '<=':
+            return a <= b;
+        case '>=':
+            return a >= b;
+    }
+}
+/**
+ * A canonical string key for `=` comparison, exported for `operators.ts`'s
+ * hash join (plan.md §22.2): two non-null values collide under this key
+ * exactly when `compare('=', a, b)` above would say `true` — the same
+ * coercion, just computed once per value instead of pairwise. Never called
+ * on `null` — a NULL join key is filtered out before it would reach this,
+ * the same "NULL never matches NULL" rule `compare` itself enforces.
+ */
+export function equalityKeyOf(value) {
+    return typeof value === 'boolean' ? String(Number(value)) : String(value);
+}
+const textOf = (value) => equalityKeyOf(value);
+const likeCache = new Map();
+/**
+ * `LIKE`: `%` matches any run of characters (including none), `_` exactly one,
+ * and everything else matches itself. **Case-sensitive**, as in PostgreSQL —
+ * SQLite's default is case-insensitive for ASCII, one of the documented
+ * differences in `oracle/ledger.ts`. There is no escape character, so a literal
+ * `%` or `_` cannot be matched; a pattern is a teaching device here, not a
+ * regular expression engine.
+ */
+export function likeMatches(text, pattern) {
+    let re = likeCache.get(pattern);
+    if (!re) {
+        const body = [...pattern]
+            .map((ch) => (ch === '%' ? '[\\s\\S]*' : ch === '_' ? '[\\s\\S]' : ch.replace(/[.*+?^${}()|[\]\\/-]/g, '\\$&')))
+            .join('');
+        re = new RegExp(`^${body}$`, 's');
+        likeCache.set(pattern, re);
+    }
+    return re.test(text);
+}
+const negate = (t, negated) => (negated && t !== null ? !t : t);
+export function evaluatePredicate(expr, row) {
+    switch (expr.kind) {
+        case 'compare':
+            return compare(expr.op, evaluateValue(expr.left, row), evaluateValue(expr.right, row));
+        case 'and': {
+            const left = evaluatePredicate(expr.left, row);
+            const right = evaluatePredicate(expr.right, row);
+            // FALSE dominates: FALSE AND UNKNOWN is FALSE, not UNKNOWN.
+            if (left === false || right === false)
+                return false;
+            if (left === null || right === null)
+                return null;
+            return true;
+        }
+        case 'or': {
+            const left = evaluatePredicate(expr.left, row);
+            const right = evaluatePredicate(expr.right, row);
+            // TRUE dominates: TRUE OR UNKNOWN is TRUE, not UNKNOWN.
+            if (left === true || right === true)
+                return true;
+            if (left === null || right === null)
+                return null;
+            return false;
+        }
+        case 'not': {
+            const operand = evaluatePredicate(expr.operand, row);
+            return operand === null ? null : !operand; // NOT UNKNOWN is UNKNOWN
+        }
+        case 'isNull': {
+            // The one test that is never UNKNOWN — it exists to ask about NULL directly.
+            const isNull = evaluateValue(expr.operand, row) === null;
+            return expr.negated ? !isNull : isNull;
+        }
+        case 'in': {
+            const value = evaluateValue(expr.operand, row);
+            if (value === null)
+                return null; // NULL IN (…) is UNKNOWN, whatever the list holds
+            let sawUnknown = false;
+            for (const item of expr.items) {
+                const equal = compare('=', value, evaluateValue(item, row));
+                if (equal === true)
+                    return negate(true, expr.negated);
+                if (equal === null)
+                    sawUnknown = true;
+            }
+            // Not found: FALSE — unless a NULL in the list left the answer unknown.
+            return negate(sawUnknown ? null : false, expr.negated);
+        }
+        case 'like': {
+            const value = evaluateValue(expr.operand, row);
+            const pattern = evaluateValue(expr.pattern, row);
+            if (value === null || pattern === null)
+                return null;
+            return negate(likeMatches(textOf(value), textOf(pattern)), expr.negated);
+        }
+        case 'aggregate':
+        case 'arith':
+        case 'neg': {
+            // A number used where a truth value is wanted: non-zero is TRUE, NULL is UNKNOWN.
+            const value = evaluateValue(expr, row);
+            return value === null ? null : Boolean(value);
+        }
+        case 'literal':
+            return expr.value === null ? null : Boolean(expr.value);
+        case 'column': {
+            const value = row[columnKey(expr)] ?? null;
+            return value === null ? null : Boolean(value);
+        }
+    }
+}
+/** Only TRUE passes a WHERE clause. UNKNOWN does not. */
+export function passes(expr, row) {
+    if (!expr)
+        return true;
+    return evaluatePredicate(expr, row) === true;
+}

package/dist/src/engine/exec/index.js

@@ -0,0 +1,4 @@
+export { buildOperator } from "./operators.js";
+export { evaluatePredicate, evaluateValue, passes } from "./evaluate.js";
+export { execute } from "./run.js";
+export { externalMergeSort, sortPassCount, sortTempPageCount } from "./sort.js";

package/dist/src/engine/exec/insert.js

@@ -0,0 +1,75 @@
+/**
+ * Executes an `INSERT`: writes the new row onto the heap page it lands on —
+ * the last page, if it has room, or a fresh one otherwise — and, if the
+ * table is indexed, adds its key to the B+Tree with the real `insert`
+ * algorithm, real leaf/internal splits included (plan.md §22.2, the write
+ * path's second statement).
+ *
+ * There is no scan and nothing to find, so unlike `DELETE` this needs no
+ * find-then-mutate pass: one row, one page, at most one tree insert.
+ */
+import { enforceUniqueOnInsert } from "./unique.js";
+import { entryFor, height, indexNameOf, indexSpecsOf, insert, keyText, keyValuesOf, pageCountFor } from "../index/index.js";
+/** Where the new row lands: the last heap page, if it has room, or a fresh one. */
+function targetPage(ctx) {
+    const lastPage = ctx.heap.pages[ctx.heap.pages.length - 1];
+    const hasRoom = lastPage.rows.length < ctx.options.rowsPerPage;
+    return hasRoom
+        ? { pageId: lastPage.pageId, slot: lastPage.rows.length, isNewPage: false }
+        : { pageId: pageCountFor(ctx.heap, ctx.trees), slot: 0, isNewPage: true };
+}
+/**
+ * One clause summarising what the B+Tree insert had to do beyond the plain
+ * add. Exported: `exec/update.ts` reuses it for the "add the new key" half
+ * of a reindex.
+ */
+export function summarizeInsert(nodesBefore, nodesAfter, heightBefore, heightAfter) {
+    if (nodesAfter === nodesBefore)
+        return 'the leaf had room, so no split was needed';
+    const added = nodesAfter - nodesBefore;
+    return `a split added ${added} node${added === 1 ? '' : 's'}${heightAfter > heightBefore ? `, and the tree grew to height ${heightAfter}` : ''}`;
+}
+/** Adds `row`'s entry to every index the table declares, skipping one whose leading column is NULL. */
+function insertIntoIndex(ctx, row, pointer) {
+    for (const spec of indexSpecsOf(ctx.table)) {
+        const name = indexNameOf(spec.columns);
+        const tree = ctx.trees[name];
+        if (!tree)
+            continue;
+        const values = keyValuesOf(row, spec.columns);
+        if (values[0] === null)
+            continue; // a NULL leading column is never indexed — nothing to add
+        const nodesBefore = Object.keys(tree.nodes).length;
+        const heightBefore = height(tree);
+        const { key, pointer: stored } = entryFor(spec.columns, row, pointer, ctx.table.clusteredKey);
+        insert(tree, key, stored);
+        const nodesAfter = Object.keys(tree.nodes).length;
+        const heightAfter = height(tree);
+        ctx.emit(`The \`${name}\` B+Tree gets key ${keyText(values)} — ${summarizeInsert(nodesBefore, nodesAfter, heightBefore, heightAfter)}.`, { stage: 'execute', op: 'Insert', rowsProduced: 1 });
+    }
+}
+export function executeInsert(row, ctx) {
+    // A UNIQUE index is asked first — a rejected INSERT must not have touched the heap or any other tree.
+    enforceUniqueOnInsert(ctx, row);
+    const { pageId, slot, isNewPage } = targetPage(ctx);
+    ctx.locks.acquire(pageId, 'exclusive', isNewPage
+        ? `Take an exclusive lock on page ${pageId} — a fresh page for the new row, since the last one is full.`
+        : `Take an exclusive lock on page ${pageId} — INSERT is about to add a row to it.`);
+    if (isNewPage) {
+        const written = ctx.pool.write(pageId);
+        if (written)
+            ctx.pool.unpin(written.frameId);
+    }
+    else {
+        const fetched = ctx.pool.fetch(pageId);
+        if (fetched)
+            ctx.pool.unpin(fetched.frameId);
+        ctx.pool.markDirty(pageId);
+    }
+    ctx.emit(isNewPage
+        ? `Insert writes the new row onto a fresh page, ${pageId} — the last page was full.`
+        : `Insert writes the new row onto page ${pageId}, which had room for it.`, { stage: 'execute', op: 'Insert', rowsProduced: 1 });
+    ctx.locks.release(pageId, 'exclusive');
+    insertIntoIndex(ctx, row, { pageId, slot });
+    return { row };
+}