@telorun/cel 0.0.0-stage → 0.108.0

package/src/type-expression.ts

@@ -0,0 +1,182 @@
+/**
+ * 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, PrimitiveName } from "./cel-type.js";
+import {
+  BOOL,
+  BYTES,
+  DOUBLE,
+  DYN,
+  DURATION,
+  INT,
+  listOf,
+  mapOf,
+  NULL,
+  optionalOf,
+  parameterOf,
+  STRING,
+  TIMESTAMP,
+  TYPE,
+  UINT,
+  WELL_KNOWN_TYPE_NAMES,
+} from "./cel-type.js";
+
+export class CelTypeExpressionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CelTypeExpressionError";
+  }
+}
+
+/**
+ * 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 class CelUnknownTypeNameError extends Error {
+  /** The name nothing is registered under. */
+  readonly typeName: string;
+
+  constructor(typeName: string) {
+    super(`no type is registered under the name ${JSON.stringify(typeName)}`);
+    this.name = "CelUnknownTypeNameError";
+    this.typeName = typeName;
+  }
+}
+
+const PRIMITIVES: Readonly<Record<string, CelType>> = {
+  dyn: DYN,
+  int: INT,
+  uint: UINT,
+  double: DOUBLE,
+  bool: BOOL,
+  string: STRING,
+  bytes: BYTES,
+  null: NULL,
+  null_type: NULL,
+  type: TYPE,
+  timestamp: TIMESTAMP,
+  duration: DURATION,
+};
+
+const PARAMETER = /^[A-Z]$/;
+
+/** 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 function parseTypeExpression(text: string, resolveNominal?: NominalResolver): CelType {
+  const reader = new TypeReader(text, resolveNominal);
+  const type = reader.read();
+  reader.expectEnd();
+  return type;
+}
+
+class TypeReader {
+  private at = 0;
+
+  constructor(
+    private readonly text: string,
+    private readonly resolveNominal?: NominalResolver,
+  ) {}
+
+  read(): CelType {
+    const name = this.readName();
+    const args = this.readArguments();
+    return this.resolve(name, args);
+  }
+
+  expectEnd(): void {
+    this.skipSpace();
+    if (this.at !== this.text.length) {
+      throw new CelTypeExpressionError(`${JSON.stringify(this.text)} is not one type expression`);
+    }
+  }
+
+  /** Reads the next type of a list, stopping at `,` or `>`. */
+  readArgument(): CelType {
+    return this.read();
+  }
+
+  private skipSpace(): void {
+    while (this.text[this.at] === " ") this.at += 1;
+  }
+
+  private readName(): string {
+    this.skipSpace();
+    const from = this.at;
+    while (this.at < this.text.length && /[A-Za-z0-9_.]/.test(this.text[this.at]!)) this.at += 1;
+    if (this.at === from) {
+      throw new CelTypeExpressionError(`${JSON.stringify(this.text)} names no type at offset ${from}`);
+    }
+    return this.text.slice(from, this.at);
+  }
+
+  private readArguments(): CelType[] {
+    this.skipSpace();
+    if (this.text[this.at] !== "<") return [];
+    this.at += 1;
+    const args: CelType[] = [this.readArgument()];
+    for (;;) {
+      this.skipSpace();
+      const next = this.text[this.at];
+      if (next === ",") {
+        this.at += 1;
+        args.push(this.readArgument());
+        continue;
+      }
+      if (next === ">") {
+        this.at += 1;
+        return args;
+      }
+      throw new CelTypeExpressionError(
+        `${JSON.stringify(this.text)} has no closing '>' for its type arguments`,
+      );
+    }
+  }
+
+  private resolve(name: string, args: readonly CelType[]): CelType {
+    const wellKnown = WELL_KNOWN_TYPE_NAMES[name];
+    if (wellKnown) return this.noArguments(name, args, PRIMITIVES[wellKnown as PrimitiveName]!);
+    if (name === "list") return args.length === 1 ? listOf(args[0]!) : listOf(DYN);
+    if (name === "map") return args.length === 2 ? mapOf(args[0]!, args[1]!) : mapOf(DYN, DYN);
+    if (name === "optional") {
+      if (args.length !== 1) {
+        throw new CelTypeExpressionError("optional takes exactly one type argument");
+      }
+      return optionalOf(args[0]!);
+    }
+    const primitive = PRIMITIVES[name];
+    if (primitive) return this.noArguments(name, args, primitive);
+    if (PARAMETER.test(name)) return this.noArguments(name, args, parameterOf(name));
+    const nominal = this.resolveNominal?.(name, args);
+    if (nominal) return nominal;
+    throw new CelUnknownTypeNameError(name);
+  }
+
+  private noArguments(name: string, args: readonly CelType[], type: CelType): CelType {
+    if (args.length > 0) throw new CelTypeExpressionError(`${name} takes no type arguments`);
+    return type;
+  }
+}

