@venn-lang/core 0.1.0

package/src/typecheck/unify.ts

@@ -0,0 +1,192 @@
+import type {
+  FnType,
+  ListType,
+  LiteralType,
+  RecordType,
+  Type,
+  TypeVar,
+  UnionType,
+} from "./type.types.js";
+import { baseOf, DYNAMIC } from "./type.types.js";
+
+/** Follow solved variables to the type they stand for. */
+export function prune(type: Type): Type {
+  if (type.kind === "var" && type.ref) {
+    const resolved = prune(type.ref);
+    type.ref = resolved;
+    return resolved;
+  }
+  return type;
+}
+
+/**
+ * Make two types equal, solving variables along the way.
+ *
+ * `dynamic` unifies with anything without constraining it. That is the escape
+ * hatch keeping the effectful world from forcing annotations.
+ *
+ * @returns true when they were made equal. Variables solved before a later step
+ * failed stay solved, so a false answer is not a rollback.
+ */
+export function unify(left: Type, right: Type): boolean {
+  const a = prune(left);
+  const b = prune(right);
+  if (a === b) return true;
+  if (a.kind === "dynamic" || b.kind === "dynamic") return true;
+  if (a.kind === "var") return bind(a, b);
+  if (b.kind === "var") return bind(b, a);
+  if (a.kind === "union" || b.kind === "union") return unifyUnion(a, b);
+  if (a.kind === "literal" || b.kind === "literal") return unifyLiteral(a, b);
+  if (a.kind === "opaque" && b.kind === "opaque") return a.name === b.name;
+  if (a.kind === "prim" && b.kind === "prim") return a.name === b.name;
+  if (a.kind === "list" && b.kind === "list") return unify(a.element, b.element);
+  if (a.kind === "fn" && b.kind === "fn") return unifyFn(a, b);
+  if (a.kind === "record" && b.kind === "record") return unifyRecord(a, b);
+  return false;
+}
+
+/** `"GET"` is a string wherever a string is wanted, and itself where it is not. */
+function unifyLiteral(a: Type, b: Type): boolean {
+  if (a.kind === "literal" && b.kind === "literal") return a.value === b.value;
+  const lit: LiteralType = a.kind === "literal" ? a : (b as LiteralType);
+  const other = a.kind === "literal" ? b : a;
+  return other.kind === "prim" && other.name === baseOf(lit.value);
+}
+
+/**
+ * A union is satisfied by any one of its members.
+ *
+ * Membership is decided by {@link matches}, which never binds a variable: trying
+ * a member and rolling back would leave half-solved variables behind, and a
+ * checker that guesses wrong is worse than one that stays quiet.
+ */
+function unifyUnion(a: Type, b: Type): boolean {
+  const [set, other] = a.kind === "union" ? [a, b] : [b as UnionType, a];
+  if (other.kind === "union") {
+    return other.members.every((m) => set.members.some((option) => matches(option, m)));
+  }
+  return set.members.some((option) => matches(option, other));
+}
+
+/**
+ * Could these be the same, without deciding anything?
+ *
+ * Used to pick a union member. Anything unknown, a variable or `dynamic`, counts
+ * as compatible, so a union never turns an open question into an error.
+ */
+function matches(left: Type, right: Type): boolean {
+  const a = prune(left);
+  const b = prune(right);
+  if (a.kind === "dynamic" || b.kind === "dynamic") return true;
+  if (a.kind === "var" || b.kind === "var") return true;
+  if (a.kind === "union") return a.members.some((m) => matches(m, b));
+  if (b.kind === "union") return b.members.some((m) => matches(a, m));
+  return matchesConcrete(a, b);
+}
+
+function matchesConcrete(a: Type, b: Type): boolean {
+  if (a.kind === "literal" || b.kind === "literal") return unifyLiteral(a, b);
+  if (a.kind === "list" && b.kind === "list") return matches(a.element, b.element);
+  if (a.kind === "opaque" && b.kind === "opaque") return a.name === b.name;
+  if (a.kind === "prim" && b.kind === "prim") return a.name === b.name;
+  // Shape is left to real unification; here it is enough that the family agrees.
+  return a.kind === b.kind && (a.kind === "record" || a.kind === "fn");
+}
+
+/** Bind a variable to a type, refusing the infinite type `t = list<t>`. */
+function bind(variable: TypeVar, type: Type): boolean {
+  if (occurs(variable, type)) return false;
+  variable.ref = type;
+  return true;
+}
+
+function occurs(variable: TypeVar, type: Type): boolean {
+  const t = prune(type);
+  if (t === variable) return true;
+  if (t.kind === "list") return occurs(variable, t.element);
+  if (t.kind === "union") return t.members.some((m) => occurs(variable, m));
+  if (t.kind === "fn")
+    return t.params.some((p) => occurs(variable, p)) || occurs(variable, t.result);
+  if (t.kind === "record")
+    return (
+      [...t.fields.values()].some((f) => occurs(variable, f)) ||
+      (t.rest !== undefined && occurs(variable, t.rest))
+    );
+  return false;
+}
+
+function unifyFn(a: FnType, b: FnType): boolean {
+  // A variadic function accepts any argument list; only its result must agree.
+  if (a.variadic || b.variadic) return unify(a.result, b.result);
+  const shared = sharedArity(a, b);
+  if (shared === undefined) return false;
+  for (let at = 0; at < shared; at += 1) {
+    if (!unify(a.params[at] as Type, b.params[at] as Type)) return false;
+  }
+  return unify(a.result, b.result);
+}
+
+/**
+ * How many parameters the two sides must agree on. Normally all of them, but a
+ * callback offered more than it takes agrees on the ones it took, which is how
+ * `people.map(p => p.age)` type-checks against a `map` that also passes an index.
+ */
+function sharedArity(a: FnType, b: FnType): number | undefined {
+  if (a.params.length === b.params.length) return a.params.length;
+  const [shorter, longer] = a.params.length < b.params.length ? [a, b] : [b, a];
+  const ignorable = longer.ignorableFrom;
+  if (ignorable === undefined || shorter.params.length < ignorable) return undefined;
+  return shorter.params.length;
+}
+
+/**
+ * Records unify field by field. An open record (a map used loosely) tolerates
+ * fields the other side lacks; a closed one requires the same shape, except for
+ * fields that may be absent.
+ */
+function unifyRecord(a: RecordType, b: RecordType): boolean {
+  const open = a.open || b.open;
+  if (a.rest && b.rest && !unify(a.rest, b.rest)) return false;
+  for (const [name, type] of a.fields) {
+    const other = b.fields.get(name);
+    if (other) {
+      if (!unify(type, other)) return false;
+    } else if (!open && !omittable(type)) {
+      return false;
+    }
+  }
+  return open || everyPresent(b, a);
+}
+
+/**
+ * May this field simply not be there?
+ *
+ * `nickname?: string` is read as `string | null`, a value that may be nothing.
+ * Absent and null are the same thing to a reader of the map, so a record that
+ * left it out still satisfies one that allows it.
+ */
+function omittable(type: Type): boolean {
+  const t = prune(type);
+  if (t.kind === "prim") return t.name === "null";
+  return t.kind === "union" && t.members.some(omittable);
+}
+
+function everyPresent(from: RecordType, into: RecordType): boolean {
+  for (const [name, type] of from.fields) {
+    if (!into.fields.has(name) && !omittable(type)) return false;
+  }
+  return true;
+}
+
+/**
+ * A field's type on a record. A key nobody listed is whatever the record says
+ * its other keys hold, or `dynamic` when it says nothing, which is a loose map.
+ */
+export function fieldType(record: RecordType, name: string): Type | undefined {
+  const known = record.fields.get(name);
+  if (known) return known;
+  if (!record.open) return undefined;
+  return record.rest ?? DYNAMIC;
+}
+
+export type { ListType };

