@telorun/cel 0.0.0-stage → 0.108.0

package/dist/integer-arithmetic.js

@@ -0,0 +1,58 @@
+/**
+ * Integer arithmetic: 64-bit, checked, and **never wrapped**.
+ *
+ * CEL's `int` is a signed 64-bit integer and its `uint` an unsigned one. A result
+ * outside the range is an error, not a wrap: an engine that wraps answers a value no
+ * other engine answers, and a manifest that silently computes `-9223372036854775808`
+ * from a sum of positives is worse than one that fails. The vectors pin this as the
+ * domain-keeping answer where the engine being replaced returns a number beyond int64.
+ *
+ * Division truncates toward zero and the modulo takes the dividend's sign, which is
+ * what `BigInt` already does; division and modulo by zero are errors of their own, so a
+ * reader of the code knows which one happened.
+ */
+import { celError, celUint } from "./cel-value.js";
+import { MAX_INT, MAX_UINT, MIN_INT } from "./lexer.js";
+const MAX_UINT_PLUS_ONE = MAX_UINT + 1n;
+function overflow(range, result, what) {
+    return celError("numeric_overflow", `${what} overflow: ${result}`, range);
+}
+/** An int result, or the overflow it is outside the range. */
+export function intResult(value, range) {
+    if (value < MIN_INT || value > MAX_INT)
+        return overflow(range, value, "integer");
+    return value;
+}
+/** A uint result, or the overflow it is outside the range. */
+export function uintResult(value, range) {
+    if (value < 0n || value > MAX_UINT)
+        return overflow(range, value, "unsigned integer");
+    return celUint(value);
+}
+export function intDivide(left, right, range) {
+    if (right === 0n)
+        return celError("division_by_zero", "division by zero", range);
+    return intResult(left / right, range);
+}
+export function intModulo(left, right, range) {
+    if (right === 0n)
+        return celError("modulo_by_zero", "modulus by zero", range);
+    return intResult(left % right, range);
+}
+export function uintDivide(left, right, range) {
+    if (right === 0n)
+        return celError("division_by_zero", "division by zero", range);
+    return uintResult(left / right, range);
+}
+export function uintModulo(left, right, range) {
+    if (right === 0n)
+        return celError("modulo_by_zero", "modulus by zero", range);
+    return uintResult(left % right, range);
+}
+/** Whether a magnitude fits a uint64 — used by the conversions. */
+export function fitsUint(value) {
+    return value >= 0n && value < MAX_UINT_PLUS_ONE;
+}
+export function fitsInt(value) {
+    return value >= MIN_INT && value <= MAX_INT;
+}

package/dist/js-emitter.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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 { type CompileTarget } from "./backend-runtime.js";
+import type { CelNode } from "./syntax-tree.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 declare const RUNTIME_BINDINGS: readonly ["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"];
+export type RuntimeBinding = (typeof RUNTIME_BINDINGS)[number];
+/**
+ * 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 declare class ModuleEmitter {
+    private readonly target;
+    private readonly hoisted;
+    private readonly hoistedByText;
+    private locals;
+    private bindings;
+    constructor(target: CompileTarget);
+    /** The source of one expression's function: a `CelStep` over the evaluation frame. */
+    emitFunction(root: CelNode): string;
+    /** A fresh function's temporaries, drawing names from the module's own numbering. */
+    private temporaries;
+    /** The `const` lines every emitted expression reads, in first-use order. */
+    hoistedLines(): readonly string[];
+    private hoist;
+    private range;
+    /**
+     * 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.
+     */
+    private elementName;
+    private node;
+    /**
+     * 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.
+     */
+    private literal;
+    private ident;
+    /**
+     * 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.
+     */
+    private chain;
+    private select;
+    private index;
+    private list;
+    private map;
+    /**
+     * `&&` 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.
+     */
+    private binary;
+    private conditional;
+    private anyCall;
+    /**
+     * One dispatch: evaluate the arguments, carry the first error out, then hand the values to
+     * the site **positionally**. 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. The arity is the
+     * dispatch key's, so the entry point is chosen here and no argument array is built.
+     */
+    private call;
+    private qualifiedCall;
+    private macro;
+    /** `has(a.b)` — presence, which a missing key answers `false` rather than erroring. */
+    private has;
+    private celBind;
+    /** `optional.of(v)`, `optional.ofNonZeroValue(v)` and `optional.none()`. */
+    private optionalNamespace;
+    /** `opt.optMap(v, body)` wraps what the body answers; `optFlatMap` does not. */
+    private optionalBinding;
+    /**
+     * 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.
+     */
+    private comprehension;
+    /** A body a comprehension calls per element: its own function, with its own temporaries. */
+    private body;
+    /**
+     * 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.
+     */
+    private carrying;
+}
+/**
+ * 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 declare function textSource(text: string): string;
+//# sourceMappingURL=js-emitter.d.ts.map

package/dist/js-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"js-emitter.d.ts","sourceRoot":"","sources":["../src/js-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,KAAK,EAAc,OAAO,EAA8B,MAAM,kBAAkB,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,mYA0BnB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AA2C/D;;;;;GAKG;AACH,qBAAa,aAAa;IAMZ,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;gBAEQ,MAAM,EAAE,aAAa;IAElD,sFAAsF;IACtF,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM;IAMnC,qFAAqF;IACrF,OAAO,CAAC,WAAW;IAQnB,4EAA4E;IAC5E,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,KAAK;IAIb;;;OAGG;IACH,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,IAAI;IA8BZ;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAqBf,OAAO,CAAC,KAAK;IAQb;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAsBb,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,KAAK;IAiBb,OAAO,CAAC,IAAI;IA8BZ,OAAO,CAAC,GAAG;IA+BX;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IA4Bd,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,OAAO;IAef;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAmBZ,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,KAAK;IAmBb,uFAAuF;IACvF,OAAO,CAAC,GAAG;IAkBX,OAAO,CAAC,OAAO;IA0Bf,4EAA4E;IAC5E,OAAO,CAAC,iBAAiB;IAczB,gFAAgF;IAChF,OAAO,CAAC,eAAe;IA8BvB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAuCrB,4FAA4F;IAC5F,OAAO,CAAC,IAAI;IAQZ;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;CAYjB;AAgCD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoB/C"}