@oh-my-pi/omptype 17.2.6

package/src/compile.ts

@@ -0,0 +1,415 @@
+/**
+ * JIT compiler: lowers schema IR into a specialized validator via
+ * `new Function`. Invoked by `type.ts` after a schema's third call; the
+ * interpreter (`interp.ts`) covers earlier calls so rarely-used schemas never
+ * pay codegen cost.
+ *
+ * Generated code philosophy:
+ * - success path is straight-line monomorphic JS with zero allocation; when
+ *   the schema has no morphs the input value itself is returned
+ * - failure allocates a single `OmpErrors` (`E(path, expected, data)`); path
+ *   arrays and messages are inline literals, so cost is one small allocation
+ * - morphing nodes (defaults, `"+": "delete"`, embedded stepped schemas)
+ *   produce a fresh output object; pure subtrees below them stay check-only
+ * - union members that morph are validated by hoisted interpreter closures;
+ *   pure members compile to inline predicates
+ */
+import { MISSING, OmpErrors } from "./errors";
+import { unionFail, walk } from "./interp";
+import { expectedOf, hasMorph, type IR, type PropIR } from "./ir";
+
+const own = Object.prototype.hasOwnProperty;
+
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+
+function access(base: string, key: string): string {
+	return IDENT.test(key) ? `${base}.${key}` : `${base}[${JSON.stringify(key)}]`;
+}
+
+/** Inline-able literal, else undefined (caller hoists into the refs pool). */
+function litSource(v: unknown): string | undefined {
+	if (v === null) return "null";
+	if (v === undefined) return "undefined";
+	switch (typeof v) {
+		case "string":
+		case "boolean":
+			return JSON.stringify(v);
+		case "number":
+			return Number.isFinite(v) ? String(v) : undefined;
+		default:
+			return undefined;
+	}
+}
+
+type PathSeg = { s: PropertyKey } | { d: string };
+
+class Builder {
+	#lines: string[] = [];
+	#refs: unknown[] = [];
+	#id = 0;
+
+	next(prefix: string): string {
+		return `${prefix}${this.#id++}`;
+	}
+
+	push(line: string): void {
+		this.#lines.push(line);
+	}
+
+	ref(value: unknown): string {
+		const idx = this.#refs.indexOf(value);
+		if (idx >= 0) return `R[${idx}]`;
+		this.#refs.push(value);
+		return `R[${this.#refs.length - 1}]`;
+	}
+
+	lit(v: unknown): string {
+		return litSource(v) ?? this.ref(v);
+	}
+
+	pathExpr(segs: PathSeg[]): string {
+		const parts = segs.map(seg => ("s" in seg ? JSON.stringify(seg.s) : seg.d));
+		return `[${parts.join(",")}]`;
+	}
+
+	fail(segs: PathSeg[], expected: string, dataExpr: string): string {
+		return `return E(${this.pathExpr(segs)},${JSON.stringify(expected)},${dataExpr})`;
+	}
+
+	/** Pure boolean predicate for a morph-free subtree. */
+	predicate(node: IR, v: string): string {
+		switch (node.k) {
+			case "unknown":
+				return "true";
+			case "null":
+				return `${v}===null`;
+			case "undefined":
+				return `${v}===undefined`;
+			case "boolean":
+				return `typeof ${v}==="boolean"`;
+			case "bigint":
+				return `typeof ${v}==="bigint"`;
+			case "anyobject":
+				return `(typeof ${v}==="object"&&${v}!==null)`;
+			case "lit":
+				return `${v}===${this.lit(node.v)}`;
+			case "string": {
+				let out = `typeof ${v}==="string"`;
+				if (node.min !== undefined) out += `&&${v}.length>=${node.min}`;
+				if (node.max !== undefined) out += `&&${v}.length<=${node.max}`;
+				if (node.url) out += `&&URL.canParse(${v})`;
+				return out;
+			}
+			case "number": {
+				let out = `typeof ${v}==="number"`;
+				if (node.int) out += `&&Number.isInteger(${v})`;
+				if (node.min !== undefined) out += `&&${v}${node.xmin ? ">" : ">="}${node.min}`;
+				if (node.max !== undefined) out += `&&${v}${node.xmax ? "<" : "<="}${node.max}`;
+				return out;
+			}
+			case "union": {
+				const lits = node.members.filter(m => m.k === "lit");
+				if (lits.length > 4) {
+					const set = this.ref(new Set(lits.map(m => m.v)));
+					const rest = node.members.filter(m => m.k !== "lit");
+					let out = `${set}.has(${v})`;
+					for (const m of rest) out += `||(${this.predicate(m, v)})`;
+					return `(${out})`;
+				}
+				return `(${node.members.map(m => `(${this.predicate(m, v)})`).join("||")})`;
+			}
+			case "array": {
+				const x = this.next("x");
+				let out = `Array.isArray(${v})`;
+				if (node.min !== undefined) out += `&&${v}.length>=${node.min}`;
+				if (node.max !== undefined) out += `&&${v}.length<=${node.max}`;
+				out += `&&${v}.every(${x}=>${this.predicate(node.el, x)})`;
+				return out;
+			}
+			case "object": {
+				const checks = [`typeof ${v}==="object"`, `${v}!==null`, `!Array.isArray(${v})`];
+				for (const p of node.props) {
+					const av = access(v, p.key);
+					const present = `${JSON.stringify(p.key)} in ${v}`;
+					checks.push(
+						p.opt || p.hasDefault
+							? `(!(${present})||(${this.predicate(p.val, av)}))`
+							: `((${present})&&(${this.predicate(p.val, av)}))`,
+					);
+				}
+				if (node.index) {
+					const k = this.next("k");
+					checks.push(
+						`(()=>{for(const ${k} in ${v})if(own.call(${v},${k})&&!(${this.predicate(node.index, `${v}[${k}]`)}))return false;return true})()`,
+					);
+				} else if (node.extras === "reject") {
+					const k = this.next("k");
+					checks.push(
+						`(()=>{for(const ${k} in ${v})if(own.call(${v},${k})&&!(${this.declaredCheck(node.props, k)}))return false;return true})()`,
+					);
+				}
+				return `(${checks.join("&&")})`;
+			}
+			case "sub":
+				return `!(${this.ref(node.schema.run)}(${v}) instanceof AE)`;
+		}
+	}
+
+	declaredCheck(props: PropIR[], keyVar: string): string {
+		if (props.length === 0) return "false";
+		if (props.length > 6) {
+			const set = this.ref(new Set(props.map(p => p.key)));
+			return `${set}.has(${keyVar})`;
+		}
+		return `(${props.map(p => `${keyVar}===${JSON.stringify(p.key)}`).join("||")})`;
+	}
+
+	/** Statement-form check for a morph-free subtree with precise error paths. */
+	emitCheck(node: IR, v: string, segs: PathSeg[]): void {
+		switch (node.k) {
+			case "unknown":
+				return;
+			case "array": {
+				let head = `Array.isArray(${v})`;
+				if (node.min !== undefined) head += `&&${v}.length>=${node.min}`;
+				if (node.max !== undefined) head += `&&${v}.length<=${node.max}`;
+				this.push(`if(!(${head}))${this.fail(segs, expectedOf(node), v)};`);
+				const i = this.next("i");
+				const x = this.next("x");
+				this.push(`for(let ${i}=0;${i}<${v}.length;${i}++){const ${x}=${v}[${i}];`);
+				this.emitCheck(node.el, x, [...segs, { d: i }]);
+				this.push("}");
+				return;
+			}
+			case "object": {
+				this.push(
+					`if(typeof ${v}!=="object"||${v}===null||Array.isArray(${v}))${this.fail(segs, "an object", v)};`,
+				);
+				for (const p of node.props) {
+					const present = `${JSON.stringify(p.key)} in ${v}`;
+					const propSegs: PathSeg[] = [...segs, { s: p.key }];
+					if (p.opt || p.hasDefault) {
+						this.push(`if(${present}){`);
+						this.emitCheck(p.val, access(v, p.key), propSegs);
+						this.push("}");
+					} else {
+						this.push(`if(!(${present}))${this.fail(propSegs, expectedOf(p.val), "M")};`);
+						this.emitCheck(p.val, access(v, p.key), propSegs);
+					}
+				}
+				if (node.index) {
+					const k = this.next("k");
+					this.push(`for(const ${k} in ${v})if(own.call(${v},${k})){`);
+					this.emitCheck(node.index, `${v}[${k}]`, [...segs, { d: k }]);
+					this.push("}");
+				} else if (node.extras === "reject") {
+					const k = this.next("k");
+					this.push(
+						`for(const ${k} in ${v})if(own.call(${v},${k})&&!(${this.declaredCheck(node.props, k)}))${this.fail(
+							[...segs, { d: k }],
+							"removed (undeclared key)",
+							`${v}[${k}]`,
+						)};`,
+					);
+				}
+				return;
+			}
+			case "sub": {
+				const r = this.next("r");
+				this.push(`const ${r}=${this.ref(node.schema.run)}(${v});`);
+				this.push(`if(${r} instanceof AE)return PF(${r},${this.pathExpr(segs)});`);
+				return;
+			}
+			case "union":
+				this.push(`if(!(${this.predicate(node, v)}))return UF(${this.ref(node)},${v},${this.pathExpr(segs)});`);
+				return;
+			default:
+				this.push(`if(!(${this.predicate(node, v)}))${this.fail(segs, expectedOf(node), v)};`);
+		}
+	}
+
+	/**
+	 * Validate `v` against a morphing subtree and assign the produced output
+	 * to `out` (an already-declared `let`).
+	 */
+	emitProduce(node: IR, v: string, segs: PathSeg[], out: string): void {
+		if (!hasMorph(node)) {
+			this.emitCheck(node, v, segs);
+			this.push(`${out}=${v};`);
+			return;
+		}
+		switch (node.k) {
+			case "sub": {
+				const r = this.next("r");
+				this.push(`const ${r}=${this.ref(node.schema.run)}(${v});`);
+				this.push(`if(${r} instanceof AE)return PF(${r},${this.pathExpr(segs)});`);
+				this.push(`${out}=${r};`);
+				return;
+			}
+			case "union": {
+				const ok = this.next("u");
+				this.push(`let ${ok}=false;`);
+				const label = this.next("b");
+				this.push(`${label}:{`);
+				for (const m of node.members) {
+					if (m.k !== "sub" && !hasMorph(m)) {
+						this.push(`if(${this.predicate(m, v)}){${out}=${v};${ok}=true;break ${label};}`);
+					}
+				}
+				for (const m of node.members) {
+					if (m.k === "sub" || hasMorph(m)) {
+						const runner = m.k === "sub" ? m.schema.run : boundWalk(m);
+						const r = this.next("r");
+						this.push(`const ${r}=${this.ref(runner)}(${v});`);
+						this.push(`if(!(${r} instanceof AE)){${out}=${r};${ok}=true;break ${label};}`);
+					}
+				}
+				this.push("}");
+				this.push(`if(!${ok})return UF(${this.ref(node)},${v},${this.pathExpr(segs)});`);
+				return;
+			}
+			case "array": {
+				let head = `Array.isArray(${v})`;
+				if (node.min !== undefined) head += `&&${v}.length>=${node.min}`;
+				if (node.max !== undefined) head += `&&${v}.length<=${node.max}`;
+				this.push(`if(!(${head}))${this.fail(segs, expectedOf(node), v)};`);
+				const arr = this.next("a");
+				const i = this.next("i");
+				const x = this.next("x");
+				const el = this.next("t");
+				this.push(`const ${arr}=new Array(${v}.length);`);
+				this.push(`for(let ${i}=0;${i}<${v}.length;${i}++){const ${x}=${v}[${i}];let ${el};`);
+				this.emitProduce(node.el, x, [...segs, { d: i }], el);
+				this.push(`${arr}[${i}]=${el};}`);
+				this.push(`${out}=${arr};`);
+				return;
+			}
+			case "object": {
+				this.push(
+					`if(typeof ${v}!=="object"||${v}===null||Array.isArray(${v}))${this.fail(segs, "an object", v)};`,
+				);
+				const o = this.next("o");
+				const fresh = node.extras === "delete" && !node.index;
+				this.push(fresh ? `const ${o}={};` : `const ${o}={...${v}};`);
+				for (const p of node.props) {
+					const present = `${JSON.stringify(p.key)} in ${v}`;
+					const propSegs: PathSeg[] = [...segs, { s: p.key }];
+					const av = access(v, p.key);
+					const ao = access(o, p.key);
+					const morphChild = hasMorph(p.val);
+					const missing: string[] = [];
+					if (p.hasDefault) {
+						const dflt = p.defFactory ? `${this.ref(p.def)}()` : this.lit(p.def);
+						missing.push(`${ao}=${dflt};`);
+					} else if (!p.opt) {
+						missing.push(`${this.fail(propSegs, expectedOf(p.val), "M")};`);
+					} else if (fresh) {
+						// optional + absent under "delete": nothing to copy
+					}
+					this.push(`if(!(${present})){${missing.join("")}}else{`);
+					if (morphChild) {
+						const t = this.next("t");
+						this.push(`let ${t};`);
+						this.emitProduce(p.val, av, propSegs, t);
+						this.push(`${ao}=${t};`);
+					} else {
+						this.emitCheck(p.val, av, propSegs);
+						if (fresh) this.push(`${ao}=${av};`);
+					}
+					this.push("}");
+				}
+				if (node.index) {
+					const k = this.next("k");
+					this.push(`for(const ${k} in ${v})if(own.call(${v},${k})){`);
+					if (hasMorph(node.index)) {
+						const t = this.next("t");
+						this.push(`let ${t};`);
+						this.emitProduce(node.index, `${v}[${k}]`, [...segs, { d: k }], t);
+						this.push(`${o}[${k}]=${t};`);
+					} else {
+						this.emitCheck(node.index, `${v}[${k}]`, [...segs, { d: k }]);
+					}
+					this.push("}");
+				} else if (node.extras === "reject") {
+					const k = this.next("k");
+					this.push(
+						`for(const ${k} in ${v})if(own.call(${v},${k})&&!(${this.declaredCheck(node.props, k)}))${this.fail(
+							[...segs, { d: k }],
+							"removed (undeclared key)",
+							`${v}[${k}]`,
+						)};`,
+					);
+				}
+				this.push(`${out}=${o};`);
+				return;
+			}
+			default:
+				// morph-free kinds are handled by the hasMorph guard above
+				this.emitCheck(node, v, segs);
+				this.push(`${out}=${v};`);
+		}
+	}
+
+	build(ir: IR): (value: unknown) => unknown {
+		let ret: string;
+		if (hasMorph(ir)) {
+			this.push("let o;");
+			// body emitted below needs `o` declared first, so splice ordering:
+			this.emitProduce(ir, "v", [], "o");
+			ret = "o";
+		} else {
+			this.emitCheck(ir, "v", []);
+			ret = "v";
+		}
+		const src = `return function(v){${this.#lines.join("")}return ${ret}}`;
+		const make = new Function("R", "E", "AE", "M", "PF", "UF", "own", src) as (
+			refs: unknown[],
+			e: typeof OmpErrors.single,
+			ae: typeof OmpErrors,
+			m: typeof MISSING,
+			pf: typeof prefixErrors,
+			uf: typeof unionFail,
+			ownFn: typeof own,
+		) => (value: unknown) => unknown;
+		return make(this.#refs, OmpErrors.single, OmpErrors, MISSING, prefixErrors, unionFail, own);
+	}
+}
+
+function prefixErrors(errs: OmpErrors, parts: PropertyKey[]): OmpErrors {
+	for (let i = parts.length - 1; i >= 0; i--) errs.prefix(parts[i]);
+	return errs;
+}
+
+const kWalk = Symbol("omptype.boundWalk");
+
+interface WalkTagged {
+	[kWalk]?: (value: unknown) => unknown;
+}
+
+/** Interpreter closure for a morphing union member (rare; hoisted into refs). */
+function boundWalk(node: IR): (value: unknown) => unknown {
+	const tagged = node as IR & WalkTagged;
+	let fn = tagged[kWalk];
+	if (!fn) {
+		fn = (value: unknown) => walk(node, value);
+		tagged[kWalk] = fn;
+	}
+	return fn;
+}
+
+/** Compile `ir` into a specialized validator. */
+export function compile(ir: IR): (value: unknown) => unknown {
+	return new Builder().build(ir);
+}
+
+/** Generated source for inspection/debugging. */
+export function compileToSource(ir: IR): string {
+	const b = new Builder();
+	if (hasMorph(ir)) {
+		b.push("let o;");
+		b.emitProduce(ir, "v", [], "o");
+		return `function(v){/* refs elided */return o}`;
+	}
+	b.emitCheck(ir, "v", []);
+	return `function(v){/* refs elided */return v}`;
+}

package/src/errors.ts

@@ -0,0 +1,136 @@
+/**
+ * Validation error containers mirroring ArkType's observable error surface:
+ * `result instanceof type.errors` / `instanceof OmpErrors`, lazy `.summary`,
+ * array iteration, and per-entry `.path` / `.problem` / `.message`.
+ *
+ * Failure-path cost matters: schemas reject untrusted input constantly, so
+ * construction stores only the path, the expectation, and the offending value.
+ * All human-readable strings are built lazily on property access.
+ */
+
+/** A single validation failure at one path. */
+export class OmpError {
+	constructor(
+		/** Property path from the root to the failing value (empty at root). */
+		readonly path: PropertyKey[],
+		/** Human-readable expectation, e.g. `"a string"` or `"at most 3600"`. */
+		readonly expected: string,
+		/** The value that failed validation. */
+		readonly data: unknown,
+	) {}
+
+	/** Short description of the received value, e.g. `"a number"` or `"missing"`. */
+	get actual(): string {
+		return describeValue(this.data);
+	}
+
+	/** Path-less problem statement: `must be <expected> (was <actual>)`. */
+	get problem(): string {
+		return this.data === MISSING
+			? `must be ${this.expected} (was missing)`
+			: `must be ${this.expected} (was ${this.actual})`;
+	}
+
+	/** Full message including the path prefix. */
+	get message(): string {
+		const at = this.path.length === 0 ? "" : `${this.path.map(String).join(".")} `;
+		return `${at}${this.problem}`;
+	}
+
+	toString(): string {
+		return this.message;
+	}
+}
+
+/** Sentinel for a required key that was absent (distinguishes from `undefined`). */
+export const MISSING: unique symbol = Symbol("omptype.missing");
+
+function describeValue(data: unknown): string {
+	if (data === null) return "null";
+	if (Array.isArray(data)) return "an array";
+	switch (typeof data) {
+		case "string":
+			return data.length <= 40 ? JSON.stringify(data) : `a string (length ${data.length})`;
+		case "number":
+			return String(data);
+		case "bigint":
+			return `${data}n`;
+		case "boolean":
+			return String(data);
+		case "undefined":
+			return "undefined";
+		case "object":
+			return "an object";
+		case "function":
+			return "a function";
+		default:
+			return "a symbol";
+	}
+}
+
+/**
+ * Aggregate of validation failures; the value returned by a schema call on
+ * invalid input. Array-like so callers can `.map()` over entries.
+ */
+export class OmpErrors extends Array<OmpError> {
+	// `.map()`/`.filter()` on an errors instance should produce plain arrays,
+	// not attempt `new OmpErrors(n)`.
+	static override get [Symbol.species](): typeof Array {
+		return Array;
+	}
+
+	/** Single-failure constructor used by generated validators. */
+	static single(path: PropertyKey[], expected: string, data: unknown): OmpErrors {
+		const out = new OmpErrors();
+		out.push(new OmpError(path, expected, data));
+		return out;
+	}
+
+	/** Prefix every entry's path with `key` (used when nesting sub-schemas). */
+	prefix(key: PropertyKey): this {
+		for (let i = 0; i < this.length; i++) {
+			const e = this[i];
+			this[i] = new OmpError([key, ...e.path], e.expected, e.data);
+		}
+		return this;
+	}
+
+	/** Human-readable digest of every failure, one per line. Built lazily. */
+	get summary(): string {
+		let out = "";
+		for (let i = 0; i < this.length; i++) {
+			if (i > 0) out += "\n";
+			out += this[i].message;
+		}
+		return out;
+	}
+
+	override toString(): string {
+		return this.summary;
+	}
+
+	/** Throw a `TraversalError` carrying the summary. */
+	throw(): never {
+		throw new TraversalError(this);
+	}
+}
+
+/** Error thrown by `Type.assert` on invalid input. */
+export class TraversalError extends Error {
+	constructor(readonly errors: OmpErrors) {
+		super(errors.summary);
+		this.name = "TraversalError";
+	}
+}
+
+/**
+ * Definition/usage error thrown while building a schema — malformed string
+ * DSL, unsupported composition, or an illegal builder call. Distinct from
+ * validation failures, which are returned as {@link OmpErrors}.
+ */
+export class OmpTypeError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "OmpTypeError";
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * omptype — ArkType-compatible schema validation with a lazy JIT runtime.
+ *
+ * Drop-in for the arktype surface this repo uses:
+ * `type()`, `Type`, `type.errors` / `OmpErrors`, `type.enumerated()`,
+ * `.or/.and/.array/.pipe/.narrow/.describe/.default/.allows/.assert/.toJsonSchema`,
+ * plus `typeof schema.infer` static inference.
+ */
+export * from "./errors";
+export * from "./infer";
+export * from "./ir";
+export * from "./json-schema";
+export * from "./type";