package/src/typecheck/unit-types.ts

@@ -0,0 +1,49 @@
+import { combine, isUnitValue, type Numeric, parseNumber } from "../units/index.js";
+import { BOOL, NUMBER, prim, type Type } from "./type.types.js";
+
+/** One value of each kind, to ask `combine` what an operator does with them. */
+const SAMPLES: Record<string, Numeric> = {
+  number: 1,
+  duration: { kind: "duration", ms: 1 },
+  size: { kind: "size", bytes: 1 },
+  percent: { kind: "percent", ratio: 1 },
+};
+
+/** The type a NUMBER lexeme has: `200` is a number, `300ms` a duration, `2mb` a size. */
+export function literalType(raw: string): Type {
+  const value = parseNumber(raw);
+  return typeof value === "number" ? NUMBER : prim(value.kind);
+}
+
+/** What an operator produces, or that its operands cannot be combined. */
+export type UnitOutcome = { ok: true; type: Type } | { ok: false };
+
+/**
+ * The type `left op right` produces, decided by the very `combine` the evaluator
+ * uses, handed one value of each kind rather than the real ones.
+ *
+ * Reusing it is the point. Unit compatibility is a single rule (`300ms + 1s`
+ * yes, `300ms + 2mb` no), and writing it a second time for the checker would be
+ * two rules that agree only until one of them changes.
+ *
+ * @returns undefined when either side is not a concrete number or unit: a type
+ * variable still to be solved, `dynamic`, a string. Those keep the ordinary
+ * path, which is what lets `fn double(x) => x * 2` learn that `x` is a number.
+ */
+export function combinedType(op: string, left: Type, right: Type): UnitOutcome | undefined {
+  const a = sampleOf(left);
+  const b = sampleOf(right);
+  if (a === undefined || b === undefined) return undefined;
+  const result = combine({ op, left: a, right: b });
+  return result.ok ? { ok: true, type: typeOfValue(result.value) } : { ok: false };
+}
+
+function sampleOf(type: Type): Numeric | undefined {
+  return type.kind === "prim" ? SAMPLES[type.name] : undefined;
+}
+
+function typeOfValue(value: Numeric | boolean): Type {
+  if (typeof value === "boolean") return BOOL;
+  if (isUnitValue(value)) return prim(value.kind);
+  return NUMBER;
+}