package/src/value-equality.ts

@@ -0,0 +1,201 @@
+/**
+ * Equality and ordering over values — **one comparison, serving both.**
+ *
+ * `<`, `<=`, `>`, `>=`, cross-numeric equality, `in` over a list and a list index all read
+ * the same rule, because two readers of "is this the same value" is how a container and an
+ * operator come to disagree about one expression.
+ *
+ * **Across the numeric types it CONVERTS.** The checker is strict — `1.0 == 1` is a type
+ * error — but `dyn(1.0) == 1` checks, so the runtime is reached with two numeric types in
+ * hand and cel-spec's answer is `true`. Where the double lies outside the integer type's
+ * range the sign decides; otherwise the integer becomes a double and two doubles are
+ * compared, **lossily**, so `dyn(9223372036854775807) < 9223372036854775808.0` is `false`.
+ * That is cel-spec's own rule: its corpus comments the case ("the conversion of the int to
+ * double is lossy") and names the test `not_lt_dyn_int_big_lossy_double`. `int(double)`
+ * refuses a double at or beyond **either** int64 extreme for the same reason.
+ *
+ * An exact comparison is defensible alone and indefensible as a cross-engine contract: a
+ * second engine built on a conformant library would answer the other way on a comparison
+ * that can decide an authorization or a retry bound, silently, at a level no static check
+ * reaches.
+ *
+ * **A map's key identity is NOT this comparison** and does not convert: a map is keyed by
+ * the canonical text of its key, so `{1u: 1.0}[?1.0]` reads the entry and `[?3.1]` names
+ * none.
+ *
+ * Equality across unrelated types is `false`, not an error — two values of different
+ * types are not equal, and asking is not a mistake. Ordering across unrelated types has
+ * no answer, so the caller reports no overload.
+ */
+
+import { durationNanos } from "./duration-value.js";
+import { mapKeyIdentity } from "./cel-map-value.js";
+import type { CelMapKey, CelValue } from "./cel-value.js";
+import {
+  celTypeNameOf,
+  isCelBytes,
+  isCelDuration,
+  isCelMap,
+  isCelOptional,
+  isCelRecord,
+  isCelTimestamp,
+  isCelTypeValue,
+  isCelUint,
+} from "./cel-value.js";
+import { timestampNanos } from "./timestamp-value.js";
+
+/** The int64 and uint64 extremes as doubles. Each reads as the nearest double there is. */
+const MIN_INT_AS_DOUBLE = -9223372036854775808;
+const MAX_INT_AS_DOUBLE = 9223372036854775807;
+const MAX_UINT_AS_DOUBLE = 18446744073709551615;
+
+/**
+ * Comparing an integer against a double, cel-spec's way: outside the integer type's range
+ * the sign decides, inside it both sides are doubles. Nothing for NaN, which orders with
+ * nothing including itself.
+ */
+function compareIntegerDouble(left: bigint, unsigned: boolean, right: number): number | undefined {
+  if (Number.isNaN(right)) return undefined;
+  if (right < (unsigned ? 0 : MIN_INT_AS_DOUBLE)) return 1;
+  if (right > (unsigned ? MAX_UINT_AS_DOUBLE : MAX_INT_AS_DOUBLE)) return -1;
+  const converted = Number(left);
+  return converted < right ? -1 : converted > right ? 1 : 0;
+}
+
+function compareNumbers(left: number, right: number): number | undefined {
+  if (Number.isNaN(left) || Number.isNaN(right)) return undefined;
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function compareBigints(left: bigint, right: bigint): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** The numeric magnitude of a value, where it has one, and which range it belongs to. */
+function numeric(
+  value: CelValue,
+): { integer: bigint; unsigned: boolean } | { double: number } | undefined {
+  if (typeof value === "bigint") return { integer: value, unsigned: false };
+  if (typeof value === "number") return { double: value };
+  if (isCelUint(value)) return { integer: value.value, unsigned: true };
+  return undefined;
+}
+
+/** Whether two numeric values compare, and how. Nothing where one is NaN. */
+function compareNumeric(left: CelValue, right: CelValue): number | undefined {
+  const a = numeric(left);
+  const b = numeric(right);
+  if (!a || !b) return undefined;
+  if ("integer" in a && "integer" in b) {
+    // An int and a uint are both exact integers, so one comparison serves both.
+    return compareBigints(a.integer, b.integer);
+  }
+  if ("integer" in a) {
+    return compareIntegerDouble(a.integer, a.unsigned, (b as { double: number }).double);
+  }
+  if ("integer" in b) {
+    const compared = compareIntegerDouble(b.integer, b.unsigned, a.double);
+    return compared === undefined ? undefined : -compared;
+  }
+  return compareNumbers(a.double, (b as { double: number }).double);
+}
+
+function compareBytes(left: Uint8Array, right: Uint8Array): number {
+  const shared = Math.min(left.length, right.length);
+  for (let at = 0; at < shared; at += 1) {
+    if (left[at]! !== right[at]!) return left[at]! < right[at]! ? -1 : 1;
+  }
+  return left.length === right.length ? 0 : left.length < right.length ? -1 : 1;
+}
+
+/**
+ * How two values order: `-1`, `0`, `1`, or nothing when they do not order at all —
+ * unrelated types, or a NaN, which orders with nothing including itself.
+ */
+export function celCompare(left: CelValue, right: CelValue): number | undefined {
+  if (numeric(left) && numeric(right)) return compareNumeric(left, right);
+  if (typeof left === "string" && typeof right === "string") {
+    return left < right ? -1 : left > right ? 1 : 0;
+  }
+  if (typeof left === "boolean" && typeof right === "boolean") {
+    return left === right ? 0 : left ? 1 : -1;
+  }
+  if (isCelBytes(left) && isCelBytes(right)) return compareBytes(left, right);
+  if (isCelTimestamp(left) && isCelTimestamp(right)) {
+    return compareBigints(timestampNanos(left), timestampNanos(right));
+  }
+  if (isCelDuration(left) && isCelDuration(right)) {
+    return compareBigints(durationNanos(left), durationNanos(right));
+  }
+  return undefined;
+}
+
+/** CEL equality: by value, across the numeric types, and `false` across unrelated ones. */
+export function celEqual(left: CelValue, right: CelValue): boolean {
+  // One identical primitive is equal to itself, and the two edges agree: `-0 === 0` and CEL
+  // says they are equal, `NaN !== NaN` and CEL says they are not — so the slow path below
+  // answers NaN correctly after this check declines it.
+  if (left === right && typeof left !== "object") return true;
+  if (numeric(left) && numeric(right)) return compareNumeric(left, right) === 0;
+  if (left === null || right === null) return left === right;
+  const leftType = celTypeNameOf(left);
+  if (leftType !== celTypeNameOf(right)) return false;
+  switch (leftType) {
+    case "bool":
+    case "string":
+      return left === right;
+    case "bytes":
+      return compareBytes(left as Uint8Array, right as Uint8Array) === 0;
+    case "google.protobuf.Timestamp":
+      return timestampNanos(left as never) === timestampNanos(right as never);
+    case "google.protobuf.Duration":
+      return durationNanos(left as never) === durationNanos(right as never);
+    case "type":
+      return isCelTypeValue(left) && isCelTypeValue(right) && left.name === right.name;
+    case "list":
+      return equalLists(left as readonly CelValue[], right as readonly CelValue[]);
+    case "map":
+      return equalMaps(left, right);
+    case "optional":
+      return equalOptionals(left, right);
+    default:
+      // A host's own named type: equal when the host's operator says so, which it
+      // registers itself. With none registered, identity is all this engine knows.
+      return left === right;
+  }
+}
+
+function equalLists(left: readonly CelValue[], right: readonly CelValue[]): boolean {
+  if (left.length !== right.length) return false;
+  return left.every((value, at) => celEqual(value, right[at]!));
+}
+
+/** Every key of a map, as the pairs equality walks. */
+function mapPairs(value: CelValue): Map<CelMapKey, CelValue> | undefined {
+  if (isCelMap(value)) {
+    return new Map([...value.entries].map(([identity, entry]) => [identity, entry.value]));
+  }
+  if (isCelRecord(value)) {
+    const pairs = new Map<CelMapKey, CelValue>();
+    for (const key of Object.keys(value)) pairs.set(mapKeyIdentity(key)!, value[key] as CelValue);
+    return pairs;
+  }
+  return undefined;
+}
+
+function equalMaps(left: CelValue, right: CelValue): boolean {
+  const a = mapPairs(left);
+  const b = mapPairs(right);
+  if (!a || !b || a.size !== b.size) return false;
+  for (const [identity, value] of a) {
+    if (!b.has(identity)) return false;
+    if (!celEqual(value, b.get(identity)!)) return false;
+  }
+  return true;
+}
+
+function equalOptionals(left: CelValue, right: CelValue): boolean {
+  if (!isCelOptional(left) || !isCelOptional(right)) return false;
+  if (left.present !== right.present) return false;
+  return !left.present || celEqual(left.held as CelValue, right.held as CelValue);
+}

package/src/value-text.ts

@@ -0,0 +1,45 @@
+/**
+ * Text: how a value is written as a string, and how text becomes bytes.
+ *
+ * `string()` is the one conversion a consumer renders a value through — an interpolated
+ * hole is defined as the CEL join of `string(<hole>)` — so each form here is the value's
+ * single written form, the same one the plain encoding uses: RFC 3339 for an instant,
+ * seconds with an `s` for a duration, UTF-8 text for bytes.
+ */
+
+import { celError, type CelError } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** The UTF-8 bytes of text. */
+export function textToBytes(text: string): Uint8Array {
+  return encoder.encode(text);
+}
+
+/**
+ * The text bytes hold. Bytes that are not UTF-8 are a conversion error rather than text
+ * with a replacement character in it: a replacement character is a value the author
+ * never wrote, and it would read back as different bytes.
+ */
+export function bytesToText(bytes: Uint8Array, range?: SourceRange): string | CelError {
+  try {
+    return decoder.decode(bytes);
+  } catch {
+    return celError("invalid_conversion", "the bytes are not UTF-8 text", range);
+  }
+}
+
+/**
+ * A double as text. The shortest digits that read back as the same double, which is the
+ * host's own shortest-round-trip form; the non-finite doubles are named as cel-spec
+ * writes them.
+ */
+export function doubleText(value: number): string {
+  if (Number.isNaN(value)) return "NaN";
+  if (value === Number.POSITIVE_INFINITY) return "+Inf";
+  if (value === Number.NEGATIVE_INFINITY) return "-Inf";
+  if (value === 0 && Object.is(value, -0)) return "-0";
+  return String(value);
+}

package/src/zoned-calendar.ts

@@ -0,0 +1,178 @@
+/**
+ * The calendar in a time zone: an instant's wall-clock fields, and the instant a wall
+ * clock names.
+ *
+ * An instant is only a date once a zone is chosen, so every calendar function of the
+ * function catalog reads its fields through here. The zone's RULES are the host's data
+ * (`Intl.DateTimeFormat`, ECMA-402, present in a browser as in Node), never this
+ * engine's: what is written here is only how those rules are applied, which is the half
+ * a second engine has to reproduce.
+ *
+ * It is separate from `timestamp-value.ts` on purpose. That file is the language's own
+ * zone reading — cel-spec's getters, which also accept a fixed `HH:MM` offset and word
+ * their refusal as the language does. This one is the catalog's: it accepts an IANA name
+ * alone, it is millisecond-granular because the functions built on it render
+ * milliseconds, and it answers a gap or a repeated wall clock the way a calendar
+ * library does. Folding the two would make one of the two behaviours wrong.
+ */
+
+/** A wall clock, to the second: what a zone makes of an instant. */
+export interface CivilTime {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/**
+ * Whether the host knows the zone. The catalog's refusal is worded by its caller, so
+ * this answers only yes or no — left to `Intl` the failure is a `RangeError` naming
+ * neither the function nor what was wrong with the argument.
+ */
+export function knownTimeZone(zone: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const FIELD_OPTIONS: Intl.DateTimeFormatOptions = {
+  hourCycle: "h23",
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+};
+
+function zoneParts(
+  instant: number,
+  zone: string,
+  options: Intl.DateTimeFormatOptions,
+): Record<string, string> {
+  const parts: Record<string, string> = {};
+  for (const part of new Intl.DateTimeFormat("en-US", { timeZone: zone, ...options }).formatToParts(
+    new Date(instant),
+  )) {
+    parts[part.type] = part.value;
+  }
+  return parts;
+}
+
+/** The wall clock an instant reads as in a zone. */
+export function civilTimeIn(instant: number, zone: string): CivilTime {
+  const parts = zoneParts(instant, zone, FIELD_OPTIONS);
+  return {
+    year: +parts.year!,
+    month: +parts.month!,
+    day: +parts.day!,
+    hour: +parts.hour!,
+    minute: +parts.minute!,
+    second: +parts.second!,
+  };
+}
+
+/** The zone's offset at an instant, in milliseconds: its wall clock read as UTC, minus it. */
+function offsetAt(instant: number, zone: string): number {
+  const fields = civilTimeIn(instant, zone);
+  return (
+    Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour, fields.minute, fields.second) -
+    instant
+  );
+}
+
+function sameWallClock(left: CivilTime, right: CivilTime): boolean {
+  return (
+    left.year === right.year &&
+    left.month === right.month &&
+    left.day === right.day &&
+    left.hour === right.hour &&
+    left.minute === right.minute &&
+    left.second === right.second
+  );
+}
+
+/**
+ * The instant whose wall clock in `zone` is these fields.
+ *
+ * The offset depends on the instant being solved for, so this takes the offset at the
+ * UTC reading, corrects, and then **checks** by reading the result back. That check is
+ * the whole point: a plain fixpoint settles on an instant whose wall clock is not the one
+ * asked for whenever the requested time does not exist, and it settles BACKWARDS — which
+ * silently moves the calendar day, the one thing `addMonths` and `startOfMonth` exist to
+ * control. Chile jumps 00:00 to 01:00 on 2026-09-06 and Cuba on 2026-03-08, so "the 6th
+ * at midnight" there is not a time; a fixpoint answered "the 5th at 23:00".
+ *
+ * Resolution follows Java's `ZonedDateTime` and Temporal's `compatible`: a wall clock
+ * that exists twice (a fall-back) takes the EARLIER instant, and one that does not exist
+ * (a spring-forward gap) shifts FORWARD out of the gap, which keeps the requested day.
+ */
+export function instantOfCivilTime(fields: CivilTime, zone: string): number {
+  const asUtc = Date.UTC(
+    fields.year,
+    fields.month - 1,
+    fields.day,
+    fields.hour,
+    fields.minute,
+    fields.second,
+  );
+  const offsetA = offsetAt(asUtc, zone);
+  const candidateA = asUtc - offsetA;
+  const offsetB = offsetAt(candidateA, zone);
+  if (offsetA === offsetB) return candidateA;
+
+  const candidateB = asUtc - offsetB;
+  const aHolds = sameWallClock(civilTimeIn(candidateA, zone), fields);
+  const bHolds = sameWallClock(civilTimeIn(candidateB, zone), fields);
+  if (aHolds && bHolds) return Math.min(candidateA, candidateB);
+  if (aHolds) return candidateA;
+  if (bHolds) return candidateB;
+  return Math.max(candidateA, candidateB);
+}
+
+/** `Date.UTC` maps years 0-99 to 1900-1999, so the year is set explicitly. */
+export function daysInMonth(year: number, month: number): number {
+  const date = new Date(Date.UTC(2000, month, 0));
+  date.setUTCFullYear(year, month, 0);
+  return date.getUTCDate();
+}
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+/** The calendar date (`YYYY-MM-DD`) an instant reads as in a zone. */
+export function dateTextIn(instant: number, zone: string): string {
+  if (zone === "UTC" || zone === "Z") return new Date(instant).toISOString().slice(0, 10);
+  const parts = zoneParts(instant, zone, { year: "numeric", month: "2-digit", day: "2-digit" });
+  return `${parts.year}-${parts.month}-${parts.day}`;
+}
+
+/**
+ * An instant as ISO-8601 in a zone, with milliseconds: UTC as `…Z`, else the zone's own
+ * offset (`2026-06-06T18:30:00.000-05:00`). The offset is derived arithmetically from
+ * standard `Intl` fields, so nothing here needs a newer ECMA-402 surface.
+ */
+export function isoTextIn(instant: number, zone: string): string {
+  if (zone === "UTC" || zone === "Z") return new Date(instant).toISOString();
+  const fields = civilTimeIn(instant, zone);
+  // Sub-second is zone-independent; read it off the instant directly.
+  const milliseconds = pad(((instant % 1000) + 1000) % 1000, 3);
+  const minutes = Math.round(
+    (Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour, fields.minute, fields.second) -
+      instant) /
+      60000,
+  );
+  const offset =
+    minutes === 0
+      ? "Z"
+      : `${minutes > 0 ? "+" : "-"}${pad(Math.floor(Math.abs(minutes) / 60), 2)}:${pad(Math.abs(minutes) % 60, 2)}`;
+  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}.${milliseconds}${offset}`;
+}