@telorun/cel 0.0.0-stage → 0.108.0

package/src/comprehension-runtime.ts

@@ -0,0 +1,157 @@
+/**
+ * What a comprehension macro **does**, as a function of its range and its body.
+ *
+ * The macros are lowered by each backend — there is no comprehension node in the tree,
+ * because expanding one at read time would make the source unwritable from the tree —
+ * but what the lowering *means* lives here, once. The closure backend passes a closure
+ * as the body and the emitter will pass an emitted function, and both get the same
+ * answers, including the error rules.
+ *
+ * **An error does not win over a decided answer**, with the one exception named below: `all`
+ * is `false` as soon as one element is false even if another errors, and `exists` is `true` as
+ * soon as one is true. That is the same rule `&&` and `||` follow, and it is what makes a
+ * comprehension over partly-unreadable data usable at all.
+ *
+ * **An element entering a body is a door a host value comes through**, and it is checked for a
+ * thenable here — in the one place a comprehension's meaning lives, so both backends inherit it
+ * rather than each remembering to. It is not the leak it looks like: `xs.all(e, true)` over a
+ * host list holding a promise used to answer **`true`**, having decided something about a value
+ * it never touched, which is the worse half of the failure class. The cost is one `typeof` per
+ * element, the same check the member read already makes, on a loop that already calls a closure
+ * per element.
+ *
+ * **That refusal is TERMINAL, and it is the one error here that does not short-circuit.** It is
+ * checked where the element is BOUND, before the body runs, and it ends the comprehension
+ * whatever a later element would have decided — so `xs.all(e, false)` and `xs.exists(e, true)`
+ * refuse rather than answering `false` and `true` off the one element that is readable. The
+ * distinction is what the error is ABOUT: `no_such_key` is a fact about one datum, so a decided
+ * answer may legitimately outrank it, while a value that must be awaited says the host handed
+ * this engine something it cannot evaluate at all. Carrying that past a convenient element makes
+ * the answer depend on how many elements happen to be readable and in what order — and the rule
+ * is subtle enough that two readers in a row took the discardable refusal for a leak instead.
+ */
+
+import type { CelValue } from "./cel-value.js";
+import { asyncValueRefused, celError, isCelError, type CelError } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+/** The body of a comprehension: the value its expression answers for one element. */
+export type ComprehensionBody = (element: CelValue) => CelValue;
+
+function notBool(value: CelValue, range?: SourceRange): CelError {
+  return celError(
+    "no_matching_overload",
+    `a comprehension's test must answer a bool, and it answered ${typeof value}`,
+    range,
+  );
+}
+
+/**
+ * Whether an element entering a body is one that must be awaited.
+ *
+ * The `typeof` is inlined here rather than left to the call, because this runs once per element
+ * on the engine's hottest loop and only an OBJECT can be a thenable. Measured on a
+ * 100k-element `map` over integers — a body that does almost nothing, so the check is as
+ * visible as it ever gets: calling unconditionally cost about 4 ms, and with the `typeof`
+ * guarding the call the difference sits at this machine's noise floor.
+ */
+function awaited(element: CelValue, range?: SourceRange): CelError | undefined {
+  if (typeof element !== "object" || element === null) return undefined;
+  return asyncValueRefused(element, range);
+}
+
+/** A predicate's answer for one element: `true`, `false`, or the error it is. */
+function test(body: ComprehensionBody, element: CelValue, range?: SourceRange): boolean | CelError {
+  const answered = body(element);
+  if (isCelError(answered)) return answered;
+  if (typeof answered !== "boolean") return notBool(answered, range);
+  return answered;
+}
+
+export function celAll(
+  elements: readonly CelValue[],
+  body: ComprehensionBody,
+  range?: SourceRange,
+): CelValue {
+  let failure: CelError | undefined;
+  for (const element of elements) {
+    const refused = awaited(element, range);
+    if (refused) return refused;
+    const answered = test(body, element, range);
+    if (answered === false) return false;
+    if (answered !== true && !failure) failure = answered;
+  }
+  return failure ?? true;
+}
+
+export function celExists(
+  elements: readonly CelValue[],
+  body: ComprehensionBody,
+  range?: SourceRange,
+): CelValue {
+  let failure: CelError | undefined;
+  for (const element of elements) {
+    const refused = awaited(element, range);
+    if (refused) return refused;
+    const answered = test(body, element, range);
+    if (answered === true) return true;
+    if (answered !== false && !failure) failure = answered;
+  }
+  return failure ?? false;
+}
+
+/** Exactly one element satisfies the test. An error anywhere leaves no count to trust. */
+export function celExistsOne(
+  elements: readonly CelValue[],
+  body: ComprehensionBody,
+  range?: SourceRange,
+): CelValue {
+  let found = 0;
+  for (const element of elements) {
+    const refused = awaited(element, range);
+    if (refused) return refused;
+    const answered = test(body, element, range);
+    if (isCelError(answered)) return answered;
+    if (answered) found += 1;
+  }
+  return found === 1;
+}
+
+export function celFilter(
+  elements: readonly CelValue[],
+  body: ComprehensionBody,
+  range?: SourceRange,
+): CelValue {
+  const kept: CelValue[] = [];
+  for (const element of elements) {
+    const refused = awaited(element, range);
+    if (refused) return refused;
+    const answered = test(body, element, range);
+    if (isCelError(answered)) return answered;
+    if (answered) kept.push(element);
+  }
+  return kept;
+}
+
+/** `map` in both arities: with a filter, an element the filter drops is not transformed. */
+export function celMapComprehension(
+  elements: readonly CelValue[],
+  transform: ComprehensionBody,
+  filter?: ComprehensionBody,
+  range?: SourceRange,
+): CelValue {
+  const out: CelValue[] = [];
+  for (const element of elements) {
+    const refused = awaited(element, range);
+    if (refused) return refused;
+    if (filter) {
+      const answered = test(filter, element, range);
+      if (isCelError(answered)) return answered;
+      if (!answered) continue;
+    }
+    const value = transform(element);
+    if (isCelError(value)) return value;
+    out.push(value);
+  }
+  return out;
+}

