@telorun/cel 0.0.0-stage → 0.108.0

package/dist/syntax-tree.js

@@ -0,0 +1,58 @@
+/**
+ * The canonical CEL syntax tree.
+ *
+ * Every node carries `range`, the half-open `[start, end)` span of UTF-16 code
+ * units it covers in the source it was parsed from, so a diagnostic, a hover or a
+ * rename can point at the text the author wrote. A tree built by hand carries
+ * ranges too — the serializer and the queries read them, and a node with none
+ * would make either answer silently wrong.
+ *
+ * Literals hold their decoded value in a tagged form rather than as a bare
+ * JavaScript value: CEL's `int` and `uint` are both arbitrary-magnitude integers,
+ * `1` and `1u` are different expressions, and a backend must be able to tell them
+ * apart without consulting a runtime value class.
+ *
+ * `qcall` is the one node the parser never produces — see `namespace-resolution.ts`.
+ */
+/** Every child node, in source order. The single reader of a node's shape for traversal. */
+export function childNodes(node) {
+    switch (node.kind) {
+        case "literal":
+        case "ident":
+        case "unparsed":
+            return [];
+        case "list":
+            return node.elements.map((element) => element.value);
+        case "map":
+            return node.entries.flatMap((entry) => [entry.key, entry.value]);
+        case "select":
+            return [node.operand];
+        case "index":
+            return [node.operand, node.index];
+        case "call":
+            return node.args;
+        case "receiverCall":
+            return [node.receiver, ...node.args];
+        case "qcall":
+            return node.args;
+        case "unary":
+            return [node.operand];
+        case "binary":
+            return [node.left, node.right];
+        case "conditional":
+            return [node.condition, node.whenTrue, node.whenFalse];
+    }
+}
+/** Depth-first pre-order walk over the whole tree. */
+export function* walkTree(root) {
+    yield root;
+    for (const child of childNodes(root))
+        yield* walkTree(child);
+}
+/** Whether any node of the tree is an unparsed hole. */
+export function hasUnparsed(root) {
+    for (const node of walkTree(root))
+        if (node.kind === "unparsed")
+            return true;
+    return false;
+}

