@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/computed.js

@@ -0,0 +1,378 @@
+import { noteRead } from './query.js';
+export const COMPUTED_TYPES = ['boolean', 'number', 'date'];
+/** What a computed column is to anything that reads columns: typed, never written, never a key. */
+export function computedColumnMeta(name, computed) {
+    return {
+        name,
+        type: computed.type === 'number' ? 'numeric' : computed.type,
+        nullable: computed.type !== 'boolean',
+        primaryKey: false,
+        writable: false,
+    };
+}
+/**
+ * The catalog with each table's computed columns among its columns, typed and never written (`computed` by table id):
+ * what a rule judged of a stored row reads one through (a validation, a form's value from a referenced record), where
+ * the figure is worked out once the row is read rather than by the statement that reads it.
+ */
+export function withComputedColumns(schema, computed) {
+    if (!computed.size)
+        return schema;
+    return {
+        ...schema,
+        tables: schema.tables.map((table) => {
+            const named = computed.get(table.id);
+            if (!named)
+                return table;
+            const extra = Object.entries(named)
+                .filter(([name]) => !table.columns.some((column) => column.name === name))
+                .map(([name, column]) => computedColumnMeta(name, column));
+            return extra.length ? { ...table, columns: [...table.columns, ...extra] } : table;
+        }),
+    };
+}
+/* ---------- the words (the parser is computedParse.ts) ---------- */
+export class ComputedError extends Error {
+    at;
+    constructor(message, at) {
+        super(message);
+        this.at = at;
+    }
+}
+/** Every path an expression reads, once each, in order. */
+export function computedReads(node) {
+    const out = [];
+    const walk = (n) => {
+        if (n.k === 'path') {
+            if (!out.includes(n.path))
+                out.push(n.path);
+            return;
+        }
+        if (n.k === 'op') {
+            walk(n.left);
+            walk(n.right);
+            return;
+        }
+        if (n.k === 'call')
+            n.args.forEach(walk);
+        if (n.k === 'not' || n.k === 'neg' || n.k === 'empty' || n.k === 'span')
+            walk(n.of);
+    };
+    walk(node);
+    return out;
+}
+/**
+ * What an expression is, or why it is none: each column's kind from the
+ * catalog (`kindOf`), a date minus a date a number of days, a date plus a
+ * number or a span a date. Said in the author's words, with the character
+ * the mistake stands at where a word locates it.
+ */
+export function computedKind(node, kindOf) {
+    const kind = (n) => {
+        switch (n.k) {
+            case 'path': {
+                const found = kindOf(n.path);
+                if (!found)
+                    throw new Error(`"${n.path}" is not a column here.`);
+                return found;
+            }
+            case 'number':
+                return 'number';
+            case 'text':
+            case 'me':
+            case 'nobody':
+                return 'text';
+            case 'bool':
+                return 'boolean';
+            case 'today':
+            case 'now':
+            case 'date':
+            case 'instant':
+                return 'date';
+            case 'not': {
+                if (kind(n.of) !== 'boolean')
+                    throw new Error('"not" reads a yes-or-no.');
+                return 'boolean';
+            }
+            case 'neg': {
+                if (kind(n.of) !== 'number')
+                    throw new Error('a minus sign reads a number.');
+                return 'number';
+            }
+            case 'empty':
+                kind(n.of);
+                return 'boolean';
+            case 'span': {
+                if (kind(n.of) !== 'number')
+                    throw new Error(`"${n.unit}s" counts a number: "3 days", "term months".`);
+                return 'span';
+            }
+            case 'call': {
+                const kinds = n.args.map(kind);
+                if (n.fn === 'round' || n.fn === 'abs') {
+                    if (kinds.some((each) => each !== 'number'))
+                        throw new Error(`${n.fn}(…) reads numbers.`);
+                    return 'number';
+                }
+                const first = kinds[0];
+                if (kinds.some((each) => each !== first))
+                    throw new Error(`${n.fn}(…) takes values of one kind, and has a ${first} and a ${kinds.find((each) => each !== first)}.`);
+                if (first === 'span')
+                    throw new Error(`${n.fn}(…) takes no span of days; add it to a date.`);
+                if (first === 'boolean')
+                    throw new Error(`${n.fn}(…) takes numbers, dates or text, not yes-or-no conditions.`);
+                if (n.fn !== 'coalesce' && first === 'text')
+                    throw new Error(`${n.fn}(…) takes numbers or dates.`);
+                return first;
+            }
+            case 'op': {
+                const l = kind(n.left), r = kind(n.right);
+                if (n.op === 'and' || n.op === 'or') {
+                    if (l !== 'boolean' || r !== 'boolean')
+                        throw new Error(`"${n.op}" joins two yes-or-no conditions.`);
+                    return 'boolean';
+                }
+                if (['=', '!=', '<', '<=', '>', '>='].includes(n.op)) {
+                    if (l !== r && !(l === 'text' && r === 'text'))
+                        throw new Error(`"${n.op}" compares a ${l} with a ${r}.`);
+                    if (l === 'span')
+                        throw new Error('a span of days is not compared; add it to a date.');
+                    return 'boolean';
+                }
+                /* A day has no hours: `today + 2 hours` would be a moment in no stated zone. */
+                const clockOnDay = (date, span) => span.k === 'span' && (span.unit === 'hour' || span.unit === 'minute') && (date.k === 'today' || date.k === 'date');
+                if (clockOnDay(n.left, n.right) || clockOnDay(n.right, n.left))
+                    throw new Error(`today is a day, and hours and minutes move an instant: write now, or a timestamp column.`);
+                if (n.op === '+') {
+                    if (l === 'number' && r === 'number')
+                        return 'number';
+                    if ((l === 'date' && (r === 'number' || r === 'span')) || (r === 'date' && (l === 'number' || l === 'span')))
+                        return 'date';
+                    throw new Error(`"+" adds numbers, or days to a date — not a ${l} and a ${r}.`);
+                }
+                if (n.op === '-') {
+                    if (l === 'number' && r === 'number')
+                        return 'number';
+                    if (l === 'date' && r === 'date')
+                        return 'number';
+                    if (l === 'date' && (r === 'number' || r === 'span'))
+                        return 'date';
+                    throw new Error(`"-" takes numbers, a date from a date (days), or days from a date — not a ${r} from a ${l}.`);
+                }
+                if (l !== 'number' || r !== 'number')
+                    throw new Error(`"${n.op}" reads numbers.`);
+                return 'number';
+            }
+        }
+    };
+    return kind(node);
+}
+/* The instant a statement writes for `now` where the catalog left it as written (foldConstants `keepNow`): the
+   request's own, read when the statement is written, from whoever serves the catalog (tenantServedSchema.ts). A
+   catalog that folded the instant in was a new object for every request, so nothing keyed by the catalog — a
+   parse, a path, a projection — was ever found again; one that leaves it is kept, and the instant travels with the
+   request instead. Nothing here keeps a statement, so no request's instant outlives it. */
+let statementInstant = () => undefined;
+/** A statement that writes `now` was compiled where no request says the instant: a missing wrapper, not a bad definition,
+ * so a caller that turns compile errors into "not shown" lets this one through rather than keep the answer it would give. */
+export class StatementInstantMissing extends Error {
+}
+/** Who says the instant a statement is written at (an ISO string), or undefined where nobody does. */
+export function readStatementInstantFrom(read) {
+    statementInstant = read;
+}
+/** The expression with its constants as this request's values: the App's day, the instant, the reader. `keepNow`
+ * leaves the instant as written, for the statement to write as its request's (statementInstant, above). */
+export function foldConstants(node, values, keepNow = false) {
+    /* Each constant folded is told to whatever keeps the catalog it is folded into (query.ts readsOf). */
+    const fold = (n) => {
+        switch (n.k) {
+            case 'today':
+                noteRead(1);
+                return { k: 'date', value: values.today };
+            case 'now':
+                if (keepNow)
+                    return n;
+                noteRead(2);
+                return { k: 'instant', value: values.now };
+            case 'me':
+                noteRead(0, true);
+                return values.me === null ? { k: 'nobody' } : { k: 'text', value: values.me };
+            case 'op':
+                return { ...n, left: fold(n.left), right: fold(n.right) };
+            case 'call':
+                return { ...n, args: n.args.map(fold) };
+            case 'not':
+            case 'neg':
+            case 'empty':
+            case 'span':
+                return { ...n, of: fold(n.of) };
+            default:
+                return n;
+        }
+    };
+    return fold(node);
+}
+const dialectOf = (style) => style.dialect ?? 'sqlite';
+/**
+ * The expression as SQL on one engine. `column` writes a path the way the
+ * view writes every other (qualified against its joins); `kindOf` is the
+ * same reading of the catalog that typed it, which says where a yes-or-no
+ * column is an integer (SQLite, a PostgreSQL 0/1 flag).
+ */
+export function compileComputed(computed, style, column, kindOf) {
+    const dialect = dialectOf(style);
+    const literal = (text) => `'${text.replace(/'/g, "''")}'`;
+    const truthy = (n) => {
+        if (n.k === 'bool')
+            return dialect === 'postgres' ? (n.value ? 'TRUE' : 'FALSE') : n.value ? '(1 = 1)' : '(1 = 0)';
+        if (n.k === 'path') {
+            const found = kindOf(n.path);
+            /* A native boolean reads as itself; a 0/1 integer as whether it is not 0. */
+            return dialect === 'postgres' && found?.native ? column(n.path) : `(${column(n.path)} <> 0)`;
+        }
+        return sql(n);
+    };
+    const days = (n) => n.k === 'span' ? (n.unit === 'week' ? `(${sql(n.of)}) * 7` : `(${sql(n.of)})`) : `(${sql(n)})`;
+    const unitOf = (n) => (n.k === 'span' ? (n.unit === 'week' ? 'day' : n.unit) : 'day');
+    /* An instant moved by the clock (`now - 30 minutes`), kept an instant rather than cast to its day. */
+    const clocked = (date, amount, sign) => {
+        const n = sign === 1 ? `(${sql(amount.of)})` : `(-(${sql(amount.of)}))`;
+        if (dialect === 'postgres')
+            return `(${date} + ${n} * INTERVAL '1 ${amount.unit}')`;
+        return `datetime(${date}, printf('%+d ${amount.unit}s', CAST(${n} AS INTEGER)))`;
+    };
+    const shifted = (date, amount, sign) => {
+        if (amount.k === 'span' && (amount.unit === 'hour' || amount.unit === 'minute'))
+            return clocked(date, amount, sign);
+        const unit = unitOf(amount);
+        const n = sign === 1 ? days(amount) : `(-${days(amount)})`;
+        if (dialect === 'postgres')
+            return unit === 'day'
+                ? `(CAST(${date} AS DATE) + CAST(${n} AS INTEGER))`
+                : `CAST(CAST(${date} AS DATE) + ${n} * INTERVAL '1 ${unit}' AS DATE)`;
+        return `date(${date}, printf('%+d ${unit}s', CAST(${n} AS INTEGER)))`;
+    };
+    const sql = (n) => {
+        switch (n.k) {
+            case 'path':
+                return column(n.path);
+            case 'number':
+                return String(n.value);
+            case 'text':
+                return literal(n.value);
+            case 'nobody':
+                return 'NULL';
+            case 'bool':
+                return truthy(n);
+            case 'now': {
+                const at = statementInstant();
+                if (at === undefined)
+                    throw new StatementInstantMissing('"now" is read when the catalog is served, or by its request, before a statement is written.');
+                noteRead(2);
+                return sql({ k: 'instant', value: at });
+            }
+            case 'today':
+            case 'me':
+                throw new Error(`"${n.k}" is read when the catalog is served, before a statement is written.`);
+            case 'date':
+                return dialect === 'sqlite' ? literal(n.value) : `DATE ${literal(n.value)}`;
+            case 'instant':
+                return dialect === 'sqlite'
+                    ? literal(n.value.replace('T', ' ').replace(/\.\d+Z$|Z$/, ''))
+                    : dialect === 'postgres'
+                        ? `CAST(${literal(n.value)} AS TIMESTAMPTZ)`
+                        : `TIMESTAMP ${literal(n.value.replace('T', ' ').replace(/\.\d+Z$|Z$/, ''))}`;
+            case 'not':
+                return `(NOT ${truthy(n.of)})`;
+            case 'neg':
+                return `(-(${sql(n.of)}))`;
+            case 'empty':
+                return `(${sql(n.of)} IS ${n.negate ? 'NOT ' : ''}NULL)`;
+            case 'span':
+                return days(n);
+            case 'call': {
+                const args = n.args.map(sql);
+                if (n.fn === 'abs')
+                    return `ABS(${args[0]})`;
+                if (n.fn === 'coalesce')
+                    return `COALESCE(${args.join(', ')})`;
+                if (n.fn === 'round') {
+                    const places = args[1] ?? '0';
+                    /* A half rounds away from zero, of the figure as written: 1.005 is 1.01. PostgreSQL rounds a numeric so (a
+                       double cast to one keeps 15 digits); SQLite rounds the double, which is 1.00499…, so the figure is moved
+                       by its places and said to 15 digits first, as computedValue.ts works it out. */
+                    if (dialect === 'postgres')
+                        return `ROUND(CAST(${args[0]} AS NUMERIC), ${places})`;
+                    const scale = places === '0' ? '' : ` * 1e${places}`;
+                    const back = places === '0' ? '' : ` / 1e${places}`;
+                    return `(CASE WHEN (${args[0]}) IS NULL THEN NULL ELSE ROUND(CAST(printf('%.15g', (${args[0]})${scale}) AS REAL))${back} END)`;
+                }
+                /* SQLite's min and max of several give nothing where one is nothing;
+                   PostgreSQL's LEAST and GREATEST skip a null, so it is said there. */
+                if (dialect === 'sqlite')
+                    return `${n.fn.toUpperCase()}(${args.join(', ')})`;
+                const pick = `${n.fn === 'min' ? 'LEAST' : 'GREATEST'}(${args.join(', ')})`;
+                return `(CASE WHEN ${args.map((arg) => `(${arg}) IS NULL`).join(' OR ')} THEN NULL ELSE ${pick} END)`;
+            }
+            case 'op': {
+                if (n.op === 'and' || n.op === 'or')
+                    return `(${truthy(n.left)} ${n.op.toUpperCase()} ${truthy(n.right)})`;
+                const lk = kindAt(n.left), rk = kindAt(n.right);
+                if (['=', '!=', '<', '<=', '>', '>='].includes(n.op)) {
+                    const op = n.op === '!=' ? '<>' : n.op;
+                    if (lk === 'boolean')
+                        return `(${truthy(n.left)} ${op} ${truthy(n.right)})`;
+                    return `(${sql(n.left)} ${op} ${sql(n.right)})`;
+                }
+                if (n.op === '-' && lk === 'date' && rk === 'date') {
+                    if (dialect === 'postgres')
+                        return `(CAST(${sql(n.left)} AS DATE) - CAST(${sql(n.right)} AS DATE))`;
+                    return `CAST(julianday(date(${sql(n.left)})) - julianday(date(${sql(n.right)})) AS INTEGER)`;
+                }
+                if ((n.op === '+' || n.op === '-') && lk === 'date')
+                    return shifted(sql(n.left), n.right, n.op === '+' ? 1 : -1);
+                if (n.op === '+' && rk === 'date')
+                    return shifted(sql(n.right), n.left, 1);
+                /* Division never truncates and never fails: a number over zero has no value. */
+                if (n.op === '/')
+                    return `((${sql(n.left)}) * 1.0 / NULLIF(${sql(n.right)}, 0))`;
+                return `(${sql(n.left)} ${n.op} ${sql(n.right)})`;
+            }
+        }
+    };
+    const kindAt = (n) => computedKind(n, (path) => kindOf(path)?.kind);
+    /* A yes-or-no column is yes or no, never unknown: a task with no due date is not overdue. */
+    if (computed.type === 'boolean') {
+        return dialect === 'postgres'
+            ? `(CASE WHEN ${truthy(computed.expr)} THEN TRUE ELSE FALSE END)`
+            : `(CASE WHEN ${truthy(computed.expr)} THEN 1 ELSE 0 END)`;
+    }
+    return sql(computed.expr);
+}
+/** Whether an expression says the instant (`now`), so it comes to a moment rather than a day. */
+export function readsNow(node) {
+    if (node.k === 'now' || node.k === 'instant')
+        return true;
+    if (node.k === 'op')
+        return readsNow(node.left) || readsNow(node.right);
+    if (node.k === 'call')
+        return node.args.some(readsNow);
+    if (node.k === 'not' || node.k === 'neg' || node.k === 'empty' || node.k === 'span')
+        return readsNow(node.of);
+    return false;
+}
+/** Whether an expression says the reader (`me`), so it comes to a different value for each. */
+export function readsMe(node) {
+    if (node.k === 'me')
+        return true;
+    if (node.k === 'op')
+        return readsMe(node.left) || readsMe(node.right);
+    if (node.k === 'call')
+        return node.args.some(readsMe);
+    if (node.k === 'not' || node.k === 'neg' || node.k === 'empty' || node.k === 'span')
+        return readsMe(node.of);
+    return false;
+}
+/* Working an expression out in JavaScript is computedValue.ts: its own module,
+   so a page that only reads an expression's shape never fetches the evaluator. */

