@telorun/cel 0.0.0-stage → 0.107.0

package/dist/js-emitter.js

@@ -0,0 +1,562 @@
+/**
+ * The JavaScript emitter: a tree compiled to **source**, not to closures.
+ *
+ * It decides nothing the closure backend decides differently. Every operator and standard
+ * function is the runtime library's, every comprehension is `comprehension-runtime.ts`, and
+ * every member read, name read, bool operand and call-site dispatch is `backend-runtime.ts`
+ * — so what this file produces is a tree of CALLS into those, in the same order, with the
+ * same short-circuit. That is why the two backends can be held to one answer case for case:
+ * the only thing that differs is how control gets from one call to the next.
+ *
+ * Three properties the shape of the output exists for:
+ *
+ * - **The runtime is a parameter, never an import.** The emitted module's default export is
+ *   a factory; it names no specifier, so it loads from a `data:` URL, from a cache directory
+ *   mounted anywhere, and under a host that resolves nothing. A module naming
+ *   `@telorun/cel` would also silently accept a runtime of another version, which the cache
+ *   key could not see.
+ * - **No bare property access implements a CEL read.** `a.b`, `a['b']`, `a[expr]`, `.?`,
+ *   `[?]` and `has()` all emit a call to the member-read seam, so no key an author or a
+ *   request wrote reaches a prototype, a method or a function property. The frame's own
+ *   fields are the engine's structure and are read directly, as they are in a closure.
+ * - **Nothing is asynchronous.** No `async`, no `await`, no promise: a thenable is refused
+ *   at the same doors, because the doors are the shared runtime's.
+ *
+ * Emission is **deterministic**: temporaries are numbered per emitted function in tree
+ * order, bindings per module in tree order, and every hoisted constant is keyed by its own
+ * text, so the same tree against the same environment is the same bytes.
+ */
+import { CelCompileError, plainMemberChain, prefixCandidates, } from "./backend-runtime.js";
+import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
+import { splitDeclaredChain } from "./declared-chain.js";
+import { isMacroCall } from "./macro-check.js";
+/**
+ * The names an emitted module destructures from the runtime it is handed, in the order it
+ * destructures them. It is the module's whole contract with the engine: `emitterRuntime`
+ * (`emitted-module.ts`) builds an object with exactly these keys, and a module emitted by
+ * one engine against another's runtime fails at load rather than running on a missing
+ * binding — which is the second reason the key carries the engine version.
+ */
+export const RUNTIME_BINDINGS = [
+    "asyncValueRefused",
+    "boolOperand",
+    "callSite",
+    "celAll",
+    "celError",
+    "celExists",
+    "celExistsOne",
+    "celFilter",
+    "celIterable",
+    "celMapComprehension",
+    "celMapFromEntries",
+    "celSome",
+    "celUint",
+    "constants",
+    "hasMember",
+    "isCelError",
+    "isCelOptional",
+    "none",
+    "optionalEntry",
+    "optionalOfNonZero",
+    "readHostValue",
+    "readName",
+    "readNameChain",
+    "readThrough",
+    "searchNameChain",
+];
+function boundName(scope, name) {
+    for (let at = scope; at; at = at.outer)
+        if (at.name === name)
+            return at.js;
+    return undefined;
+}
+/**
+ * The temporaries one emitted function declares. Each emitted function — the expression's
+ * own, and every comprehension or binding body inside it — declares its own, because a
+ * body's closure outlives the statement that called it and a name it shares with its caller
+ * would clobber a value still in use.
+ *
+ * **Every name is unique across the MODULE, not within the function**, and that is not
+ * tidiness: a body declaring `let t0` would **shadow** the `t0` its caller holds a bound
+ * value in, so `cel.bind(n, 2, xs.map(e, e + n))` read the element where it meant the
+ * binding and answered `[2, 4, 6]` for `[3, 4, 5]`. Numbering per module makes the shape
+ * impossible rather than avoided.
+ */
+class Temporaries {
+    allocate;
+    names = [];
+    constructor(allocate) {
+        this.allocate = allocate;
+    }
+    next() {
+        const name = this.allocate();
+        this.names.push(name);
+        return name;
+    }
+    /** The `let` that declares them, or nothing where the function used none. */
+    declaration() {
+        return this.names.length === 0 ? "" : `let ${this.names.join(", ")}; `;
+    }
+}
+/**
+ * One module's worth of emission. The hoist table is shared by every expression in the
+ * module, so two expressions reading the same name share one range and one rest-list: a
+ * constant allocated per evaluation is the cost the closure backend does not pay, and
+ * hoisting is how the emitter does not pay it either.
+ */
+export class ModuleEmitter {
+    target;
+    hoisted = [];
+    hoistedByText = new Map();
+    locals = 0;
+    bindings = 0;
+    constructor(target) {
+        this.target = target;
+    }
+    /** The source of one expression's function: a `CelStep` over the evaluation frame. */
+    emitFunction(root) {
+        const temporaries = this.temporaries();
+        const body = this.node(root, undefined, temporaries);
+        return `(frame) => { ${temporaries.declaration()}return ${body}; }`;
+    }
+    /** A fresh function's temporaries, drawing names from the module's own numbering. */
+    temporaries() {
+        return new Temporaries(() => {
+            const name = `t${this.locals}`;
+            this.locals += 1;
+            return name;
+        });
+    }
+    /** The `const` lines every emitted expression reads, in first-use order. */
+    hoistedLines() {
+        return this.hoisted;
+    }
+    hoist(text) {
+        const held = this.hoistedByText.get(text);
+        if (held !== undefined)
+            return held;
+        const name = `h${this.hoisted.length}`;
+        this.hoisted.push(`const ${name} = ${text};`);
+        this.hoistedByText.set(text, name);
+        return name;
+    }
+    range(range) {
+        return this.hoist(`[${range[0]}, ${range[1]}]`);
+    }
+    /**
+     * The name a comprehension's element is bound to: a **parameter** of the body function,
+     * numbered per module so a nested body can never shadow the one around it.
+     */
+    elementName() {
+        const name = `b${this.bindings}`;
+        this.bindings += 1;
+        return name;
+    }
+    // --- the tree -----------------------------------------------------------
+    node(node, scope, fn) {
+        switch (node.kind) {
+            case "literal":
+                return this.literal(node.literal);
+            case "ident":
+                return this.ident(node, scope);
+            case "list":
+                return this.list(node, scope, fn);
+            case "map":
+                return this.map(node, scope, fn);
+            case "select":
+                return this.select(node, scope, fn);
+            case "index":
+                return this.index(node, scope, fn);
+            case "unary":
+                return this.call(node.operator, "global", [this.node(node.operand, scope, fn)], node.range, fn);
+            case "binary":
+                return this.binary(node, scope, fn);
+            case "conditional":
+                return this.conditional(node, scope, fn);
+            case "call":
+            case "receiverCall":
+                return this.anyCall(node, scope, fn);
+            case "qcall":
+                return this.qualifiedCall(node, scope, fn);
+            case "unparsed":
+                throw new CelCompileError("the expression could not be read whole, so it cannot be compiled");
+        }
+    }
+    /**
+     * A literal as the source that builds its value. A plain value is written inline; a uint
+     * and a bytes literal are **hoisted**, because each is an object and allocating one per
+     * evaluation would be work the closure backend does once at compile time.
+     */
+    literal(literal) {
+        switch (literal.type) {
+            case "int":
+                return integerSource(literal.value);
+            case "uint":
+                return this.hoist(`celUint(${integerSource(literal.value)})`);
+            case "double":
+                return doubleSource(literal.value);
+            case "string":
+                return textSource(literal.value);
+            case "bytes":
+                return this.hoist(`new Uint8Array([${[...literal.value].join(", ")}])`);
+            case "bool":
+                return literal.value ? "true" : "false";
+            case "null":
+                return "null";
+        }
+    }
+    // --- names --------------------------------------------------------------
+    ident(node, scope) {
+        if (!node.absolute) {
+            const held = boundName(scope, node.name);
+            if (held !== undefined)
+                return held;
+        }
+        return `readName(frame.activation, constants, ${textSource(node.name)}, ${this.range(node.range)})`;
+    }
+    /**
+     * A chain of plain member names rooted at a free name. The split over the names the host
+     * declared happens **here, at emit time**, through the same function the checker and the
+     * closure backend split it with — so the emitted code performs one activation read and
+     * then member reads, and can never read a different name than the one the check typed.
+     */
+    chain(segments, range) {
+        const declaredSplit = splitDeclaredChain(segments, this.target.declares);
+        const at = this.range(range);
+        if (declaredSplit) {
+            const rest = this.hoist(`[${declaredSplit.rest.map(textSource).join(", ")}]`);
+            return `readNameChain(frame.activation, constants, ${textSource(declaredSplit.name)}, ${rest}, ${at})`;
+        }
+        // Nothing declares a prefix, so the activation is searched longest prefix first — the
+        // same fallback, over the same candidate list, that the closure backend builds.
+        const candidates = this.hoist(`[${prefixCandidates(segments)
+            .map((candidate) => `{ name: ${textSource(candidate.name)}, rest: [${candidate.rest.map(textSource).join(", ")}] }`)
+            .join(", ")}]`);
+        return `searchNameChain(frame.activation, constants, ${candidates}, ${textSource(segments.join("."))}, ${at})`;
+    }
+    // --- member reads -------------------------------------------------------
+    select(node, scope, fn) {
+        const chain = plainMemberChain(node, (name) => boundName(scope, name) !== undefined);
+        if (chain)
+            return this.chain(chain, node.range);
+        const operand = this.node(node.operand, scope, fn);
+        const at = this.range(node.range);
+        return this.carrying([operand], fn, ([held]) => `readThrough(${held}, ${textSource(node.field)}, ${node.optional}, ${at})`);
+    }
+    index(node, scope, fn) {
+        const operand = this.node(node.operand, scope, fn);
+        const key = this.node(node.index, scope, fn);
+        const at = this.range(node.range);
+        return this.carrying([operand, key], fn, ([held, named]) => `readThrough(${held}, ${named}, ${node.optional}, ${at})`);
+    }
+    // --- aggregates ---------------------------------------------------------
+    list(node, scope, fn) {
+        const out = fn.next();
+        const at = this.range(node.range);
+        const entries = node.elements.map((element) => ({
+            value: this.node(element.value, scope, fn),
+            optional: element.optional,
+        }));
+        let body = out;
+        for (let index = entries.length - 1; index >= 0; index -= 1) {
+            const entry = entries[index];
+            const value = fn.next();
+            if (!entry.optional) {
+                body = `(${value} = ${entry.value}, isCelError(${value}) ? ${value} : (${out}.push(${value}), ${body}))`;
+                continue;
+            }
+            // An absent optional entry leaves no element: the aggregate shrinks, which is the
+            // whole reason to write one.
+            const held = fn.next();
+            body =
+                `(${value} = ${entry.value}, isCelError(${value}) ? ${value} : ` +
+                    `(${held} = optionalEntry(${value}, ${at}), isCelError(${held}) ? ${held} : ` +
+                    `(${held}.present && ${out}.push(${held}.held), ${body})))`;
+        }
+        return `(${out} = [], ${body})`;
+    }
+    map(node, scope, fn) {
+        const out = fn.next();
+        const at = this.range(node.range);
+        const entries = node.entries.map((entry) => ({
+            key: this.node(entry.key, scope, fn),
+            value: this.node(entry.value, scope, fn),
+            optional: entry.optional,
+        }));
+        let body = `celMapFromEntries(${out}, ${at})`;
+        for (let index = entries.length - 1; index >= 0; index -= 1) {
+            const entry = entries[index];
+            const key = fn.next();
+            const value = fn.next();
+            const kept = entry.optional ? fn.next() : undefined;
+            const written = kept
+                ? `(${kept} = optionalEntry(${value}, ${at}), isCelError(${kept}) ? ${kept} : ` +
+                    `(${kept}.present && ${out}.push([${key}, ${kept}.held]), ${body}))`
+                : `(${out}.push([${key}, ${value}]), ${body})`;
+            body =
+                `(${key} = ${entry.key}, isCelError(${key}) ? ${key} : ` +
+                    `(${value} = ${entry.value}, isCelError(${value}) ? ${value} : ${written}))`;
+        }
+        return `(${out} = [], ${body})`;
+    }
+    // --- operators ----------------------------------------------------------
+    /**
+     * `&&` and `||` carry an error-valued operand through: `false && <error>` is `false` and
+     * `true || <error>` is `true`, whichever side the error is on. The emitted form is the
+     * closure backend's branch order written out, so an error on one side and a non-bool on
+     * the other decide the same way.
+     */
+    binary(node, scope, fn) {
+        if (node.operator !== "&&" && node.operator !== "||") {
+            return this.call(node.operator, "global", [this.node(node.left, scope, fn), this.node(node.right, scope, fn)], node.range, fn);
+        }
+        const left = this.node(node.left, scope, fn);
+        const right = this.node(node.right, scope, fn);
+        const at = this.range(node.range);
+        const decided = node.operator === "&&" ? "false" : "true";
+        const undecided = node.operator === "&&" ? "true" : "false";
+        const a = fn.next();
+        const b = fn.next();
+        return (`(${a} = boolOperand(${left}, ${at}), ${a} === ${decided} ? ${decided} : ` +
+            `(${b} = boolOperand(${right}, ${at}), ${b} === ${decided} ? ${decided} : ` +
+            `isCelError(${a}) ? ${a} : isCelError(${b}) ? ${b} : ${undecided}))`);
+    }
+    conditional(node, scope, fn) {
+        const condition = this.node(node.condition, scope, fn);
+        const whenTrue = this.node(node.whenTrue, scope, fn);
+        const whenFalse = this.node(node.whenFalse, scope, fn);
+        const at = this.range(node.range);
+        const held = fn.next();
+        return (`(${held} = boolOperand(${condition}, ${at}), isCelError(${held}) ? ${held} : ` +
+            `${held} ? ${whenTrue} : ${whenFalse})`);
+    }
+    // --- calls --------------------------------------------------------------
+    anyCall(node, scope, fn) {
+        // The same question the checker asks, in the same place: a macro is not a function, and
+        // it is recognised before any overload is looked for.
+        if (isMacroCall(node))
+            return this.macro(node, scope, fn);
+        const args = [
+            ...(node.kind === "receiverCall" ? [this.node(node.receiver, scope, fn)] : []),
+            ...node.args.map((argument) => this.node(argument, scope, fn)),
+        ];
+        return this.call(node.name, node.kind === "call" ? "global" : "receiver", args, node.range, fn);
+    }
+    /**
+     * One dispatch: evaluate the arguments, carry the first error out, then hand the values to
+     * the site. The site is hoisted, so it is built once per loaded module and holds the
+     * overloads it resolved — exactly as a compiled closure's does.
+     */
+    call(name, form, args, range, fn) {
+        const site = this.hoist(`callSite(${textSource(name)}, ${textSource(form)}, ${this.range(range)})`);
+        return this.carrying(args, fn, (values) => `${site}.call([${values.join(", ")}])`);
+    }
+    qualifiedCall(node, scope, fn) {
+        const args = node.args.map((argument) => this.node(argument, scope, fn));
+        const at = this.range(node.range);
+        const context = this.hoist(`{ range: ${at} }`);
+        const bound = fn.next();
+        // The arguments are evaluated only once something IS bound, which is the closure
+        // backend's order: a call nothing bound is `unbound_function` even where an argument
+        // would have failed.
+        const dispatched = this.carrying(args, fn, (values) => `readHostValue(${bound}([${values.join(", ")}], ${context}), ${at})`);
+        const refusal = `celError("unbound_function", ${textSource(`unbound function '${node.namespace}.${node.name}' — nothing is bound under that name here`)}, ${at})`;
+        return (`(${bound} = frame.namespaceFunction ? frame.namespaceFunction(${textSource(node.namespace)}, ` +
+            `${textSource(node.name)}) : undefined, !${bound} ? ${refusal} : ${dispatched})`);
+    }
+    // --- macros -------------------------------------------------------------
+    macro(node, scope, fn) {
+        if (node.kind === "call")
+            return this.has(node, scope, fn);
+        const receiver = node.receiver;
+        if (receiver.kind === "ident" && receiver.name === "cel" && node.name === "bind") {
+            return this.celBind(node, scope, fn);
+        }
+        if (receiver.kind === "ident" && receiver.name === "optional") {
+            return this.optionalNamespace(node, scope, fn);
+        }
+        if ((node.name === "optMap" || node.name === "optFlatMap") && node.args.length === 2) {
+            return this.optionalBinding(node, scope, fn);
+        }
+        return this.comprehension(node, scope, fn);
+    }
+    /** `has(a.b)` — presence, which a missing key answers `false` rather than erroring. */
+    has(node, scope, fn) {
+        const argument = node.args[0];
+        if (argument.kind !== "select") {
+            throw new CelCompileError("has() asks about a member, so its argument ends in a select");
+        }
+        const operand = this.node(argument.operand, scope, fn);
+        const at = this.range(node.range);
+        return this.carrying([operand], fn, ([held]) => `hasMember(${held}, ${textSource(argument.field)}, ${at})`);
+    }
+    celBind(node, scope, fn) {
+        const binding = namespaceMacroBinding("cel", node.name, node.args.length);
+        if (!binding) {
+            throw new CelCompileError("cel.bind(name, value, body) takes a name, its value and a body");
+        }
+        const name = node.args[binding.variableArgument];
+        if (name.kind !== "ident")
+            throw new CelCompileError("cel.bind binds a name");
+        const value = this.node(node.args[1], scope, fn);
+        // The bound value lives in a temporary of the enclosing function, so it is DECLARED
+        // there: a body nested inside this one captures it as a closure captures any `let`.
+        const held = fn.next();
+        const body = this.node(node.args[2], { name: name.name, js: held, outer: scope }, fn);
+        const at = this.range(node.range);
+        const refused = fn.next();
+        // A name is bound to a VALUE, so a value that must be awaited is refused here rather
+        // than inside the body, where every read of the name would meet it again.
+        return (`(${held} = ${value}, isCelError(${held}) ? ${held} : ` +
+            `(${refused} = asyncValueRefused(${held}, ${at}), ${refused} ? ${refused} : ${body}))`);
+    }
+    /** `optional.of(v)`, `optional.ofNonZeroValue(v)` and `optional.none()`. */
+    optionalNamespace(node, scope, fn) {
+        if (node.name === "none")
+            return "none";
+        if (node.args.length !== 1) {
+            throw new CelCompileError(`optional.${node.name}(value) takes one argument`);
+        }
+        const value = this.node(node.args[0], scope, fn);
+        const wrap = node.name === "ofNonZeroValue" ? "optionalOfNonZero" : "celSome";
+        return this.carrying([value], fn, ([held]) => `${wrap}(${held})`);
+    }
+    /** `opt.optMap(v, body)` wraps what the body answers; `optFlatMap` does not. */
+    optionalBinding(node, scope, fn) {
+        const name = node.args[0];
+        if (name.kind !== "ident")
+            throw new CelCompileError(`${node.name} binds a name`);
+        const receiver = this.node(node.receiver, scope, fn);
+        const at = this.range(node.range);
+        const optional = fn.next();
+        const refused = fn.next();
+        const answered = fn.next();
+        const held = fn.next();
+        const body = this.node(node.args[1], { name: name.name, js: held, outer: scope }, fn);
+        const wrong = `celError("no_matching_overload", ${textSource(`${JSON.stringify(node.name)} reads an optional`)}, ${at})`;
+        const result = node.name === "optMap"
+            ? `celSome(${answered})`
+            : `isCelOptional(${answered}) ? ${answered} : celError("no_matching_overload", ` +
+                `${textSource("optFlatMap's body answers an optional")}, ${at})`;
+        // A host may hand over the optional itself, so what it HOLDS is a door of its own.
+        return (`(${optional} = ${receiver}, isCelError(${optional}) ? ${optional} : ` +
+            `!isCelOptional(${optional}) ? ${wrong} : ` +
+            `!${optional}.present ? none : ` +
+            `(${refused} = asyncValueRefused(${optional}.held, ${at}), ${refused} ? ${refused} : ` +
+            `(${held} = ${optional}.held, ${answered} = ${body}, isCelError(${answered}) ? ${answered} : ${result})))`);
+    }
+    /**
+     * A comprehension. The body becomes a function of the element, exactly as the closure
+     * backend passes one, so the macro's meaning — including which error outranks which
+     * decided answer — stays `comprehension-runtime.ts`'s alone.
+     */
+    comprehension(node, scope, fn) {
+        const binding = receiverMacroBinding(node.name, node.args.length);
+        if (!binding)
+            throw new CelCompileError(`${node.name} is not a comprehension`);
+        const name = node.args[binding.variableArgument];
+        if (name.kind !== "ident")
+            throw new CelCompileError(`${node.name} binds a name`);
+        const receiver = this.node(node.receiver, scope, fn);
+        const at = this.range(node.range);
+        const element = this.elementName();
+        const inner = { name: name.name, js: element, outer: scope };
+        const bodies = binding.scopedArguments.map((argument) => this.body(node.args[argument], inner, element));
+        const elements = fn.next();
+        const call = (() => {
+            switch (node.name) {
+                case "all":
+                    return `celAll(${elements}, ${bodies[0]}, ${at})`;
+                case "exists":
+                    return `celExists(${elements}, ${bodies[0]}, ${at})`;
+                case "exists_one":
+                    return `celExistsOne(${elements}, ${bodies[0]}, ${at})`;
+                case "filter":
+                    return `celFilter(${elements}, ${bodies[0]}, ${at})`;
+                default:
+                    return bodies.length === 2
+                        ? `celMapComprehension(${elements}, ${bodies[1]}, ${bodies[0]}, ${at})`
+                        : `celMapComprehension(${elements}, ${bodies[0]}, undefined, ${at})`;
+            }
+        })();
+        return this.carrying([receiver], fn, ([held]) => `(${elements} = celIterable(${held}, ${at}), isCelError(${elements}) ? ${elements} : ${call})`);
+    }
+    /** A body a comprehension calls per element: its own function, with its own temporaries. */
+    body(node, scope, parameter) {
+        const temporaries = this.temporaries();
+        const text = this.node(node, scope, temporaries);
+        return `(${parameter}) => { ${temporaries.declaration()}return ${text}; }`;
+    }
+    // --- the one sequencing rule --------------------------------------------
+    /**
+     * Evaluate each expression in order and carry the first error out, then build the answer
+     * from the values. Every form that evaluates more than one thing goes through here, so a
+     * later operand is never evaluated after an earlier one failed — which is what makes an
+     * error a value that short-circuits rather than an exception.
+     */
+    carrying(expressions, fn, answer) {
+        const values = expressions.map(() => fn.next());
+        let out = answer(values);
+        for (let at = expressions.length - 1; at >= 0; at -= 1) {
+            out = `(${values[at]} = ${expressions[at]}, isCelError(${values[at]}) ? ${values[at]} : ${out})`;
+        }
+        return out;
+    }
+}
+// --- writing a value as source ---------------------------------------------
+/** An int or uint literal as a `bigint`, parenthesized where it is negative. */
+function integerSource(value) {
+    return value < 0n ? `(${value}n)` : `${value}n`;
+}
+/**
+ * A double as source. `-0` is a value CEL tells apart from `0`, and an overflowing literal
+ * reads as an infinity, so neither may go through the shortest decimal form.
+ */
+function doubleSource(value) {
+    if (Number.isNaN(value))
+        return "NaN";
+    if (value === Number.POSITIVE_INFINITY)
+        return "Infinity";
+    if (value === Number.NEGATIVE_INFINITY)
+        return "(-Infinity)";
+    if (Object.is(value, -0))
+        return "(-0)";
+    return value < 0 ? `(${value})` : `${value}`;
+}
+const ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\v": "\\v",
+};
+/**
+ * Text as a JavaScript string literal. Every character outside printable ASCII is written
+ * as an escape — a lone surrogate, a line separator and a zero-width joiner all read back
+ * as themselves, and the emitted module is pure ASCII however its expressions were written,
+ * so no encoding assumption about the file it is stored in can change its meaning.
+ */
+export function textSource(text) {
+    let out = '"';
+    for (const unit of text) {
+        const held = ESCAPES[unit];
+        if (held !== undefined) {
+            out += held;
+            continue;
+        }
+        const code = unit.codePointAt(0);
+        if (code >= 0x20 && code <= 0x7e) {
+            out += unit;
+            continue;
+        }
+        if (code > 0xffff) {
+            out += `\\u{${code.toString(16)}}`;
+            continue;
+        }
+        out += `\\u${code.toString(16).padStart(4, "0")}`;
+    }
+    return `${out}"`;
+}