package/dist/timestamp-value.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Instants: reading one, writing one, and reading a field of one in a time zone.
+ *
+ * A timestamp is whole seconds plus nanoseconds in `[0, 1e9)`, because cel-spec's own
+ * rows carry nanosecond instants (`string(timestamp('9999-12-31T23:59:59.999999999Z'))`)
+ * and no host date type holds them. The range is cel-spec's: `0001-01-01T00:00:00Z`
+ * through `9999-12-31T23:59:59.999999999Z`, and an instant outside it is an error
+ * wherever it would be built — which is exactly the answer the vectors call
+ * domain-keeping where the engine being replaced returns a date beyond year 9999.
+ *
+ * **A zone is named, never computed here.** A getter takes an IANA name or a fixed
+ * `±HH:MM` offset; the rules behind a name are the host's data, which no release of this
+ * engine fixes, so the only thing this file decides is how a name is applied.
+ */
+import { type CelError, type CelTimestamp } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+/** `0001-01-01T00:00:00Z` and `9999-12-31T23:59:59Z`, in seconds since the epoch. */
+export declare const MIN_TIMESTAMP_SECONDS = -62135596800n;
+export declare const MAX_TIMESTAMP_SECONDS = 253402300799n;
+/** An instant from seconds and nanoseconds of any sign, normalized, or the range error. */
+export declare function celTimestamp(seconds: bigint, nanos?: bigint | number, range?: SourceRange): CelTimestamp | CelError;
+/**
+ * An instant from epoch MILLISECONDS — the mirror of `celDurationFromNanos` for a host
+ * clock reading (`Date.now()`, a driver's epoch-millis column), or the range error.
+ *
+ * It exists so that a host never has to reach for its own date type to say "now": the
+ * instance type is seconds plus nanos, and a millisecond reading is the one other shape
+ * a host actually holds. A fractional reading keeps its sub-millisecond part.
+ */
+export declare function celTimestampFromMillis(millis: number, range?: SourceRange): CelTimestamp | CelError;
+/** The instant's nanoseconds since the epoch — what arithmetic and ordering compare. */
+export declare function timestampNanos(value: CelTimestamp): bigint;
+/** An instant from RFC 3339 text, with any offset and any fractional precision. */
+export declare function parseTimestamp(text: string, range?: SourceRange): CelTimestamp | CelError;
+/**
+ * RFC 3339 in UTC, with the fraction written to the precision it carries and omitted
+ * when the instant is whole — cel-spec's own spelling (`2009-02-13T23:31:30Z`).
+ */
+export declare function formatTimestamp(value: CelTimestamp): string;
+export interface CivilFields {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/**
+ * The civil fields of an instant in a zone. A zone is an IANA name, resolved by the
+ * host's own tz database, or a fixed `±HH:MM` offset, which is arithmetic; an unsigned
+ * offset is read as ahead of UTC, as cel-spec's own rows read it.
+ */
+export declare function zonedFields(value: CelTimestamp, zone: string | undefined, range?: SourceRange): CivilFields | CelError;
+/** Which field of an instant a getter answers. The names are cel-spec's. */
+export type TimestampField = "getFullYear" | "getMonth" | "getDayOfYear" | "getDayOfMonth" | "getDate" | "getDayOfWeek" | "getHours" | "getMinutes" | "getSeconds" | "getMilliseconds";
+/**
+ * A field of an instant. `getMonth`, `getDayOfMonth` and `getDayOfYear` are **zero
+ * based** and `getDate` is one based, which is cel-spec's own split; `getDayOfWeek`
+ * counts from Sunday.
+ */
+export declare function timestampField(value: CelTimestamp, field: TimestampField, zone?: string, range?: SourceRange): bigint | CelError;
+//# sourceMappingURL=timestamp-value.d.ts.map

package/dist/timestamp-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-value.d.ts","sourceRoot":"","sources":["../src/timestamp-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AACnD,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAInD,2FAA2F;AAC3F,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAAM,GAAG,MAAU,EAC1B,KAAK,CAAC,EAAE,WAAW,GAClB,YAAY,GAAG,QAAQ,CAYzB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,QAAQ,CAMnG;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAE1D;AAKD,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,QAAQ,CAgCzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAK3D;AAaD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAgED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,CAAC,EAAE,WAAW,GAClB,WAAW,GAAG,QAAQ,CAYxB;AAsCD,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,UAAU,GACV,cAAc,GACd,eAAe,GACf,SAAS,GACT,cAAc,GACd,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,iBAAiB,CAAC;AAEtB;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,WAAW,GAClB,MAAM,GAAG,QAAQ,CA0BnB"}

package/dist/timestamp-value.js

@@ -0,0 +1,238 @@
+/**
+ * Instants: reading one, writing one, and reading a field of one in a time zone.
+ *
+ * A timestamp is whole seconds plus nanoseconds in `[0, 1e9)`, because cel-spec's own
+ * rows carry nanosecond instants (`string(timestamp('9999-12-31T23:59:59.999999999Z'))`)
+ * and no host date type holds them. The range is cel-spec's: `0001-01-01T00:00:00Z`
+ * through `9999-12-31T23:59:59.999999999Z`, and an instant outside it is an error
+ * wherever it would be built — which is exactly the answer the vectors call
+ * domain-keeping where the engine being replaced returns a date beyond year 9999.
+ *
+ * **A zone is named, never computed here.** A getter takes an IANA name or a fixed
+ * `±HH:MM` offset; the rules behind a name are the host's data, which no release of this
+ * engine fixes, so the only thing this file decides is how a name is applied.
+ */
+import { celError, CEL_VALUE_TYPE, isCelError, } from "./cel-value.js";
+/** `0001-01-01T00:00:00Z` and `9999-12-31T23:59:59Z`, in seconds since the epoch. */
+export const MIN_TIMESTAMP_SECONDS = -62135596800n;
+export const MAX_TIMESTAMP_SECONDS = 253402300799n;
+const NANOS_PER_SECOND = 1000000000n;
+/** An instant from seconds and nanoseconds of any sign, normalized, or the range error. */
+export function celTimestamp(seconds, nanos = 0, range) {
+    const total = BigInt(nanos);
+    let whole = seconds + total / NANOS_PER_SECOND;
+    let rest = total % NANOS_PER_SECOND;
+    if (rest < 0n) {
+        whole -= 1n;
+        rest += NANOS_PER_SECOND;
+    }
+    if (whole < MIN_TIMESTAMP_SECONDS || whole > MAX_TIMESTAMP_SECONDS) {
+        return celError("invalid_conversion", "timestamp out of range", range);
+    }
+    return { [CEL_VALUE_TYPE]: "google.protobuf.Timestamp", seconds: whole, nanos: Number(rest) };
+}
+/**
+ * An instant from epoch MILLISECONDS — the mirror of `celDurationFromNanos` for a host
+ * clock reading (`Date.now()`, a driver's epoch-millis column), or the range error.
+ *
+ * It exists so that a host never has to reach for its own date type to say "now": the
+ * instance type is seconds plus nanos, and a millisecond reading is the one other shape
+ * a host actually holds. A fractional reading keeps its sub-millisecond part.
+ */
+export function celTimestampFromMillis(millis, range) {
+    if (!Number.isFinite(millis)) {
+        return celError("invalid_conversion", "timestamp out of range", range);
+    }
+    const whole = Math.floor(millis / 1000);
+    return celTimestamp(BigInt(whole), Math.round((millis - whole * 1000) * 1_000_000), range);
+}
+/** The instant's nanoseconds since the epoch — what arithmetic and ordering compare. */
+export function timestampNanos(value) {
+    return value.seconds * NANOS_PER_SECOND + BigInt(value.nanos);
+}
+const RFC_3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/;
+/** An instant from RFC 3339 text, with any offset and any fractional precision. */
+export function parseTimestamp(text, range) {
+    const parts = RFC_3339.exec(text);
+    if (!parts) {
+        return celError("invalid_conversion", `${JSON.stringify(text)} is not an RFC 3339 instant`, range);
+    }
+    const [, year, month, day, hour, minute, second, fraction, sign, offsetHours, offsetMinutes] = parts;
+    const fields = {
+        year: Number(year),
+        month: Number(month),
+        day: Number(day),
+        hour: Number(hour),
+        minute: Number(minute),
+        second: Number(second),
+    };
+    if (fields.month < 1 ||
+        fields.month > 12 ||
+        fields.day < 1 ||
+        fields.day > daysInMonth(fields.year, fields.month) ||
+        fields.hour > 23 ||
+        fields.minute > 59 ||
+        fields.second > 59) {
+        return celError("invalid_conversion", `${JSON.stringify(text)} is not an instant`, range);
+    }
+    let seconds = secondsFromFields(fields);
+    if (sign) {
+        const offset = BigInt(Number(offsetHours) * 3600 + Number(offsetMinutes) * 60);
+        seconds += sign === "-" ? offset : -offset;
+    }
+    const nanos = fraction ? Number(`${fraction}000000000`.slice(0, 9)) : 0;
+    return celTimestamp(seconds, nanos, range);
+}
+/**
+ * RFC 3339 in UTC, with the fraction written to the precision it carries and omitted
+ * when the instant is whole — cel-spec's own spelling (`2009-02-13T23:31:30Z`).
+ */
+export function formatTimestamp(value) {
+    const fields = utcFields(value.seconds);
+    const date = `${pad(fields.year, 4)}-${pad(fields.month, 2)}-${pad(fields.day, 2)}`;
+    const time = `${pad(fields.hour, 2)}:${pad(fields.minute, 2)}:${pad(fields.second, 2)}`;
+    return `${date}T${time}${fractionText(value.nanos)}Z`;
+}
+function fractionText(nanos) {
+    if (nanos === 0)
+        return "";
+    return `.${pad(nanos, 9).replace(/0+$/, "")}`;
+}
+function pad(value, width) {
+    return String(value).padStart(width, "0");
+}
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+function daysInMonth(year, month) {
+    return month === 2 && isLeapYear(year) ? 29 : MONTH_DAYS[month - 1];
+}
+/** Days from the epoch to a civil date, by Howard Hinnant's `days_from_civil`. */
+function daysFromCivil(year, month, day) {
+    const shifted = month <= 2 ? year - 1 : year;
+    const era = Math.floor(shifted / 400);
+    const yearOfEra = shifted - era * 400;
+    const dayOfYear = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
+    const dayOfEra = yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100) + dayOfYear;
+    return era * 146097 + dayOfEra - 719468;
+}
+/** The civil date a day count names, the inverse of `daysFromCivil`. */
+function civilFromDays(days) {
+    const shifted = days + 719468;
+    const era = Math.floor(shifted / 146097);
+    const dayOfEra = shifted - era * 146097;
+    const yearOfEra = Math.floor((dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365);
+    const year = yearOfEra + era * 400;
+    const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+    const monthPrime = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthPrime + 2) / 5) + 1;
+    const month = monthPrime + (monthPrime < 10 ? 3 : -9);
+    return { year: month <= 2 ? year + 1 : year, month, day };
+}
+function secondsFromFields(fields) {
+    const days = daysFromCivil(fields.year, fields.month, fields.day);
+    return BigInt(days) * 86400n + BigInt(fields.hour * 3600 + fields.minute * 60 + fields.second);
+}
+function utcFields(seconds) {
+    const days = Number(floorDiv(seconds, 86400n));
+    const rest = Number(seconds - BigInt(days) * 86400n);
+    const date = civilFromDays(days);
+    return {
+        ...date,
+        hour: Math.floor(rest / 3600),
+        minute: Math.floor((rest % 3600) / 60),
+        second: rest % 60,
+    };
+}
+function floorDiv(value, by) {
+    const quotient = value / by;
+    return value % by < 0n ? quotient - 1n : quotient;
+}
+// --- zones -----------------------------------------------------------------
+const FIXED_OFFSET = /^([+-]?)(\d{2}):(\d{2})$/;
+/**
+ * The civil fields of an instant in a zone. A zone is an IANA name, resolved by the
+ * host's own tz database, or a fixed `±HH:MM` offset, which is arithmetic; an unsigned
+ * offset is read as ahead of UTC, as cel-spec's own rows read it.
+ */
+export function zonedFields(value, zone, range) {
+    if (zone === undefined || zone === "UTC")
+        return utcFields(value.seconds);
+    const fixed = FIXED_OFFSET.exec(zone);
+    if (fixed) {
+        const [, sign, hours, minutes] = fixed;
+        if (Number(hours) > 23 || Number(minutes) > 59) {
+            return celError("invalid_argument", `${JSON.stringify(zone)} is not a time zone`, range);
+        }
+        const offset = BigInt(Number(hours) * 3600 + Number(minutes) * 60);
+        return utcFields(value.seconds + (sign === "-" ? -offset : offset));
+    }
+    return namedZoneFields(value, zone, range);
+}
+/** The host's answer for an IANA zone. Its rules are the host's data, not this engine's. */
+function namedZoneFields(value, zone, range) {
+    let parts;
+    try {
+        const format = new Intl.DateTimeFormat("en-US", {
+            timeZone: zone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hourCycle: "h23",
+            era: "short",
+        });
+        parts = format.formatToParts(new Date(Number(value.seconds) * 1000));
+    }
+    catch {
+        return celError("invalid_argument", `${JSON.stringify(zone)} is not a time zone`, range);
+    }
+    const read = (type) => Number(parts.find((part) => part.type === type)?.value ?? Number.NaN);
+    const era = parts.find((part) => part.type === "era")?.value;
+    const year = read("year");
+    return {
+        year: era === "BC" ? 1 - year : year,
+        month: read("month"),
+        day: read("day"),
+        hour: read("hour"),
+        minute: read("minute"),
+        second: read("second"),
+    };
+}
+/**
+ * A field of an instant. `getMonth`, `getDayOfMonth` and `getDayOfYear` are **zero
+ * based** and `getDate` is one based, which is cel-spec's own split; `getDayOfWeek`
+ * counts from Sunday.
+ */
+export function timestampField(value, field, zone, range) {
+    if (field === "getMilliseconds")
+        return BigInt(Math.floor(value.nanos / 1_000_000));
+    const civil = zonedFields(value, zone, range);
+    if (isCelError(civil))
+        return civil;
+    switch (field) {
+        case "getFullYear":
+            return BigInt(civil.year);
+        case "getMonth":
+            return BigInt(civil.month - 1);
+        case "getDayOfMonth":
+            return BigInt(civil.day - 1);
+        case "getDate":
+            return BigInt(civil.day);
+        case "getDayOfYear":
+            return BigInt(daysFromCivil(civil.year, civil.month, civil.day) - daysFromCivil(civil.year, 1, 1));
+        case "getDayOfWeek": {
+            const days = daysFromCivil(civil.year, civil.month, civil.day);
+            return BigInt(((days % 7) + 11) % 7);
+        }
+        case "getHours":
+            return BigInt(civil.hour);
+        case "getMinutes":
+            return BigInt(civil.minute);
+        case "getSeconds":
+            return BigInt(civil.second);
+    }
+}