package/dist/shared/computedParse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * An expression's words read into its tree (computed.ts): the tokenizer and the parser computed columns, a form's
+ * live lines and the App's checks read with. A module of its own because nothing in computed.ts calls it, and a
+ * browser's first page reaches computed.ts (a computed column's meta): what a part loaded on demand uses of a module
+ * the first page reaches is drawn into the first page's chunk, so the parser lived there for a form's live lines.
+ */
+import { type ComputedNode } from './computed.js';
+/**
+ * An expression's tree, or why it is not one. `isColumn` says which bare
+ * words are names: a word on the right of `=` or `!=` that is not one is a
+ * value, as it is in a query (`status = open`).
+ */
+export declare function parseComputed(text: string, isColumn: (path: string) => boolean): ComputedNode;

package/dist/shared/computedParse.js

@@ -0,0 +1,278 @@
+/**
+ * An expression's words read into its tree (computed.ts): the tokenizer and the parser computed columns, a form's
+ * live lines and the App's checks read with. A module of its own because nothing in computed.ts calls it, and a
+ * browser's first page reaches computed.ts (a computed column's meta): what a part loaded on demand uses of a module
+ * the first page reaches is drawn into the first page's chunk, so the parser lived there for a form's live lines.
+ */
+import { ComputedError } from './computed.js';
+/** The functions an expression may call: each written alike on every engine and worked out alike in JavaScript. */
+const COMPUTED_FUNCTIONS = ['coalesce', 'round', 'min', 'max', 'abs'];
+const isFunction = (word) => COMPUTED_FUNCTIONS.includes(word);
+/* The greatest number of places `round` keeps: past it a figure is no longer one an engine says exactly. */
+const ROUND_PLACES = 10;
+const CONSTANTS = new Set(['today', 'now', 'me', 'true', 'false']);
+const UNITS = {
+    minute: 'minute',
+    minutes: 'minute',
+    hour: 'hour',
+    hours: 'hour',
+    day: 'day',
+    days: 'day',
+    week: 'week',
+    weeks: 'week',
+    month: 'month',
+    months: 'month',
+    year: 'year',
+    years: 'year',
+};
+const WORD = /[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*/y;
+function tokens(text) {
+    const out = [];
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        if (/\d/.test(c)) {
+            const m = /\d+(?:\.\d+)?/y;
+            m.lastIndex = i;
+            const n = m.exec(text)[0];
+            out.push({ t: 'number', v: n, at: i });
+            i += n.length;
+            continue;
+        }
+        if (c === "'") {
+            let j = i + 1, value = '';
+            for (;;) {
+                if (j >= text.length)
+                    throw new ComputedError('a quoted text is not closed.', i);
+                if (text[j] === "'") {
+                    if (text[j + 1] === "'") {
+                        value += "'";
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                value += text[j++];
+            }
+            /* Written into the statement between quotes, so held to what every engine reads alike there (recordLabel.ts). */
+            if ([...value].some((ch) => ch === '\\' || ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f)) {
+                throw new ComputedError('a quoted text holds a backslash or a control character, which engines read differently.', i);
+            }
+            out.push({ t: 'text', v: value, at: i });
+            i = j + 1;
+            continue;
+        }
+        const two = text.slice(i, i + 2);
+        if (['!=', '<>', '<=', '>='].includes(two)) {
+            out.push({ t: 'op', v: two === '<>' ? '!=' : two, at: i });
+            i += 2;
+            continue;
+        }
+        if ('=<>+-*/(),'.includes(c)) {
+            out.push({ t: 'op', v: c, at: i });
+            i++;
+            continue;
+        }
+        WORD.lastIndex = i;
+        const w = WORD.exec(text);
+        if (w) {
+            out.push({ t: 'word', v: w[0], at: i });
+            i += w[0].length;
+            continue;
+        }
+        throw new ComputedError(`"${c}" is not part of an expression.`, i);
+    }
+    out.push({ t: 'end', v: '', at: text.length });
+    return out;
+}
+/**
+ * An expression's tree, or why it is not one. `isColumn` says which bare
+ * words are names: a word on the right of `=` or `!=` that is not one is a
+ * value, as it is in a query (`status = open`).
+ */
+export function parseComputed(text, isColumn) {
+    const list = tokens(text);
+    let p = 0;
+    const peek = () => list[p];
+    const word = (v) => peek().t === 'word' && peek().v.toLowerCase() === v;
+    const take = () => list[p++];
+    const expect = (v) => {
+        if (peek().t !== 'op' || peek().v !== v)
+            throw new ComputedError(`expected "${v}"${peek().t === 'end' ? ' before the end' : ` at "${peek().v}"`}.`, peek().at);
+        take();
+    };
+    const or = () => {
+        let left = and();
+        while (word('or')) {
+            take();
+            left = { k: 'op', op: 'or', left, right: and() };
+        }
+        return left;
+    };
+    const and = () => {
+        let left = not();
+        while (word('and')) {
+            take();
+            left = { k: 'op', op: 'and', left, right: not() };
+        }
+        return left;
+    };
+    const not = () => {
+        if (word('not')) {
+            take();
+            return { k: 'not', of: not() };
+        }
+        return compare();
+    };
+    const compare = () => {
+        const left = additive();
+        if (word('is')) {
+            take();
+            const negate = word('not');
+            if (negate)
+                take();
+            if (!word('empty'))
+                throw new ComputedError('say "is empty" or "is not empty".', peek().at);
+            take();
+            return { k: 'empty', of: left, negate };
+        }
+        /* `status in (open, waiting)`, `status not in (done)`: the query language's list, said as the equalities it
+           means, joined by "or", so it types, compiles on every engine and works out in the browser as `=` does. */
+        const negated = word('not') && list[p + 1].t === 'word' && list[p + 1].v.toLowerCase() === 'in';
+        if (negated || word('in')) {
+            if (negated)
+                take();
+            take();
+            expect('(');
+            const items = [];
+            for (;;) {
+                const valueAt = peek();
+                const next = list[p + 1];
+                items.push(left.k === 'path' &&
+                    valueAt.t === 'word' &&
+                    !CONSTANTS.has(valueAt.v.toLowerCase()) &&
+                    !valueAt.v.includes('.') &&
+                    !isColumn(valueAt.v) &&
+                    next.t === 'op' &&
+                    (next.v === ',' || next.v === ')')
+                    ? (take(), { k: 'text', value: valueAt.v })
+                    : additive());
+                if (peek().t === 'op' && peek().v === ',') {
+                    take();
+                    continue;
+                }
+                expect(')');
+                break;
+            }
+            const any = items
+                .map((right) => ({ k: 'op', op: '=', left, right }))
+                .reduce((either, each) => ({ k: 'op', op: 'or', left: either, right: each }));
+            return negated ? { k: 'not', of: any } : any;
+        }
+        const op = peek();
+        if (op.t === 'op' && ['=', '!=', '<', '<=', '>', '>='].includes(op.v)) {
+            take();
+            const valueAt = peek();
+            /* `status = open`: a bare word that names no column is the value, as in a query. */
+            const right = (op.v === '=' || op.v === '!=') &&
+                left.k === 'path' &&
+                valueAt.t === 'word' &&
+                !CONSTANTS.has(valueAt.v.toLowerCase()) &&
+                !valueAt.v.includes('.') &&
+                !isColumn(valueAt.v) &&
+                (list[p + 1].t === 'end' || list[p + 1].t === 'word' || (list[p + 1].t === 'op' && list[p + 1].v === ')'))
+                ? (take(), { k: 'text', value: valueAt.v })
+                : additive();
+            if (op.v === '=' && right.k === 'path' && /^null$/i.test(right.path))
+                throw new ComputedError('"= null" is never true; say "is empty".', valueAt.at);
+            return { k: 'op', op: op.v, left, right };
+        }
+        return left;
+    };
+    const additive = () => {
+        let left = multiplicative();
+        while (peek().t === 'op' && (peek().v === '+' || peek().v === '-')) {
+            const op = take().v;
+            left = { k: 'op', op, left, right: multiplicative() };
+        }
+        return left;
+    };
+    const multiplicative = () => {
+        let left = unary();
+        while (peek().t === 'op' && (peek().v === '*' || peek().v === '/')) {
+            const op = take().v;
+            left = { k: 'op', op, left, right: unary() };
+        }
+        return left;
+    };
+    const unary = () => {
+        if (peek().t === 'op' && peek().v === '-') {
+            take();
+            return { k: 'neg', of: unary() };
+        }
+        const value = primary();
+        /* `3 days`, `term months`: a span a date moves by. */
+        if (peek().t === 'word' && Object.hasOwn(UNITS, peek().v.toLowerCase()))
+            return { k: 'span', of: value, unit: UNITS[take().v.toLowerCase()] };
+        return value;
+    };
+    const primary = () => {
+        const token = take();
+        if (token.t === 'number')
+            return { k: 'number', value: Number(token.v) };
+        if (token.t === 'text')
+            return { k: 'text', value: token.v };
+        if (token.t === 'op' && token.v === '(') {
+            const inner = or();
+            expect(')');
+            return inner;
+        }
+        if (token.t === 'word') {
+            const lower = token.v.toLowerCase();
+            /* `round(total, 2)`: a function's name is a word followed by "(", which no column or value ever is. */
+            if (peek().t === 'op' && peek().v === '(') {
+                if (!isFunction(lower))
+                    throw new ComputedError(`"${token.v}" is not a function; an expression calls ${COMPUTED_FUNCTIONS.join(', ')}.`, token.at);
+                take();
+                const args = [];
+                if (!(peek().t === 'op' && peek().v === ')'))
+                    for (;;) {
+                        args.push(or());
+                        if (peek().t === 'op' && peek().v === ',') {
+                            take();
+                            continue;
+                        }
+                        break;
+                    }
+                expect(')');
+                const fn = lower;
+                const many = fn === 'coalesce' || fn === 'min' || fn === 'max';
+                if (many ? args.length < 2 : fn === 'round' ? args.length < 1 || args.length > 2 : args.length !== 1)
+                    throw new ComputedError(many
+                        ? `${fn}(…) takes two values or more: ${fn}(a, b).`
+                        : fn === 'round'
+                            ? 'round(…) takes a number and, if you like, how many places: round(total) or round(total, 2).'
+                            : `${fn}(…) takes one number.`, token.at);
+                if (fn === 'round' && args[1] && !(args[1].k === 'number' && Number.isInteger(args[1].value) && args[1].value <= ROUND_PLACES))
+                    throw new ComputedError(`round(…)'s places are a whole number from 0 to ${ROUND_PLACES}, written out: round(total, 2).`, token.at);
+                return { k: 'call', fn, args };
+            }
+            if (lower === 'true' || lower === 'false')
+                return { k: 'bool', value: lower === 'true' };
+            if (lower === 'today' || lower === 'now' || lower === 'me')
+                return { k: lower };
+            if (['and', 'or', 'not', 'is', 'empty', 'in'].includes(lower) || Object.hasOwn(UNITS, lower))
+                throw new ComputedError(`"${token.v}" stands where a value goes.`, token.at);
+            return { k: 'path', path: token.v };
+        }
+        throw new ComputedError(token.t === 'end' ? 'the expression ends where a value goes.' : `"${token.v}" stands where a value goes.`, token.at);
+    };
+    const tree = or();
+    if (peek().t !== 'end')
+        throw new ComputedError(`"${peek().v}" follows a complete expression; join two with "and" or "or".`, peek().at);
+    return tree;
+}