package/src/units/combine.ts

@@ -0,0 +1,97 @@
+import type { UnitKind, UnitValue } from "./unit.types.js";
+
+/** Anything arithmetic accepts: a plain number, or a number carrying a unit. */
+export type Numeric = number | UnitValue;
+
+/** Why two operands would not combine: the operator, and the kind of each side. */
+export type UnitMismatch = { op: string; left: string; right: string };
+
+/** The outcome of {@link combine}: the value, or the mismatch behind VN3012. */
+export type CombineResult =
+  | { ok: true; value: Numeric | boolean }
+  | { ok: false; mismatch: UnitMismatch };
+
+type Norm = { kind: UnitKind | "scalar"; base: number };
+
+const COMPARE = new Set(["<", "<=", ">", ">=", "==", "!="]);
+
+/**
+ * Combine two numerics with an operator, checking that their units agree.
+ *
+ * `300ms + 1s` succeeds; `300ms + 2mb` reports a mismatch. Never throws: the
+ * caller decides whether a mismatch is a problem and where to point at it.
+ *
+ * @returns The combined value, or the mismatch that stopped it.
+ */
+export function combine(args: { op: string; left: Numeric; right: Numeric }): CombineResult {
+  const left = norm(args.left);
+  const right = norm(args.right);
+  const value = COMPARE.has(args.op) ? compare(args.op, left, right) : arith(args.op, left, right);
+  if (value === null)
+    return { ok: false, mismatch: { op: args.op, left: left.kind, right: right.kind } };
+  return { ok: true, value };
+}
+
+/**
+ * Ordering needs a shared unit; equality does not.
+ *
+ * Asking whether a duration is *less than* a size is a question with no answer,
+ * so it reports a mismatch. Asking whether they are *equal* has an obvious one:
+ * they are not. Reporting a mismatch there made `a == b` able to fail, so no
+ * program could compare two values whose units it did not already know.
+ */
+function compare(op: string, l: Norm, r: Norm): boolean | null {
+  if (l.kind === r.kind) return applyCompare(op, l.base, r.base);
+  if (op === "==") return false;
+  return op === "!=" ? true : null;
+}
+
+function arith(op: string, l: Norm, r: Norm): Numeric | null {
+  if (l.kind === "scalar" && r.kind === "scalar") return applyScalar(op, l.base, r.base);
+  if (op === "+" || op === "-")
+    return l.kind === r.kind ? fromBase(l.kind, applyScalar(op, l.base, r.base)) : null;
+  if (op === "*") return scale(l, r);
+  return divide(op, l, r);
+}
+
+function scale(l: Norm, r: Norm): Numeric | null {
+  if (l.kind === "scalar") return fromBase(r.kind, l.base * r.base);
+  if (r.kind === "scalar") return fromBase(l.kind, l.base * r.base);
+  return null;
+}
+
+function divide(op: string, l: Norm, r: Norm): Numeric | null {
+  if (op !== "/" && op !== "%") return null;
+  if (r.kind === "scalar") return fromBase(l.kind, applyScalar(op, l.base, r.base));
+  return l.kind === r.kind ? applyScalar(op, l.base, r.base) : null;
+}
+
+function norm(value: Numeric): Norm {
+  if (typeof value === "number") return { kind: "scalar", base: value };
+  if (value.kind === "duration") return { kind: "duration", base: value.ms };
+  if (value.kind === "size") return { kind: "size", base: value.bytes };
+  return { kind: "percent", base: value.ratio };
+}
+
+function fromBase(kind: UnitKind | "scalar", base: number): Numeric {
+  if (kind === "duration") return { kind, ms: base };
+  if (kind === "size") return { kind, bytes: base };
+  if (kind === "percent") return { kind, ratio: base };
+  return base;
+}
+
+function applyScalar(op: string, a: number, b: number): number {
+  if (op === "+") return a + b;
+  if (op === "-") return a - b;
+  if (op === "*") return a * b;
+  if (op === "/") return a / b;
+  return a % b;
+}
+
+function applyCompare(op: string, a: number, b: number): boolean {
+  if (op === "<") return a < b;
+  if (op === "<=") return a <= b;
+  if (op === ">") return a > b;
+  if (op === ">=") return a >= b;
+  return op === "==" ? a === b : a !== b;
+}