package/dist/tree-equality.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether two trees are the same expression.
+ *
+ * Ranges are **not** compared: two trees of the same expression written with
+ * different spacing or parentheses hold different offsets, and the round-trip
+ * contract (`serializer.ts`) is exactly that serializing and re-parsing gives back
+ * the same expression — not the same text.
+ *
+ * Numbers compare by identity rather than by `==`, so `-0.0` is not `0.0` and a
+ * `NaN` equals itself: both are distinct literals a round-trip must preserve.
+ */
+import type { CelNode } from "./syntax-tree.js";
+/** Whether the two trees are the same expression, their ranges aside. */
+export declare function treesEqual(left: CelNode, right: CelNode): boolean;
+//# sourceMappingURL=tree-equality.d.ts.map

package/dist/tree-equality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-equality.d.ts","sourceRoot":"","sources":["../src/tree-equality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAc,OAAO,EAAE,MAAM,kBAAkB,CAAC;AA0B5D,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA0FjE"}

package/dist/tree-equality.js

@@ -0,0 +1,105 @@
+/**
+ * Whether two trees are the same expression.
+ *
+ * Ranges are **not** compared: two trees of the same expression written with
+ * different spacing or parentheses hold different offsets, and the round-trip
+ * contract (`serializer.ts`) is exactly that serializing and re-parsing gives back
+ * the same expression — not the same text.
+ *
+ * Numbers compare by identity rather than by `==`, so `-0.0` is not `0.0` and a
+ * `NaN` equals itself: both are distinct literals a round-trip must preserve.
+ */
+function literalsEqual(left, right) {
+    if (left.type !== right.type)
+        return false;
+    switch (left.type) {
+        case "null":
+            return true;
+        case "int":
+        case "uint":
+            return left.value === right.value;
+        case "double":
+            return Object.is(left.value, right.value);
+        case "bool":
+        case "string":
+            return left.value === right.value;
+        case "bytes": {
+            const other = right.value;
+            return left.value.length === other.length && left.value.every((byte, at) => byte === other[at]);
+        }
+    }
+}
+function listsEqual(left, right) {
+    return left.length === right.length && left.every((node, at) => treesEqual(node, right[at]));
+}
+/** Whether the two trees are the same expression, their ranges aside. */
+export function treesEqual(left, right) {
+    if (left.kind !== right.kind)
+        return false;
+    switch (left.kind) {
+        case "literal":
+            return literalsEqual(left.literal, right.literal);
+        case "ident": {
+            const other = right;
+            // Absolute changes what the name resolves against, so it is part of the expression;
+            // whether a member was written between backticks is not.
+            return left.name === other.name && left.absolute === other.absolute;
+        }
+        case "unparsed":
+            return true;
+        case "list": {
+            const other = right.elements;
+            return (left.elements.length === other.length &&
+                left.elements.every((element, at) => element.optional === other[at].optional && treesEqual(element.value, other[at].value)));
+        }
+        case "map": {
+            const other = right.entries;
+            return (left.entries.length === other.length &&
+                left.entries.every((entry, at) => entry.optional === other[at].optional &&
+                    treesEqual(entry.key, other[at].key) &&
+                    treesEqual(entry.value, other[at].value)));
+        }
+        case "select": {
+            const other = right;
+            return (left.field === other.field &&
+                left.optional === other.optional &&
+                treesEqual(left.operand, other.operand));
+        }
+        case "index": {
+            const other = right;
+            return (left.optional === other.optional &&
+                treesEqual(left.operand, other.operand) &&
+                treesEqual(left.index, other.index));
+        }
+        case "call": {
+            const other = right;
+            return left.name === other.name && listsEqual(left.args, other.args);
+        }
+        case "receiverCall": {
+            const other = right;
+            return (left.name === other.name &&
+                treesEqual(left.receiver, other.receiver) &&
+                listsEqual(left.args, other.args));
+        }
+        case "qcall": {
+            const other = right;
+            return (left.namespace === other.namespace && left.name === other.name && listsEqual(left.args, other.args));
+        }
+        case "unary": {
+            const other = right;
+            return left.operator === other.operator && treesEqual(left.operand, other.operand);
+        }
+        case "binary": {
+            const other = right;
+            return (left.operator === other.operator &&
+                treesEqual(left.left, other.left) &&
+                treesEqual(left.right, other.right));
+        }
+        case "conditional": {
+            const other = right;
+            return (treesEqual(left.condition, other.condition) &&
+                treesEqual(left.whenTrue, other.whenTrue) &&
+                treesEqual(left.whenFalse, other.whenFalse));
+        }
+    }
+}

