@oh-my-pi/omptype 17.2.6

package/src/ir.ts

@@ -0,0 +1,480 @@
+/**
+ * Schema IR and the ArkType-compatible definition parser.
+ *
+ * `parseDef` turns the definition subset this repo uses — string DSL
+ * (primitives, literals, unions, arrays, bounds, `number.integer`,
+ * `string.url`, inline `= literal` defaults), object literals (optional `?`
+ * keys, `"+"` undeclared-key policy, `"[string]"` index signatures), tuple
+ * `[def, "[]"]` arrays, and embedded `Type` instances — into a small IR tree
+ * consumed by the interpreter (`interp.ts`), the JIT compiler (`compile.ts`),
+ * and the JSON Schema emitter (`json-schema.ts`).
+ */
+
+import { OmpTypeError } from "./errors";
+
+/** Brand carried by `Type` instances so the parser can embed them in defs. */
+export const IR_BRAND: unique symbol = Symbol("omptype.schema");
+
+/**
+ * The parser-facing surface of an embedded `Type` instance.
+ * `type.ts` implements this on every schema it creates.
+ */
+export interface EmbeddableSchema {
+	[IR_BRAND]: true;
+	/** Structural IR of the schema (base type when runtime steps exist). */
+	ir: IR;
+	/** True when the schema carries `.pipe()`/`.narrow()` steps. */
+	hasSteps: boolean;
+	/** `.default()` payload; a function is a factory invoked per fill. */
+	defaultValue?: unknown;
+	hasDefault: boolean;
+	/** `.describe()` annotation, emitted into JSON Schema. */
+	description?: string;
+	/** Full validate+morph pipeline (identical to calling the schema). */
+	run(value: unknown): unknown;
+}
+
+/** Policy for undeclared object keys. */
+export type Extras = "keep" | "reject" | "delete";
+
+export type IR =
+	| { k: "unknown"; desc?: string }
+	| { k: "null"; desc?: string }
+	| { k: "undefined"; desc?: string }
+	| { k: "boolean"; desc?: string }
+	| { k: "bigint"; desc?: string }
+	/** Any non-null object (the bare `object` keyword). */
+	| { k: "anyobject"; desc?: string }
+	| { k: "string"; min?: number; max?: number; url?: boolean; desc?: string }
+	| { k: "number"; min?: number; max?: number; xmin?: boolean; xmax?: boolean; int?: boolean; desc?: string }
+	| { k: "lit"; v: unknown; desc?: string }
+	| { k: "union"; members: IR[]; desc?: string }
+	| { k: "array"; el: IR; min?: number; max?: number; desc?: string }
+	| { k: "object"; props: PropIR[]; index?: IR; extras: Extras; desc?: string }
+	/** Embedded schema with runtime steps; validated by calling `run`. */
+	| { k: "sub"; schema: EmbeddableSchema; desc?: string };
+
+export interface PropIR {
+	key: string;
+	opt: boolean;
+	val: IR;
+	/** Default payload (value, or factory when `defFactory`); missing key is filled. */
+	def?: unknown;
+	defFactory?: boolean;
+	hasDefault?: boolean;
+}
+
+/** Definition input accepted by `type()` and object property values. */
+export type Def = string | EmbeddableSchema | readonly Def[] | { readonly [k: string]: Def };
+
+// ── tokenizer ────────────────────────────────────────────────────────────────
+
+type Tok = { t: "id"; v: string } | { t: "num"; v: number } | { t: "str"; v: string } | { t: "op"; v: string };
+
+const SIMPLE_OPS = "|()[]=?";
+
+function tokenize(src: string): Tok[] {
+	const toks: Tok[] = [];
+	let i = 0;
+	const n = src.length;
+	while (i < n) {
+		const c = src[i];
+		if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+			i++;
+			continue;
+		}
+		if (c === "'" || c === '"') {
+			let j = i + 1;
+			while (j < n && src[j] !== c) j++;
+			if (j >= n) throw new OmpTypeError(`unterminated string literal in "${src}"`);
+			toks.push({ t: "str", v: src.slice(i + 1, j) });
+			i = j + 1;
+			continue;
+		}
+		if ((c >= "0" && c <= "9") || (c === "-" && i + 1 < n && src[i + 1] >= "0" && src[i + 1] <= "9")) {
+			let j = i + 1;
+			while (j < n && ((src[j] >= "0" && src[j] <= "9") || src[j] === "." || src[j] === "e" || src[j] === "+")) j++;
+			toks.push({ t: "num", v: Number(src.slice(i, j)) });
+			i = j;
+			continue;
+		}
+		if (/[a-zA-Z_$]/.test(c)) {
+			let j = i + 1;
+			while (j < n && /[\w.$]/.test(src[j])) j++;
+			toks.push({ t: "id", v: src.slice(i, j) });
+			i = j;
+			continue;
+		}
+		if (c === "<" || c === ">") {
+			if (src[i + 1] === "=") {
+				toks.push({ t: "op", v: `${c}=` });
+				i += 2;
+			} else {
+				toks.push({ t: "op", v: c });
+				i++;
+			}
+			continue;
+		}
+		if (SIMPLE_OPS.includes(c)) {
+			toks.push({ t: "op", v: c });
+			i++;
+			continue;
+		}
+		throw new OmpTypeError(`unexpected character '${c}' in "${src}"`);
+	}
+	return toks;
+}
+
+// ── string-definition parser ─────────────────────────────────────────────────
+
+const CMP: Record<string, true> = { "<": true, "<=": true, ">": true, ">=": true };
+
+const KEYWORDS: Record<string, () => IR> = {
+	string: () => ({ k: "string" }),
+	"string.url": () => ({ k: "string", url: true }),
+	number: () => ({ k: "number" }),
+	"number.integer": () => ({ k: "number", int: true }),
+	boolean: () => ({ k: "boolean" }),
+	bigint: () => ({ k: "bigint" }),
+	null: () => ({ k: "null" }),
+	undefined: () => ({ k: "undefined" }),
+	unknown: () => ({ k: "unknown" }),
+	object: () => ({ k: "anyobject" }),
+	true: () => ({ k: "lit", v: true }),
+	false: () => ({ k: "lit", v: false }),
+};
+
+interface ParsedTop {
+	ir: IR;
+	def?: unknown;
+	hasDefault: boolean;
+	/** Trailing `?` marker — only legal on object property values. */
+	optional: boolean;
+}
+
+class StrParser {
+	#toks: Tok[];
+	#pos = 0;
+	#src: string;
+
+	constructor(src: string) {
+		this.#src = src;
+		this.#toks = tokenize(src);
+	}
+
+	#peek(offset = 0): Tok | undefined {
+		return this.#toks[this.#pos + offset];
+	}
+
+	#next(): Tok {
+		const t = this.#toks[this.#pos++];
+		if (!t) throw new OmpTypeError(`unexpected end of definition "${this.#src}"`);
+		return t;
+	}
+
+	#eatOp(v: string): boolean {
+		const t = this.#peek();
+		if (t?.t === "op" && t.v === v) {
+			this.#pos++;
+			return true;
+		}
+		return false;
+	}
+
+	/** Full definition with optional trailing `= literal` default and/or `?` optional marker. */
+	parseTop(): ParsedTop {
+		const ir = this.parseUnion();
+		let def: unknown;
+		let hasDefault = false;
+		if (this.#eatOp("=")) {
+			const t = this.#next();
+			if (t.t === "num" || t.t === "str") def = t.v;
+			else if (t.t === "id" && (t.v === "true" || t.v === "false")) def = t.v === "true";
+			else if (t.t === "id" && t.v === "null") def = null;
+			else throw new OmpTypeError(`unsupported default literal in "${this.#src}"`);
+			hasDefault = true;
+		}
+		const optional = this.#eatOp("?");
+		this.#expectEnd();
+		return { ir, def, hasDefault, optional };
+	}
+
+	#expectEnd(): void {
+		if (this.#pos < this.#toks.length) {
+			throw new OmpTypeError(`trailing tokens in definition "${this.#src}"`);
+		}
+	}
+
+	parseUnion(): IR {
+		const first = this.parseBounded();
+		if (!this.#eatOp("|")) return first;
+		const members = [first, this.parseBounded()];
+		while (this.#eatOp("|")) members.push(this.parseBounded());
+		return { k: "union", members };
+	}
+
+	/**
+	 * `NUM CMP base (CMP NUM)?` or `base (CMP NUM)?`, with `[]*` postfix on the
+	 * base AND after a trailing bound — `string>0[]` is an array of bounded
+	 * strings, matching ArkType precedence (bounds bind tighter than `[]`).
+	 */
+	parseBounded(): IR {
+		const t = this.#peek();
+		const t1 = this.#peek(1);
+		if (t?.t === "num" && t1?.t === "op" && CMP[t1.v]) {
+			// leading bound: `1 <= string <= 10`, `0 < number`
+			const lo = t.v;
+			this.#pos += 2;
+			let node = this.parsePostfix();
+			node = applyBound(node, flip(t1.v), lo, this.#src);
+			const t2 = this.#peek();
+			if (t2?.t === "op" && CMP[t2.v]) {
+				this.#pos++;
+				const hi = this.#next();
+				if (hi.t !== "num") throw new OmpTypeError(`expected number after comparator in "${this.#src}"`);
+				node = applyBound(node, t2.v, hi.v, this.#src);
+			}
+			return this.#eatArraySuffixes(node);
+		}
+		let node = this.parsePostfix();
+		const t2 = this.#peek();
+		if (t2?.t === "op" && CMP[t2.v]) {
+			this.#pos++;
+			const num = this.#next();
+			if (num.t !== "num") throw new OmpTypeError(`expected number after comparator in "${this.#src}"`);
+			node = applyBound(node, t2.v, num.v, this.#src);
+			node = this.#eatArraySuffixes(node);
+		}
+		return node;
+	}
+
+	/** Wrap `node` in array IR for each `[]` pair at the cursor. */
+	#eatArraySuffixes(node: IR): IR {
+		for (;;) {
+			const t = this.#peek();
+			if (!(t?.t === "op" && t.v === "[")) return node;
+			this.#pos++;
+			if (!this.#eatOp("]")) throw new OmpTypeError(`expected ']' in "${this.#src}"`);
+			node = { k: "array", el: node };
+		}
+	}
+
+	parsePostfix(): IR {
+		let node = this.parsePrimary();
+		for (;;) {
+			const t = this.#peek();
+			if (!(t?.t === "op" && t.v === "[")) break;
+			this.#pos++;
+			if (!this.#eatOp("]")) throw new OmpTypeError(`expected ']' in "${this.#src}"`);
+			node = { k: "array", el: node };
+		}
+		return node;
+	}
+
+	parsePrimary(): IR {
+		const t = this.#next();
+		if (t.t === "op" && t.v === "(") {
+			const inner = this.parseUnion();
+			if (!this.#eatOp(")")) throw new OmpTypeError(`expected ')' in "${this.#src}"`);
+			return inner;
+		}
+		if (t.t === "str") return { k: "lit", v: t.v };
+		if (t.t === "num") return { k: "lit", v: t.v };
+		if (t.t === "id") {
+			const make = KEYWORDS[t.v];
+			if (!make) throw new OmpTypeError(`unknown keyword "${t.v}" in "${this.#src}"`);
+			return make();
+		}
+		throw new OmpTypeError(`unexpected token in "${this.#src}"`);
+	}
+}
+
+function flip(op: string): string {
+	switch (op) {
+		case "<":
+			return ">";
+		case "<=":
+			return ">=";
+		case ">":
+			return "<";
+		default:
+			return "<=";
+	}
+}
+
+/** Apply `node CMP value` — numeric range, string length, or array length. */
+function applyBound(node: IR, op: string, value: number, src: string): IR {
+	if (node.k === "number") {
+		switch (op) {
+			case ">=":
+				node.min = value;
+				node.xmin = false;
+				break;
+			case ">":
+				node.min = value;
+				node.xmin = true;
+				break;
+			case "<=":
+				node.max = value;
+				node.xmax = false;
+				break;
+			case "<":
+				node.max = value;
+				node.xmax = true;
+				break;
+		}
+		return node;
+	}
+	if (node.k === "string" || node.k === "array") {
+		switch (op) {
+			case ">=":
+				node.min = value;
+				break;
+			case ">":
+				node.min = value + 1;
+				break;
+			case "<=":
+				node.max = value;
+				break;
+			case "<":
+				node.max = value - 1;
+				break;
+		}
+		return node;
+	}
+	throw new OmpTypeError(`cannot bound ${node.k} in "${src}"`);
+}
+
+// ── definition parser ────────────────────────────────────────────────────────
+
+function isEmbedded(def: unknown): def is EmbeddableSchema {
+	return (typeof def === "function" || (typeof def === "object" && def !== null)) && IR_BRAND in (def as object);
+}
+
+/** Embed a schema value: inline pure structure, keep `sub` nodes for stepped schemas. */
+export function embed(schema: EmbeddableSchema): IR {
+	if (schema.hasSteps) return { k: "sub", schema, desc: schema.description };
+	if (schema.description !== undefined && schema.ir.desc === undefined) {
+		return { ...schema.ir, desc: schema.description };
+	}
+	return schema.ir;
+}
+
+/** Parse a definition (string DSL, object literal, tuple, or embedded schema) into IR. */
+export function parseDef(def: Def): IR {
+	if (typeof def === "string") {
+		const parsed = new StrParser(def).parseTop();
+		if (parsed.optional) throw new OmpTypeError(`optional "?" marker is only valid on object property values`);
+		return parsed.ir;
+	}
+	if (isEmbedded(def)) return embed(def);
+	if (Array.isArray(def)) {
+		if (def.length === 2 && def[1] === "[]") return { k: "array", el: parseDef(def[0] as Def) };
+		throw new OmpTypeError(`unsupported tuple definition (only [def, "[]"])`);
+	}
+	if (typeof def === "object" && def !== null) {
+		const props: PropIR[] = [];
+		let index: IR | undefined;
+		let extras: Extras = "keep";
+		const rec = def as { readonly [k: string]: Def };
+		for (const rawKey in rec) {
+			const val = rec[rawKey];
+			if (rawKey === "+") {
+				if (val === "reject" || val === "delete") extras = val;
+				else if (val === "ignore") extras = "keep";
+				else throw new OmpTypeError(`bad "+" value ${String(val)}`);
+				continue;
+			}
+			if (rawKey === "[string]") {
+				index = parseDef(val);
+				continue;
+			}
+			const opt = rawKey.endsWith("?");
+			const key = opt ? rawKey.slice(0, -1) : rawKey;
+			if (typeof val === "string") {
+				const parsed = new StrParser(val).parseTop();
+				const prop: PropIR = { key, opt: opt || parsed.optional, val: parsed.ir };
+				if (parsed.hasDefault) {
+					prop.def = parsed.def;
+					prop.hasDefault = true;
+				}
+				props.push(prop);
+			} else if (isEmbedded(val) && val.hasDefault) {
+				props.push({
+					key,
+					opt,
+					val: embed(val),
+					def: val.defaultValue,
+					defFactory: typeof val.defaultValue === "function",
+					hasDefault: true,
+				});
+			} else {
+				props.push({ key, opt, val: parseDef(val) });
+			}
+		}
+		return { k: "object", props, index, extras };
+	}
+	throw new OmpTypeError(`unsupported definition ${String(def)}`);
+}
+
+/** True when validating `ir` can produce an output different from its input. */
+export function hasMorph(ir: IR): boolean {
+	switch (ir.k) {
+		case "sub":
+			return true;
+		case "object":
+			if (ir.extras === "delete") return true;
+			for (const p of ir.props) {
+				if (p.hasDefault || hasMorph(p.val)) return true;
+			}
+			return ir.index !== undefined && hasMorph(ir.index);
+		case "array":
+			return hasMorph(ir.el);
+		case "union":
+			return ir.members.some(hasMorph);
+		default:
+			return false;
+	}
+}
+
+/** Human-readable expectation for error messages, e.g. `"a string"`. */
+export function expectedOf(ir: IR): string {
+	switch (ir.k) {
+		case "unknown":
+			return "unknown";
+		case "null":
+			return "null";
+		case "undefined":
+			return "undefined";
+		case "boolean":
+			return "boolean";
+		case "bigint":
+			return "a bigint";
+		case "anyobject":
+			return "an object";
+		case "string": {
+			let out = ir.url ? "a URL string" : "a string";
+			if (ir.min !== undefined && ir.max !== undefined) out += ` (length ${ir.min} to ${ir.max})`;
+			else if (ir.min !== undefined) out += ` (length at least ${ir.min})`;
+			else if (ir.max !== undefined) out += ` (length at most ${ir.max})`;
+			return out;
+		}
+		case "number": {
+			let out = ir.int ? "an integer" : "a number";
+			if (ir.min !== undefined) out += ` ${ir.xmin ? "more than" : "at least"} ${ir.min}`;
+			if (ir.max !== undefined)
+				out += `${ir.min !== undefined ? " and" : ""} ${ir.xmax ? "less than" : "at most"} ${ir.max}`;
+			return out;
+		}
+		case "lit":
+			return typeof ir.v === "string" ? JSON.stringify(ir.v) : String(ir.v);
+		case "union":
+			return [...new Set(ir.members.map(expectedOf))].join(" or ");
+		case "array":
+			return "an array";
+		case "object":
+			return "an object";
+		case "sub":
+			return expectedOf(ir.schema.ir);
+	}
+}

package/src/json-schema.ts

@@ -0,0 +1,172 @@
+import type { IR, PropIR } from "./ir";
+
+export interface JsonSchemaOptions {
+	description?: string;
+}
+
+type JsonSchema = Record<string, unknown>;
+
+/** Emit the draft-2020-12 JSON Schema represented by an IR tree. */
+export function irToJsonSchema(ir: IR, options?: JsonSchemaOptions): JsonSchema {
+	const schema = emit(ir);
+	if (options?.description !== undefined) schema.description = options.description;
+	return schema;
+}
+
+function emit(ir: IR): JsonSchema {
+	let schema: JsonSchema;
+	switch (ir.k) {
+		case "unknown":
+		case "undefined":
+			schema = {};
+			break;
+		case "null":
+			schema = { type: "null" };
+			break;
+		case "boolean":
+			schema = { type: "boolean" };
+			break;
+		case "bigint":
+			schema = { type: "integer" };
+			break;
+		case "anyobject":
+			schema = { type: "object" };
+			break;
+		case "string":
+			schema = emitString(ir);
+			break;
+		case "number":
+			schema = emitNumber(ir);
+			break;
+		case "lit":
+			schema = emitLiteral(ir.v);
+			break;
+		case "union":
+			schema = emitUnion(ir.members);
+			break;
+		case "array":
+			schema = { type: "array", items: emit(ir.el) };
+			if (ir.min !== undefined) schema.minItems = ir.min;
+			if (ir.max !== undefined) schema.maxItems = ir.max;
+			break;
+		case "object":
+			schema = emitObject(ir.props, ir.index, ir.extras);
+			break;
+		case "sub":
+			schema = emit(ir.schema.ir);
+			if (ir.schema.description !== undefined) schema.description = ir.schema.description;
+			break;
+	}
+	if (ir.desc !== undefined) schema.description = ir.desc;
+	return schema;
+}
+
+function emitString(ir: Extract<IR, { k: "string" }>): JsonSchema {
+	const schema: JsonSchema = { type: "string" };
+	if (ir.min !== undefined) schema.minLength = ir.min;
+	if (ir.max !== undefined) schema.maxLength = ir.max;
+	if (ir.url) schema.format = "uri";
+	return schema;
+}
+
+function emitNumber(ir: Extract<IR, { k: "number" }>): JsonSchema {
+	const schema: JsonSchema = { type: ir.int ? "integer" : "number" };
+	if (ir.min !== undefined) schema[ir.xmin ? "exclusiveMinimum" : "minimum"] = ir.min;
+	if (ir.max !== undefined) schema[ir.xmax ? "exclusiveMaximum" : "maximum"] = ir.max;
+	return schema;
+}
+
+function emitLiteral(value: unknown): JsonSchema {
+	if (isJsonValue(value)) return { const: value };
+	switch (typeof value) {
+		case "string":
+			return { type: "string" };
+		case "number":
+			return { type: "number" };
+		case "boolean":
+			return { type: "boolean" };
+		case "bigint":
+			return { type: "integer" };
+		case "object":
+			return { type: "object" };
+		default:
+			return {};
+	}
+}
+
+function emitUnion(members: IR[]): JsonSchema {
+	const defined = members.filter(member => member.k !== "undefined");
+	if (defined.length === 0) return {};
+	if (defined.length === 1) return emit(defined[0]);
+	if (defined.every(member => member.k === "lit" && isJsonValue(member.v))) {
+		const values = defined.map(member => (member as Extract<IR, { k: "lit" }>).v);
+		const schema: JsonSchema = { enum: values };
+		const scalarType = homogeneousScalarType(values);
+		if (scalarType !== undefined) schema.type = scalarType;
+		return schema;
+	}
+	return { anyOf: defined.map(emit) };
+}
+
+function homogeneousScalarType(values: unknown[]): string | undefined {
+	const first = jsonScalarType(values[0]);
+	if (first === undefined) return undefined;
+	for (let i = 1; i < values.length; i++) {
+		if (jsonScalarType(values[i]) !== first) return undefined;
+	}
+	return first;
+}
+
+function jsonScalarType(value: unknown): string | undefined {
+	if (value === null) return "null";
+	switch (typeof value) {
+		case "string":
+		case "number":
+		case "boolean":
+			return typeof value;
+		default:
+			return undefined;
+	}
+}
+
+function emitObject(props: PropIR[], index: IR | undefined, extras: "keep" | "reject" | "delete"): JsonSchema {
+	const properties: Record<string, unknown> = {};
+	const required: string[] = [];
+	// ArkType emits required properties first (each group in declaration
+	// order); downstream wire consumers rely on that stable ordering.
+	const ordered = [...props.filter(p => !p.opt && !p.hasDefault), ...props.filter(p => p.opt || p.hasDefault)];
+	for (const prop of ordered) {
+		const propertySchema = emit(prop.val);
+		if (prop.hasDefault) {
+			propertySchema.default = prop.defFactory ? (prop.def as () => unknown)() : prop.def;
+		}
+		properties[prop.key] = propertySchema;
+		if (!prop.opt && !prop.hasDefault) required.push(prop.key);
+	}
+	const schema: JsonSchema = { type: "object", properties };
+	if (required.length > 0) schema.required = required;
+	if (index !== undefined) schema.additionalProperties = emit(index);
+	else if (extras === "reject") schema.additionalProperties = false;
+	return schema;
+}
+
+function isJsonValue(value: unknown, seen = new Set<object>()): boolean {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object" || seen.has(value)) return false;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			if (!isJsonValue(item, seen)) return false;
+		}
+		seen.delete(value);
+		return true;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return false;
+	for (const key in value) {
+		if (Object.hasOwn(value, key) && !isJsonValue((value as Record<string, unknown>)[key], seen)) return false;
+	}
+	seen.delete(value);
+	return true;
+}