package/src/units/index.ts

@@ -0,0 +1,6 @@
+export type { CombineResult, Numeric, UnitMismatch } from "./combine.js";
+export { combine } from "./combine.js";
+export { parseInstant } from "./parse-instant.js";
+export { parseNumber } from "./parse-number.js";
+export type { Duration, Instant, Percent, Size, UnitKind, UnitValue } from "./unit.types.js";
+export { isInstant, isUnitValue } from "./unit-guards.js";

package/src/units/parse-instant.ts

@@ -0,0 +1,12 @@
+import type { Instant } from "./unit.types.js";
+
+/**
+ * Read an ISO-8601 lexeme into an {@link Instant}, keeping the source text.
+ *
+ * A lexeme that does not parse takes epoch 0 rather than NaN, so comparing two
+ * instants stays total. The grammar has already accepted the shape by here.
+ */
+export function parseInstant(iso: string): Instant {
+  const epochMs = Date.parse(iso);
+  return { kind: "instant", epochMs: Number.isNaN(epochMs) ? 0 : epochMs, iso };
+}

package/src/units/parse-number.ts

@@ -0,0 +1,48 @@
+import type { UnitValue } from "./unit.types.js";
+
+const DURATION_MS: Record<string, number> = { ms: 1, s: 1000, m: 60000, h: 3600000 };
+const SIZE_BYTES: Record<string, number> = { b: 1, kb: 1024, mb: 1048576, gb: 1073741824 };
+
+/**
+ * Lexemes already read, keyed by their text.
+ *
+ * Callers pass `NumberLit.raw`, so this holds one entry per literal written in
+ * the loaded programs. Handing the same parsed value to every caller is safe:
+ * numbers are primitives and a `UnitValue` is readonly throughout, so `combine`
+ * builds new values rather than mutating.
+ */
+const parsed = new Map<string, number | UnitValue>();
+
+/**
+ * Read a NUMBER lexeme into the value it denotes.
+ *
+ * Accepts digit grouping and an optional unit suffix: "200", "1_000", "300ms",
+ * "2mb", "50%". A lexeme with no recognised suffix reads as a plain number.
+ *
+ * @returns A number, or the `UnitValue` the suffix asks for.
+ */
+export function parseNumber(raw: string): number | UnitValue {
+  const known = parsed.get(raw);
+  if (known !== undefined) return known;
+  const value = readLexeme(raw);
+  parsed.set(raw, value);
+  return value;
+}
+
+function readLexeme(raw: string): number | UnitValue {
+  // `_` groups digits for the reader and means nothing to the value: the
+  // grammar only lets it sit between them, so dropping it is safe here.
+  const digits = raw.includes("_") ? raw.replaceAll("_", "") : raw;
+  const match = /^([0-9]+(?:\.[0-9]+)?)(ms|kb|mb|gb|b|s|m|h|%)?$/.exec(digits);
+  if (!match) return Number(digits);
+  const value = Number(match[1]);
+  return match[2] ? toUnitValue(value, match[2]) : value;
+}
+
+function toUnitValue(value: number, unit: string): UnitValue {
+  const ms = DURATION_MS[unit];
+  if (ms !== undefined) return { kind: "duration", ms: value * ms };
+  const bytes = SIZE_BYTES[unit];
+  if (bytes !== undefined) return { kind: "size", bytes: value * bytes };
+  return { kind: "percent", ratio: value / 100 };
+}