package/dist/type-expression.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Types as text: `list<int>`, `map<string, int>`, `optional<T>`, `Money<string>`.
+ *
+ * A host declares a variable's or a signature's type as a string, and the signature
+ * data a port reads is text, so one grammar reads both. It is deliberately the same
+ * spelling `formatType` writes, so a type that round-trips through text is the type
+ * it started as — which is what lets the definition listing and the signature data
+ * be compared without a second parser.
+ *
+ * A bare capital letter is a type **parameter**, which is how a signature says "the
+ * same type here and there". A name the host registered as a nominal type resolves
+ * to it; any other name is refused rather than guessed — as a
+ * {@link CelUnknownTypeNameError}, which a caller holding the name's source may turn
+ * into a verdict — because a misspelled type in a signature would otherwise register a
+ * function nothing can call.
+ */
+import type { CelType } from "./cel-type.js";
+export declare class CelTypeExpressionError extends Error {
+    constructor(message: string);
+}
+/**
+ * A well-formed type expression naming a type nothing is registered under.
+ *
+ * It is **not** a `CelTypeExpressionError`, and the split is the whole point: that error
+ * is about text this grammar cannot read, while this one is about a name the HOST and its
+ * own registry disagree about. A caller that holds where the name was written can turn it
+ * into a ranged verdict instead of a crash — which is what a namespace declaration built
+ * out of a host's data does — and a caller that cannot still lets it fly.
+ */
+export declare class CelUnknownTypeNameError extends Error {
+    /** The name nothing is registered under. */
+    readonly typeName: string;
+    constructor(typeName: string);
+}
+/** What a name that is neither a primitive nor a parameter resolves to. */
+export type NominalResolver = (name: string, args: readonly CelType[]) => CelType | undefined;
+/**
+ * Reads one type expression. `resolveNominal` is consulted for every name the
+ * language itself does not define.
+ */
+export declare function parseTypeExpression(text: string, resolveNominal?: NominalResolver): CelType;
+//# sourceMappingURL=type-expression.d.ts.map

package/dist/type-expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-expression.d.ts","sourceRoot":"","sources":["../src/type-expression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AAoB5D,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAmBD,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,GAAG,SAAS,CAAC;AAE9F;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,eAAe,GAAG,OAAO,CAK3F"}