package/src/declared-chain.ts

@@ -0,0 +1,45 @@
+/**
+ * Splitting a dotted chain over the names a host DECLARED — once, for both halves.
+ *
+ * A host may declare `a.b.c`, or `a.b` holding a map, or both. `a.b.c` then reads the
+ * variable of that name where it is declared and the map's entry where only `a.b` is, so the
+ * host's own naming decides rather than the shape of the expression: the **longest declared
+ * prefix wins**.
+ *
+ * The checker and the backend ask the same question of the same declarations, so they ask it
+ * here. Two readers would be two answers to "which name is this chain", and the pair that
+ * disagrees is the worst kind: `telo check` types one name while evaluation reads another, and
+ * nothing says so. Splitting at compile time also means a declared chain costs **one**
+ * activation read at evaluation rather than a search over its prefixes.
+ *
+ * A chain **no prefix of which** is declared — the root included — is left alone: there is
+ * nothing to split it on, and the checker has no opinion about it either. The backend then
+ * searches the activation at evaluation, which is what every conformance row binding a dotted
+ * key relies on. Where any prefix IS declared the search never runs, so a key the host did not
+ * declare can never win over a name it did.
+ */
+
+/** Where a chain splits: the declared name, and the members read off its value. */
+export interface DeclaredChain {
+  readonly name: string;
+  readonly rest: readonly string[];
+}
+
+/**
+ * The longest declared prefix of a chain, or nothing when no declaration covers one.
+ *
+ * **The root counts as a prefix**, and leaving it out was the disagreement this function
+ * exists to prevent: with a chain whose root alone is declared treated as undeclared, the
+ * backend fell into the activation prefix search, and an activation holding both `a` and the
+ * key `"a.b"` answered the undeclared key where the checker had typed the declared name.
+ */
+export function splitDeclaredChain(
+  segments: readonly string[],
+  declared: (name: string) => boolean,
+): DeclaredChain | undefined {
+  for (let length = segments.length; length >= 1; length -= 1) {
+    const name = segments.slice(0, length).join(".");
+    if (declared(name)) return { name, rest: segments.slice(length) };
+  }
+  return undefined;
+}