package/src/units/unit-guards.ts

@@ -0,0 +1,16 @@
+import type { Instant, UnitValue } from "./unit.types.js";
+
+/** Whether this value carries a unit: a duration, a size or a percent. */
+export function isUnitValue(value: unknown): value is UnitValue {
+  return hasKind(value, ["duration", "size", "percent"]);
+}
+
+/** Whether this value is a point in time. */
+export function isInstant(value: unknown): value is Instant {
+  return hasKind(value, ["instant"]);
+}
+
+function hasKind(value: unknown, kinds: readonly string[]): boolean {
+  if (typeof value !== "object" || value === null || !("kind" in value)) return false;
+  return kinds.includes((value as { kind: string }).kind);
+}

package/src/units/unit.types.ts

@@ -0,0 +1,38 @@
+/**
+ * Unit-typed values.
+ *
+ * Each holds a canonical base unit (milliseconds, bytes, a ratio in 0..1, epoch
+ * milliseconds), so arithmetic never converts and only display does. The `kind`
+ * field is the brand that keeps a unit from reading as an ordinary map.
+ */
+
+/** Which unit a value carries. */
+export type UnitKind = "duration" | "size" | "percent";
+
+/** A length of time, held in milliseconds. */
+export interface Duration {
+  readonly kind: "duration";
+  readonly ms: number;
+}
+
+/** A quantity of data, held in bytes. */
+export interface Size {
+  readonly kind: "size";
+  readonly bytes: number;
+}
+
+/** A proportion, held as a ratio in 0..1 rather than as 0..100. */
+export interface Percent {
+  readonly kind: "percent";
+  readonly ratio: number;
+}
+
+/** A point in time. The source ISO text is kept so printing it back is exact. */
+export interface Instant {
+  readonly kind: "instant";
+  readonly epochMs: number;
+  readonly iso: string;
+}
+
+/** Any value carrying a unit. */
+export type UnitValue = Duration | Size | Percent;

package/src/value/equals.ts

@@ -0,0 +1,4 @@
+/** Strict equality with no coercion: "99.00" (string) never equals 99 (number). */
+export function strictEquals(left: unknown, right: unknown): boolean {
+  return left === right;
+}

package/src/value/index.ts

@@ -0,0 +1,4 @@
+export { strictEquals } from "./equals.js";
+export { isNumeric } from "./is-numeric.js";
+export { truthy } from "./truthiness.js";
+export type { Value } from "./value.types.js";

package/src/value/is-numeric.ts

@@ -0,0 +1,6 @@
+import { isUnitValue, type Numeric } from "../units/index.js";
+
+/** True for plain numbers and unit values (duration/size/percent). */
+export function isNumeric(value: unknown): value is Numeric {
+  return typeof value === "number" || isUnitValue(value);
+}

package/src/value/truthiness.ts

@@ -0,0 +1,9 @@
+import { isUnitValue } from "../units/index.js";
+
+/** Boolean coercion for `!`, `&&`, `||`, and `if` conditions. */
+export function truthy(value: unknown): boolean {
+  if (value === null || value === undefined || value === false) return false;
+  if (value === 0 || value === "") return false;
+  if (isUnitValue(value)) return true;
+  return Boolean(value);
+}

package/src/value/value.types.ts

@@ -0,0 +1,12 @@
+import type { Instant, UnitValue } from "../units/index.js";
+
+/** A runtime value in the language: primitives, unit values, lists, and maps. */
+export type Value =
+  | null
+  | boolean
+  | number
+  | string
+  | UnitValue
+  | Instant
+  | readonly Value[]
+  | { readonly [key: string]: Value };