@venn-lang/core 0.1.0

package/src/expr/methods/list-selection.ts

@@ -0,0 +1,142 @@
+import { truthy } from "../../value/index.js";
+import { type Invoke, type Method, nativeFn } from "../native.types.js";
+
+const num = (value: unknown): number => Number(value);
+
+/** Selecting, ordering and summarising: the other half of everyday list work. */
+export const LIST_SELECTION: Record<string, Method> = {
+  take: (list: readonly unknown[]) => nativeFn((args) => list.slice(0, count(args[0]))),
+  drop: (list: readonly unknown[]) => nativeFn((args) => list.slice(count(args[0]))),
+  // Counted from the front, because `slice(-0)` is `slice(0)` and would hand
+  // back the whole list when asked for none of it.
+  takeLast: (list: readonly unknown[]) =>
+    nativeFn((args) => list.slice(Math.max(0, list.length - count(args[0])))),
+  dropLast: (list: readonly unknown[]) =>
+    nativeFn((args) => list.slice(0, Math.max(0, list.length - count(args[0])))),
+  takeWhile: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.slice(0, edge(list, args[0], invoke))),
+  dropWhile: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.slice(edge(list, args[0], invoke))),
+  distinct: (list: readonly unknown[]) => distinct(list, (item) => item),
+  distinctBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => distinct(list, (item, i) => invoke.two(args[0], item, i))),
+  sortBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => sortBy(list, (item, i) => invoke.two(args[0], item, i))),
+  minBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => best(list, (item, i) => num(invoke.two(args[0], item, i)), -1)),
+  maxBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => best(list, (item, i) => num(invoke.two(args[0], item, i)), 1)),
+  sumBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) =>
+      list.reduce((total: number, x, i) => total + num(invoke.two(args[0], x, i)), 0),
+    ),
+  flatMap: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.flatMap((item, i) => flatten(invoke.two(args[0], item, i)))),
+  sum: (list: readonly unknown[]) => list.reduce((total: number, x) => total + num(x), 0),
+  average: (list: readonly unknown[]) =>
+    list.length === 0 ? 0 : list.reduce((total: number, x) => total + num(x), 0) / list.length,
+  // Folded rather than spread: `Math.min(...list)` passes every element as an
+  // argument, and a list of a few hundred thousand overflows the call stack.
+  min: (list: readonly unknown[]) => extreme(list, -1),
+  max: (list: readonly unknown[]) => extreme(list, 1),
+  /** The inverse of a map's `entries`: `[["a", 1]].toMap` gives `{ a: 1 }`. */
+  toMap: (list: readonly unknown[]) => toMap(list),
+  isEmpty: (list: readonly unknown[]) => list.length === 0,
+};
+
+function toMap(list: readonly unknown[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const entry of list) {
+    const pair = Array.isArray(entry) ? entry : [];
+    if (pair.length > 0) out[String(pair[0])] = pair[1];
+  }
+  return out;
+}
+
+function count(value: unknown): number {
+  return Math.max(0, Math.trunc(Number(value ?? 0)));
+}
+
+/** The smallest or largest number in a list, or null when there is none. */
+function extreme(list: readonly unknown[], direction: 1 | -1): number | null {
+  if (list.length === 0) return null;
+  let best = num(list[0]);
+  for (let at = 1; at < list.length; at += 1) {
+    const value = num(list[at]);
+    if (Number.isNaN(value)) return Number.NaN;
+    if (value * direction > best * direction) best = value;
+  }
+  return best;
+}
+
+/** Where the run of items satisfying the predicate ends. */
+function edge(list: readonly unknown[], fn: unknown, invoke: Invoke): number {
+  let index = 0;
+  while (index < list.length && truthy(invoke.two(fn, list[index], index))) index += 1;
+  return index;
+}
+
+function distinct(
+  list: readonly unknown[],
+  keyOf: (item: unknown, i: number) => unknown,
+): unknown[] {
+  const seen = new Set<string>();
+  const out: unknown[] = [];
+  list.forEach((item, index) => {
+    const key = JSON.stringify(keyOf(item, index)) ?? "";
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(item);
+  });
+  return out;
+}
+
+/**
+ * Sort by a derived key, ordering positions rather than the items themselves.
+ *
+ * The keys go in one array and the positions in another, so the sort moves
+ * numbers and nothing is allocated per item. It stays stable, which is what
+ * leaves items whose keys tie in the order they came.
+ */
+function sortBy(list: readonly unknown[], keyOf: (item: unknown, i: number) => unknown): unknown[] {
+  const size = list.length;
+  const keys = new Array<unknown>(size);
+  const order = new Array<number>(size);
+  for (let at = 0; at < size; at += 1) {
+    keys[at] = keyOf(list[at], at);
+    order[at] = at;
+  }
+  order.sort((left, right) => compare(keys[left], keys[right]));
+  const out = new Array<unknown>(size);
+  for (let at = 0; at < size; at += 1) out[at] = list[order[at] as number];
+  return out;
+}
+
+/** Numbers compare as numbers; anything else compares as its text. */
+function compare(left: unknown, right: unknown): number {
+  if (typeof left === "number" && typeof right === "number") return left - right;
+  const a = String(left);
+  const b = String(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function best(
+  list: readonly unknown[],
+  scoreOf: (item: unknown, i: number) => number,
+  direction: number,
+): unknown {
+  let winner: unknown = null;
+  let score = Number.NaN;
+  list.forEach((item, index) => {
+    const value = scoreOf(item, index);
+    if (Number.isNaN(score) || (value - score) * direction > 0) {
+      winner = item;
+      score = value;
+    }
+  });
+  return winner;
+}
+
+function flatten(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [value];
+}

package/src/expr/methods/map-extras.ts

@@ -0,0 +1,87 @@
+import { type Invoke, type Method, nativeFn } from "../native.types.js";
+
+type Dict = Record<string, unknown>;
+
+/** Reshaping a map without a loop: rename, project, combine, walk a path. */
+export const MAP_EXTRAS: Record<string, Method> = {
+  mapValues: (map: Dict, invoke: Invoke) =>
+    nativeFn((args) => rebuild(map, ([k, v]) => [k, invoke.two(args[0], v, k)])),
+  mapKeys: (map: Dict, invoke: Invoke) =>
+    nativeFn((args) => rebuild(map, ([k, v]) => [String(invoke.two(args[0], k, v)), v])),
+  filterValues: (map: Dict, invoke: Invoke) =>
+    nativeFn((args) => keepIf(map, ([k, v]) => Boolean(invoke.two(args[0], v, k)))),
+  pick: (map: Dict) => nativeFn((args) => keepIf(map, ([k]) => names(args).includes(k))),
+  omit: (map: Dict) => nativeFn((args) => keepIf(map, ([k]) => !names(args).includes(k))),
+  mergeDeep: (map: Dict) => nativeFn((args) => mergeDeep(map, asDict(args[0]))),
+  invert: (map: Dict) => rebuild(map, ([k, v]) => [String(v), k]),
+  isEmpty: (map: Dict) => Object.keys(map).length === 0,
+  /** `getPath("a.b.c")` reaches into nested data without a chain of guards. */
+  getPath: (map: Dict) => nativeFn((args) => walk(map, String(args[0] ?? ""))),
+  /** Whether the path leads anywhere, including to a field holding `null`. */
+  hasPath: (map: Dict) => nativeFn((args) => reach(map, String(args[0] ?? "")) !== ABSENT),
+};
+
+/** The inverse of `entries`: `fromEntries([["a", 1]])` gives `{ a: 1 }`. */
+export function fromEntries(list: readonly unknown[]): Dict {
+  const out: Dict = {};
+  for (const entry of list) {
+    const pair = Array.isArray(entry) ? entry : [];
+    if (pair.length > 0) out[String(pair[0])] = pair[1];
+  }
+  return out;
+}
+
+function rebuild(map: Dict, step: (entry: [string, unknown]) => [string, unknown]): Dict {
+  return Object.fromEntries(Object.entries(map).map(step));
+}
+
+function keepIf(map: Dict, keep: (entry: [string, unknown]) => boolean): Dict {
+  return Object.fromEntries(Object.entries(map).filter(keep));
+}
+
+/** Flatten the argument list: `pick("a", "b")` and `pick(["a", "b"])` both work. */
+function names(args: readonly unknown[]): string[] {
+  return args.flatMap((arg) => (Array.isArray(arg) ? arg : [arg])).map(String);
+}
+
+function mergeDeep(left: Dict, right: Dict): Dict {
+  const out: Dict = { ...left };
+  for (const [key, value] of Object.entries(right)) {
+    const current = out[key];
+    out[key] = isDict(current) && isDict(value) ? mergeDeep(current, value) : value;
+  }
+  return out;
+}
+
+/** Nothing at all is here, told apart from a field that holds nothing. */
+const ABSENT = Symbol("venn.absent");
+
+/**
+ * Follow a dotted path, answering {@link ABSENT} when it leads nowhere.
+ *
+ * A field holding `null` and a field that does not exist are different facts,
+ * and collapsing them made `hasPath` answer `false` for a key that was plainly
+ * there.
+ */
+function reach(map: Dict, path: string): unknown {
+  let current: unknown = map;
+  for (const part of path.split(".")) {
+    if (!isDict(current) && !Array.isArray(current)) return ABSENT;
+    if (!Object.hasOwn(current as Dict, part)) return ABSENT;
+    current = (current as Dict)[part];
+  }
+  return current;
+}
+
+function walk(map: Dict, path: string): unknown {
+  const found = reach(map, path);
+  return found === ABSENT ? null : (found ?? null);
+}
+
+function isDict(value: unknown): value is Dict {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function asDict(value: unknown): Dict {
+  return isDict(value) ? value : {};
+}

package/src/expr/methods/map-methods.ts

@@ -0,0 +1,17 @@
+import { type Method, nativeFn } from "../native.types.js";
+
+type Dict = Record<string, unknown>;
+
+/**
+ * Methods on a map value. Checked only after a data property of the same name,
+ * so a map with a key called `keys` still reads that key.
+ */
+export const MAP_METHODS: Record<string, Method> = {
+  keys: (map: Dict) => Object.keys(map),
+  values: (map: Dict) => Object.values(map),
+  entries: (map: Dict) => Object.entries(map).map(([key, value]) => [key, value]),
+  has: (map: Dict) => nativeFn((args) => String(args[0]) in map),
+  get: (map: Dict) => nativeFn((args) => map[String(args[0])] ?? null),
+  len: (map: Dict) => Object.keys(map).length,
+  merge: (map: Dict) => nativeFn((args) => ({ ...map, ...(args[0] as Dict) })),
+};

package/src/expr/methods/number-methods.ts

@@ -0,0 +1,29 @@
+import { type Method, nativeFn } from "../native.types.js";
+
+/** Methods on a number. Rounding and clamping without reaching for a namespace. */
+export const NUMBER_METHODS: Record<string, Method> = {
+  abs: (value: number) => Math.abs(value),
+  floor: (value: number) => Math.floor(value),
+  ceil: (value: number) => Math.ceil(value),
+  sign: (value: number) => Math.sign(value),
+  sqrt: (value: number) => Math.sqrt(value),
+  isEven: (value: number) => value % 2 === 0,
+  isOdd: (value: number) => Math.abs(value % 2) === 1,
+  round: (value: number) => nativeFn((args) => roundTo(value, Number(args[0] ?? 0))),
+  toFixed: (value: number) => nativeFn((args) => value.toFixed(places(args[0]))),
+  clamp: (value: number) =>
+    nativeFn((args) => Math.min(Math.max(value, Number(args[0])), Number(args[1]))),
+  pow: (value: number) => nativeFn((args) => value ** Number(args[0])),
+  times: (value: number) => Array.from({ length: Math.max(0, Math.trunc(value)) }, (_x, i) => i),
+  toString: (value: number) => String(value),
+};
+
+function roundTo(value: number, decimals: number): number {
+  const scale = 10 ** places(decimals);
+  return Math.round(value * scale) / scale;
+}
+
+function places(value: unknown): number {
+  const parsed = Math.trunc(Number(value ?? 0));
+  return Number.isNaN(parsed) ? 0 : Math.min(20, Math.max(0, parsed));
+}

package/src/expr/methods/string-extras.ts

@@ -0,0 +1,66 @@
+import { type Method, nativeFn } from "../native.types.js";
+
+const COMBINING = /[\u0300-\u036f]/g;
+
+/** Text handling a script actually needs: words, lines, casing, slugs, matching. */
+export const STRING_EXTRAS: Record<string, Method> = {
+  words: (text: string) => text.split(/\s+/).filter(Boolean),
+  lines: (text: string) => text.split(/\r?\n/),
+  chars: (text: string) => [...text],
+  capitalize: (text: string) => text.charAt(0).toUpperCase() + text.slice(1),
+  title: (text: string) => text.replace(/\S+/g, capitalizeWord),
+  slugify: (text: string) => slugify(text),
+  isEmpty: (text: string) => text.length === 0,
+  isBlank: (text: string) => text.trim().length === 0,
+  trimStart: (text: string) => text.trimStart(),
+  trimEnd: (text: string) => text.trimEnd(),
+  count: (text: string) => nativeFn((args) => occurrences(text, String(args[0] ?? ""))),
+  matches: (text: string) => nativeFn((args) => matches(text, String(args[0] ?? ""))),
+  test: (text: string) => nativeFn((args) => regex(String(args[0] ?? ""))?.test(text) ?? false),
+  before: (text: string) => nativeFn((args) => cut(text, String(args[0] ?? ""), true)),
+  after: (text: string) => nativeFn((args) => cut(text, String(args[0] ?? ""), false)),
+  ensureStart: (text: string) => nativeFn((args) => prefixed(text, String(args[0] ?? ""))),
+  ensureEnd: (text: string) => nativeFn((args) => suffixed(text, String(args[0] ?? ""))),
+};
+
+function capitalizeWord(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+}
+
+/** `"João Gonçalves"` becomes `"joao-goncalves"`: ASCII-safe, url-ready. */
+function slugify(text: string): string {
+  const plain = text.normalize("NFD").replace(COMBINING, "").toLowerCase();
+  return plain.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+function occurrences(text: string, needle: string): number {
+  return needle === "" ? 0 : text.split(needle).length - 1;
+}
+
+/** Every match of a pattern, as a list of strings. An invalid pattern matches nothing. */
+function matches(text: string, pattern: string): string[] {
+  const expression = regex(pattern, "g");
+  return expression ? [...text.matchAll(expression)].map((match) => match[0]) : [];
+}
+
+function regex(pattern: string, flags = ""): RegExp | undefined {
+  try {
+    return new RegExp(pattern, flags);
+  } catch {
+    return undefined;
+  }
+}
+
+function cut(text: string, marker: string, keepHead: boolean): string {
+  const at = text.indexOf(marker);
+  if (at < 0) return keepHead ? text : "";
+  return keepHead ? text.slice(0, at) : text.slice(at + marker.length);
+}
+
+function prefixed(text: string, prefix: string): string {
+  return text.startsWith(prefix) ? text : `${prefix}${text}`;
+}
+
+function suffixed(text: string, suffix: string): string {
+  return text.endsWith(suffix) ? text : `${text}${suffix}`;
+}

package/src/expr/methods/string-methods.ts

@@ -0,0 +1,32 @@
+import { type Method, nativeFn } from "../native.types.js";
+
+function end(value: unknown): number | undefined {
+  return value === undefined ? undefined : Number(value);
+}
+
+/**
+ * Members of a string value. A no-argument transform is a property, read
+ * without parentheses (`name.upper`); anything taking an argument is a method
+ * (`name.split(",")`). `replace` replaces every occurrence.
+ */
+export const STRING_METHODS: Record<string, Method> = {
+  len: (text: string) => text.length,
+  upper: (text: string) => text.toUpperCase(),
+  lower: (text: string) => text.toLowerCase(),
+  trim: (text: string) => text.trim(),
+  reverse: (text: string) => [...text].reverse().join(""),
+  toNumber: (text: string) => Number(text),
+  split: (text: string) => nativeFn((args) => text.split(String(args[0] ?? ""))),
+  replace: (text: string) =>
+    nativeFn((args) => text.split(String(args[0])).join(String(args[1] ?? ""))),
+  contains: (text: string) => nativeFn((args) => text.includes(String(args[0]))),
+  startsWith: (text: string) => nativeFn((args) => text.startsWith(String(args[0]))),
+  endsWith: (text: string) => nativeFn((args) => text.endsWith(String(args[0]))),
+  slice: (text: string) => nativeFn((args) => text.slice(Number(args[0] ?? 0), end(args[1]))),
+  repeat: (text: string) => nativeFn((args) => text.repeat(Math.max(0, Number(args[0] ?? 0)))),
+  padStart: (text: string) =>
+    nativeFn((args) => text.padStart(Number(args[0] ?? 0), String(args[1] ?? " "))),
+  padEnd: (text: string) =>
+    nativeFn((args) => text.padEnd(Number(args[0] ?? 0), String(args[1] ?? " "))),
+  indexOf: (text: string) => nativeFn((args) => text.indexOf(String(args[0]))),
+};

package/src/expr/methods/unit-methods.ts

@@ -0,0 +1,54 @@
+import type { Duration, Percent, Size } from "../../units/index.js";
+import { type Method, nativeFn } from "../native.types.js";
+
+/**
+ * Reading a unit back as a plain number, in whichever unit you want it.
+ *
+ * A `duration` knows it is a duration; what it does not know is whether you
+ * want to print milliseconds or minutes. These are the way across, and they all
+ * land on `number`, the unit having served its purpose by then.
+ */
+export const DURATION_METHODS: Record<string, Method> = {
+  ms: (value: Duration) => value.ms,
+  seconds: (value: Duration) => value.ms / 1000,
+  minutes: (value: Duration) => value.ms / 60000,
+  hours: (value: Duration) => value.ms / 3600000,
+};
+
+export const SIZE_METHODS: Record<string, Method> = {
+  bytes: (value: Size) => value.bytes,
+  kb: (value: Size) => value.bytes / 1024,
+  mb: (value: Size) => value.bytes / 1048576,
+  gb: (value: Size) => value.bytes / 1073741824,
+};
+
+export const PERCENT_METHODS: Record<string, Method> = {
+  ratio: (value: Percent) => value.ratio,
+  percent: (value: Percent) => value.ratio * 100,
+  // `12%.of(50)` is 6: the share of something, which is what a percent is for.
+  of: (value: Percent) => nativeFn((args) => Number(args[0]) * value.ratio),
+};
+
+/**
+ * Reading a plain number *as* a unit: the way back.
+ *
+ * Symmetric with the tables above. `2mb.kb` writes a size out as 2048 and
+ * `2048.toKb` reads 2048 back as that size, so for every `X` a unit answers to,
+ * a number answers to `toX`.
+ */
+export const NUMBER_TO_UNIT: Record<string, Method> = {
+  toMs: (value: number) => duration(value),
+  toSeconds: (value: number) => duration(value * 1000),
+  toMinutes: (value: number) => duration(value * 60000),
+  toHours: (value: number) => duration(value * 3600000),
+  toBytes: (value: number) => size(value),
+  toKb: (value: number) => size(value * 1024),
+  toMb: (value: number) => size(value * 1048576),
+  toGb: (value: number) => size(value * 1073741824),
+  toRatio: (value: number) => percent(value),
+  toPercent: (value: number) => percent(value / 100),
+};
+
+const duration = (ms: number): Duration => ({ kind: "duration", ms });
+const size = (bytes: number): Size => ({ kind: "size", bytes });
+const percent = (ratio: number): Percent => ({ kind: "percent", ratio });

package/src/expr/namespace.ts

@@ -0,0 +1,20 @@
+const NAMESPACE = Symbol("venn.namespace");
+
+/**
+ * A plugin namespace as a value (`fmt`, `data`, `crypto`), so its verbs can be
+ * called from any expression: `print(fmt.table(rows))`.
+ *
+ * Marked, because a name the user binds must still win over a namespace of the
+ * same name, and a bare `data.faker.uuid` must still read as a call rather than
+ * as the function itself.
+ */
+export function namespaceValue(members: Record<string, unknown>): Record<string, unknown> {
+  return Object.assign(Object.create(null) as Record<string, unknown>, members, {
+    [NAMESPACE]: true,
+  });
+}
+
+/** Whether this value is a namespace rather than an ordinary map. */
+export function isNamespaceValue(value: unknown): boolean {
+  return typeof value === "object" && value !== null && NAMESPACE in value;
+}

package/src/expr/native.types.ts

@@ -0,0 +1,40 @@
+/**
+ * Invoke a Venn callable (a closure or another native fn) with values.
+ *
+ * The fixed arities are part of the contract because the built-in methods are
+ * the hottest callers there are: `map` and `reduce` call once per element, and
+ * an argument list would be one array per element. Injected rather than
+ * imported, so a method never depends on the invoker itself.
+ */
+export interface Invoke {
+  (fn: unknown, values: readonly unknown[]): unknown;
+  one(fn: unknown, a: unknown): unknown;
+  two(fn: unknown, a: unknown, b: unknown): unknown;
+  three(fn: unknown, a: unknown, b: unknown, c: unknown): unknown;
+}
+
+/** A built-in method on a native value: `[1,2].map`, `"a".upper`. */
+export type Method = (receiver: never, invoke: Invoke) => unknown;
+
+const NATIVE = Symbol("venn.native");
+
+/** A callable backed by a host function rather than by Venn source. */
+export interface NativeFn {
+  readonly [NATIVE]: true;
+  call(values: readonly unknown[]): unknown;
+}
+
+/** Whether this value is a host-backed callable. */
+export function isNativeFn(value: unknown): value is NativeFn {
+  return typeof value === "object" && value !== null && NATIVE in value;
+}
+
+/**
+ * Wrap a host function so the language can call it.
+ *
+ * The wrapper takes the whole argument list: arity is the host function's own
+ * business, and a plugin verb reads what it needs and ignores the rest.
+ */
+export function nativeFn(call: (values: readonly unknown[]) => unknown): NativeFn {
+  return { [NATIVE]: true, call };
+}

package/src/expr/operators.ts

@@ -0,0 +1,91 @@
+import { buildProblem, CODES } from "../codes/index.js";
+import { ProblemError } from "../problem/index.js";
+import { combine, type Numeric } from "../units/index.js";
+import { isNumeric, strictEquals } from "../value/index.js";
+import { isWaiting, whenBothReady } from "./pending.js";
+
+const NO_SPAN = { uri: "", offset: 0, length: 0, line: 1, column: 1 };
+
+/**
+ * Two plain numbers, where the unit machinery has nothing to decide. Going
+ * through `combine` for `x + 1` normalises both sides into fresh objects and
+ * asks whether their units agree, which for scalars is always yes.
+ *
+ * The compiler looks the operator up here once, so at run time this is a
+ * captured function rather than a table read.
+ */
+export const PLAIN: Record<string, (a: number, b: number) => number | boolean> = {
+  "+": (a, b) => a + b,
+  "-": (a, b) => a - b,
+  "*": (a, b) => a * b,
+  "/": (a, b) => a / b,
+  "%": (a, b) => a % b,
+  "<": (a, b) => a < b,
+  "<=": (a, b) => a <= b,
+  ">": (a, b) => a > b,
+  ">=": (a, b) => a >= b,
+  "==": (a, b) => a === b,
+  "!=": (a, b) => a !== b,
+};
+
+/**
+ * Apply a binary operator to two values of any kind.
+ *
+ * @throws ProblemError VN3012 when the units do not agree, or when the operator
+ * has no meaning for these values.
+ */
+export function applyBinary(op: string, left: unknown, right: unknown): unknown {
+  // Only on the slow path: two plain numbers never reach here. Either side may
+  // still be on its way, in which case the answer is too.
+  if (isWaiting(left) || isWaiting(right)) {
+    return whenBothReady(left, right, (a, b) => applyBinary(op, a, b));
+  }
+  if (op === "in") return isIn(left, right);
+  if (op === "~=") return regexMatch(left, right);
+  if (isNumeric(left) && isNumeric(right)) return numeric(op, left, right);
+  if (op === "==") return strictEquals(left, right);
+  if (op === "!=") return !strictEquals(left, right);
+  throw operatorError(op);
+}
+
+/** Negate a numeric, keeping its unit. */
+export function negate(value: Numeric): unknown {
+  const result = combine({ op: "*", left: value, right: -1 });
+  return result.ok ? result.value : value;
+}
+
+function numeric(op: string, left: Numeric, right: Numeric): unknown {
+  const result = combine({ op, left, right });
+  if (result.ok) return result.value;
+  throw new ProblemError(
+    buildProblem({
+      spec: CODES.VN3012_UNIT_MISMATCH,
+      span: NO_SPAN,
+      title: `Cannot combine ${result.mismatch.left} with ${result.mismatch.right} using "${op}".`,
+    }),
+  );
+}
+
+function isIn(left: unknown, right: unknown): boolean {
+  if (Array.isArray(right)) return right.includes(left);
+  if (typeof right === "string") return right.includes(String(left));
+  return false;
+}
+
+function regexMatch(subject: unknown, pattern: unknown): boolean {
+  try {
+    return new RegExp(String(pattern)).test(String(subject));
+  } catch {
+    return false;
+  }
+}
+
+function operatorError(op: string): ProblemError {
+  return new ProblemError(
+    buildProblem({
+      spec: CODES.VN3012_UNIT_MISMATCH,
+      span: NO_SPAN,
+      title: `Operator "${op}" cannot be applied to these values.`,
+    }),
+  );
+}

package/src/expr/pending.ts

@@ -0,0 +1,47 @@
+/**
+ * Values that have not arrived yet, travelling up an expression.
+ *
+ * Expressions compile to synchronous functions, so a plugin verb called from
+ * inside one hands back the promise it is running on rather than its result.
+ * Computing with that promise would quietly produce nonsense, so each node that
+ * meets one chains onto it and hands a promise to *its* parent. The statement
+ * at the top is already asynchronous and waits there.
+ *
+ * The effect is that `await` never has to be written: a function reaching for
+ * something slow returns something slow, all the way up, and the statement that
+ * binds it gets the value. Nothing pays for this until a promise appears, and
+ * the checks sit past the fast paths ordinary values take.
+ */
+
+/** Whether this value is still on its way. */
+export function isWaiting(value: unknown): value is Promise<unknown> {
+  return value instanceof Promise;
+}
+
+/** Continue once this value has arrived, or immediately if it already has. */
+export function whenReady<T>(value: unknown, then: (settled: unknown) => T): T | Promise<T> {
+  return isWaiting(value) ? value.then(then) : then(value);
+}
+
+/** The same for a pair, without building an array when neither is waiting. */
+export function whenBothReady<T>(
+  left: unknown,
+  right: unknown,
+  then: (a: unknown, b: unknown) => T,
+): T | Promise<T> {
+  if (!isWaiting(left) && !isWaiting(right)) return then(left, right);
+  return Promise.all([left, right]).then(([a, b]) => then(a, b));
+}
+
+/** The same for a list: `Promise.all` only when one of them is waiting. */
+export function whenAllReady<T>(
+  values: readonly unknown[],
+  then: (settled: unknown[]) => T,
+): T | Promise<T> {
+  // An index loop, not `for…of`: this runs once per call and the iterator a
+  // `for…of` allocates showed up as 25% on a call-heavy program.
+  for (let at = 0; at < values.length; at += 1) {
+    if (isWaiting(values[at])) return Promise.all(values).then(then);
+  }
+  return then(values as unknown[]);
+}