package/src/duration-value.ts

@@ -0,0 +1,160 @@
+/**
+ * Durations: reading one, writing one, and the fields of one.
+ *
+ * **CEL's duration is the signed 64-bit range of its total NANOSECONDS** —
+ * `-9223372036.854775808s … 9223372036.854775807s`, roughly ±292 years. That is cel-spec's
+ * own rule, stated under *Overflow* in its language definition ("Duration values are
+ * limited to a single int64 value, or roughly +-290 years"), and all six of the vectors'
+ * `timestamps/duration_range` rows read it: each uses an operand of 200,000,000,000s or
+ * 320,000,000,000s and each expects `duration out of range`.
+ *
+ * **It is a subrange of the typed frame's, deliberately.** The frame carries protobuf's
+ * `google.protobuf.Duration` range — ±315,576,000,000s, ±10,000 years — because a duration
+ * arriving from a transport, a journal or a controller must always be representable, and
+ * narrowing the frame to CEL's range would make such a value unwritable. So CEL ⊂ frame:
+ * `duration('200000000000s')` is a value the frame carries and CEL cannot construct, which
+ * is the correct answer rather than a cost. Nothing about the frame changes here.
+ *
+ * The range is an invariant, not a storage format: a duration is still seconds and
+ * nanoseconds of the same sign, with `|nanos| < 1e9`, and nanosecond-precise. A computation
+ * that leaves the range is an error, never a value outside it.
+ *
+ * It is written as seconds with an `s` suffix (`1000000s`, `-1.5s`), which is cel-spec's
+ * own spelling, and the one plain encoding a duration has wherever it is written down.
+ */
+
+import { celError, CEL_VALUE_TYPE, isCelError, type CelDuration, type CelError } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+/** The widest and narrowest total a duration holds, in nanoseconds: int64. */
+export const MAX_DURATION_NANOS = 9_223_372_036_854_775_807n;
+export const MIN_DURATION_NANOS = -9_223_372_036_854_775_808n;
+
+const NANOS_PER_SECOND = 1_000_000_000n;
+
+/** A duration from a total in nanoseconds, or the range error. */
+export function celDurationFromNanos(total: bigint, range?: SourceRange): CelDuration | CelError {
+  if (total > MAX_DURATION_NANOS || total < MIN_DURATION_NANOS) {
+    return celError("invalid_conversion", "duration out of range", range);
+  }
+  return {
+    [CEL_VALUE_TYPE]: "google.protobuf.Duration",
+    seconds: total / NANOS_PER_SECOND,
+    nanos: Number(total % NANOS_PER_SECOND),
+  };
+}
+
+/**
+ * The error a duration **this engine did not build** is outside CEL's range: one from a
+ * host, which the frame's wider range admits. Checked where such a duration is used, not
+ * where it arrives, so a value merely passing through is not judged.
+ */
+export function durationOutOfRange(value: CelDuration, range?: SourceRange): CelError | undefined {
+  const total = durationNanos(value);
+  if (total <= MAX_DURATION_NANOS && total >= MIN_DURATION_NANOS) return undefined;
+  return celError("invalid_conversion", "duration out of range", range);
+}
+
+/** The duration's total nanoseconds — what arithmetic and ordering compare. */
+export function durationNanos(value: CelDuration): bigint {
+  return value.seconds * NANOS_PER_SECOND + BigInt(value.nanos);
+}
+
+const UNIT_NANOS: Readonly<Record<string, bigint>> = {
+  ns: 1n,
+  us: 1_000n,
+  "µs": 1_000n,
+  "μs": 1_000n,
+  ms: 1_000_000n,
+  s: 1_000_000_000n,
+  m: 60_000_000_000n,
+  h: 3_600_000_000_000n,
+};
+
+const PART = /([0-9]*)(?:\.([0-9]*))?(ns|us|µs|μs|ms|s|m|h)/g;
+
+/**
+ * A duration from CEL's own text: a sign, then one or more number-and-unit parts over
+ * `ns`, `us`, `ms`, `s`, `m` and `h` (`1h30m`, `1.5s`, `-10m`).
+ */
+export function parseDuration(text: string, range?: SourceRange): CelDuration | CelError {
+  const total = durationNanosFromText(text, range);
+  return isCelError(total) ? total : celDurationFromNanos(total, range);
+}
+
+/**
+ * The same text as a TOTAL OF NANOSECONDS, with no range applied.
+ *
+ * The grammar and the range are separate questions, and a consumer outside CEL has the same
+ * grammar with a different range: protobuf's `google.protobuf.Duration` reaches ±10,000
+ * years, which **cannot be held in an int64 of nanoseconds at all**, so a reader that must
+ * carry one (a journal entry, a value off a transport) cannot go through `parseDuration` and
+ * would otherwise restate this grammar. It answers an unbounded `bigint`; applying a range
+ * is the caller's, and `celDurationFromNanos` is what applies CEL's.
+ */
+export function durationNanosFromText(text: string, range?: SourceRange): bigint | CelError {
+  const refuse = () =>
+    celError("invalid_conversion", `${JSON.stringify(text)} is not a duration`, range);
+  let body = text;
+  let negative = false;
+  if (body.startsWith("+") || body.startsWith("-")) {
+    negative = body.startsWith("-");
+    body = body.slice(1);
+  }
+  if (body === "0") return 0n;
+  if (body === "") return refuse();
+  PART.lastIndex = 0;
+  let total = 0n;
+  let at = 0;
+  for (let found = PART.exec(body); found; found = PART.exec(body)) {
+    if (found.index !== at) return refuse();
+    const [whole, digits, fraction, unit] = found;
+    if (!digits && !fraction) return refuse();
+    const scale = UNIT_NANOS[unit!]!;
+    total += BigInt(digits || "0") * scale;
+    if (fraction) {
+      const padded = `${fraction}000000000`.slice(0, 9);
+      total += (BigInt(padded) * scale) / NANOS_PER_SECOND;
+    }
+    at += whole.length;
+  }
+  if (at !== body.length) return refuse();
+  return negative ? -total : total;
+}
+
+/** Seconds with an `s` suffix, the fraction trimmed to what it carries. */
+export function formatDuration(value: CelDuration): string {
+  const total = durationNanos(value);
+  const negative = total < 0n;
+  const magnitude = negative ? -total : total;
+  const seconds = magnitude / NANOS_PER_SECOND;
+  const nanos = magnitude % NANOS_PER_SECOND;
+  const fraction = nanos === 0n ? "" : `.${String(nanos).padStart(9, "0").replace(/0+$/, "")}`;
+  return `${negative ? "-" : ""}${seconds}${fraction}s`;
+}
+
+/** Which field of a duration a getter answers. */
+export type DurationField = "getHours" | "getMinutes" | "getSeconds" | "getMilliseconds";
+
+/**
+ * A field of a duration. `getHours`, `getMinutes` and `getSeconds` answer the **whole span**
+ * in that unit, truncated toward zero; `getMilliseconds` answers the **component** — the
+ * milliseconds inside the second, so `duration('123.321456789s').getMilliseconds()` is 321
+ * and not 123,321.
+ *
+ * That split is cel-spec's, and it is also the only reading under which the engine does not
+ * contradict itself: a timestamp's `getMilliseconds()` has always answered the component.
+ */
+export function durationField(value: CelDuration, field: DurationField): bigint {
+  const total = durationNanos(value);
+  switch (field) {
+    case "getHours":
+      return total / 3_600_000_000_000n;
+    case "getMinutes":
+      return total / 60_000_000_000n;
+    case "getSeconds":
+      return total / NANOS_PER_SECOND;
+    case "getMilliseconds":
+      return BigInt(Math.trunc(value.nanos / 1_000_000));
+  }
+}