@oh-my-pi/omptype 17.2.6 → 17.2.8

package/src/errors.ts

@@ -8,33 +8,120 @@
  * All human-readable strings are built lazily on property access.
  */
 
+/** Context supplied to configurable error formatters. */
+export interface ErrorContext {
+	readonly code: string;
+	readonly path: readonly PropertyKey[];
+	readonly propString: string;
+	readonly data: unknown;
+	readonly expected: string;
+	readonly actual: string;
+	readonly problem: string;
+	readonly description: string;
+	readonly rule?: unknown;
+}
+
+/** Per-schema overrides for validation error text. */
+export interface ErrorConfig {
+	readonly expected?: string | ((context: ErrorContext) => string);
+	readonly actual?: string | ((data: unknown) => string);
+	readonly problem?: string | ((context: ErrorContext) => string);
+	readonly message?: string | ((context: ErrorContext) => string);
+	/** Internal: custom predicate expectations display the offending value rather than its domain. */
+	readonly preserveActual?: boolean;
+}
+
+function format(
+	override: string | ((context: ErrorContext) => string) | undefined,
+	context: ErrorContext,
+	fallback: string,
+): string {
+	return typeof override === "function" ? override(context) : (override ?? fallback);
+}
+
 /** A single validation failure at one path. */
 export class OmpError {
+	#rawExpected: string;
+	#config: ErrorConfig | undefined;
+
 	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,
+		expected: string,
 		/** The value that failed validation. */
 		readonly data: unknown,
-	) {}
+		config?: ErrorConfig,
+	) {
+		this.#rawExpected = expected;
+		this.#config = config;
+	}
+	/** Prefix this failure when a nested schema delegates validation. */
+	prefix(key: PropertyKey): this {
+		this.path.unshift(key);
+		return this;
+	}
+
+	/** Apply schema-local formatting to this failure. */
+	configure(config: ErrorConfig): this {
+		this.#config = { ...this.#config, ...config };
+		return this;
+	}
+
+	/** Stable category for programmatic error handling. */
+	get code(): string {
+		return errorCode(this.#rawExpected, this.data);
+	}
+
+	#context(expected: string, actual: string, problem = ""): ErrorContext {
+		const { description, rule } = describeExpectation(this.#rawExpected);
+		return {
+			code: this.code,
+			path: this.path,
+			propString: formatPath(this.path),
+			data: this.data,
+			expected,
+			actual,
+			problem,
+			description,
+			...(rule === undefined ? {} : { rule }),
+		};
+	}
+
+	/** Human-readable expectation, including a configured override. */
+	get expected(): string {
+		const actual = describeValue(this.data, this.#config?.preserveActual ? "predicate" : this.code);
+		const parts = this.#rawExpected.split(" or ");
+		const fallback =
+			parts.length < 3 ? this.#rawExpected : `${parts.slice(0, -1).join(", ")} or ${parts[parts.length - 1]}`;
+		return format(this.#config?.expected, this.#context(fallback, actual), fallback);
+	}
 
 	/** Short description of the received value, e.g. `"a number"` or `"missing"`. */
 	get actual(): string {
-		return describeValue(this.data);
+		const actual = describeValue(this.data, this.#config?.preserveActual ? "predicate" : this.code);
+		const override = this.#config?.actual;
+		return typeof override === "function" ? override(this.data) : (override ?? actual);
 	}
 
 	/** 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})`;
+		const expected = this.expected;
+		const actual = this.actual;
+		const fallback =
+			this.data === MISSING
+				? `must be ${expected} (was missing)`
+				: actual === ""
+					? `must be ${expected}`
+					: `must be ${expected} (was ${actual})`;
+		return format(this.#config?.problem, this.#context(expected, actual, fallback), fallback);
 	}
-
-	/** Full message including the path prefix. */
 	get message(): string {
-		const at = this.path.length === 0 ? "" : `${this.path.map(String).join(".")} `;
-		return `${at}${this.problem}`;
+		const expected = this.expected;
+		const actual = this.actual;
+		const problem = this.problem;
+		const at = this.path.length === 0 ? "" : `${formatPath(this.path)} `;
+		const messageActual = this.#config?.actual === undefined ? describeKind(this.data) : actual;
+		return format(this.#config?.message, this.#context(expected, messageActual, problem), `${at}${problem}`);
 	}
 
 	toString(): string {
@@ -44,8 +131,23 @@ export class OmpError {
 
 /** Sentinel for a required key that was absent (distinguishes from `undefined`). */
 export const MISSING: unique symbol = Symbol("omptype.missing");
+function stringifyValue(data: object): string {
+	const seen = new WeakSet<object>();
+	return (
+		JSON.stringify(data, (_key, value: unknown) => {
+			if (typeof value !== "object" || value === null) return value;
+			if (seen.has(value)) return "(cycle)";
+			seen.add(value);
+			return value;
+		}) ?? "an object"
+	);
+}
 
-function describeValue(data: unknown): string {
+function describeValue(data: unknown, code: string): string {
+	if (data === MISSING) return "missing";
+	if (code === "undeclared") return "";
+	if (code === "referenceSame") return "";
+	if (code === "domain") return describeKind(data);
 	if (data === null) return "null";
 	if (Array.isArray(data)) return "an array";
 	switch (typeof data) {
@@ -60,7 +162,7 @@ function describeValue(data: unknown): string {
 		case "undefined":
 			return "undefined";
 		case "object":
-			return "an object";
+			return stringifyValue(data);
 		case "function":
 			return "a function";
 		default:
@@ -68,48 +170,256 @@ function describeValue(data: unknown): string {
 	}
 }
 
+function describeKind(data: unknown): string {
+	if (data === MISSING) return "missing";
+	if (typeof data === "number" && Number.isNaN(data)) return "NaN";
+	if (data === null) return "null";
+	if (Array.isArray(data)) return "an object";
+	switch (typeof data) {
+		case "string":
+			return "a string";
+		case "number":
+			return "a number";
+		case "bigint":
+			return "a bigint";
+		case "boolean":
+			return "boolean";
+		case "undefined":
+			return "undefined";
+		case "object": {
+			const ctor = Object.getPrototypeOf(data)?.constructor;
+			return typeof ctor?.name === "string" && ctor.name !== "Object" ? ctor.name : "an object";
+		}
+		case "function":
+			return "a function";
+		default:
+			return "a symbol";
+	}
+}
+
+function describeExpectation(expected: string): { description: string; rule?: unknown } {
+	const divisor = /divisible by (\d+(?:\.\d+)?)/.exec(expected);
+	if (divisor) {
+		const rule = Number(divisor[1]);
+		return { description: rule === 2 ? "even" : `divisible by ${rule}`, rule };
+	}
+	return { description: expected.replace(/^(?:an?|the) /, "") };
+}
+
+function formatPath(path: readonly PropertyKey[]): string {
+	let out = "";
+	for (const key of path) {
+		if (typeof key === "number") out += `[${key}]`;
+		else if (typeof key === "symbol") out += `[${String(key)}]`;
+		else out += out.length === 0 ? key : `.${key}`;
+	}
+	return out;
+}
+
+function errorCode(expected: string, data: unknown): string {
+	if (data === MISSING) return "required";
+	if (expected === "removed") return "undeclared";
+	if (expected.includes("serialized to the same value")) return "referenceSame";
+	if (expected.includes("divisible by") || expected.includes("integer")) return "divisor";
+	if (
+		expected === "true" ||
+		expected === "false" ||
+		expected === "null" ||
+		expected === "undefined" ||
+		expected === "NaN" ||
+		expected === "Infinity" ||
+		expected === "-Infinity" ||
+		/^-?\d+(?:\.\d+)?n?$/.test(expected) ||
+		(expected.includes(" or ") &&
+			expected.split(" or ").every(part => /^".*"$|^-?\d+(?:\.\d+)?n?$|^(?:true|false|null|undefined)$/.test(part)))
+	) {
+		return "unit";
+	}
+	if (
+		expected.includes("at least") ||
+		expected.includes("more than") ||
+		expected.includes("timestamp after") ||
+		expected === "non-negative" ||
+		expected === "positive"
+	) {
+		return "min";
+	}
+	if (
+		expected.includes("at most") ||
+		expected.includes("less than") ||
+		expected.includes("timestamp before") ||
+		expected === "non-positive" ||
+		expected === "negative"
+	) {
+		return "max";
+	}
+	if (
+		expected.includes("matching") ||
+		expected.includes("format") ||
+		expected.includes("email") ||
+		expected.includes("parsable") ||
+		expected.includes("only digits")
+	) {
+		return "pattern";
+	}
+	if (expected.includes("predicate") || expected.includes("satisfying") || expected.includes("according to"))
+		return "predicate";
+	if (expected.startsWith('"') || expected.startsWith("the date ")) return "unit";
+	if (expected === "an Error" || expected === "a Date" || expected.startsWith("an instance of ")) return "domain";
+	if (
+		(expected.includes(" or ") && !expected.includes("IPv")) ||
+		expected.endsWith(" instance") ||
+		expected.startsWith("a number representing") ||
+		[
+			"a string",
+			"a number",
+			"a bigint",
+			"a symbol",
+			"boolean",
+			"an object",
+			"an array",
+			"a tuple",
+			"undefined",
+			"null",
+			"unknown",
+			"never",
+		].includes(expected)
+	)
+		return "domain";
+	return "predicate";
+}
+
 /**
- * Aggregate of validation failures; the value returned by a schema call on
- * invalid input. Array-like so callers can `.map()` over entries.
+ * Validation failure result. The common single-error case remains lazy;
+ * traversal only materializes an entry array when a second error is appended.
  */
-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;
+type StoredPath = PropertyKey[] | PropertyKey | undefined;
+
+export class OmpErrors implements Iterable<OmpError> {
+	#path: StoredPath;
+	#expected: string;
+	#data: unknown;
+	#entry: OmpError | undefined;
+	#entries: OmpError[] | undefined;
+	#config: ErrorConfig | undefined;
+	#separator = "\n";
+
+	constructor(path: StoredPath, expected: string, data: unknown, config?: ErrorConfig) {
+		this.#path = path;
+		this.#expected = expected;
+		this.#data = data;
+		this.#config = config;
+	}
+
+	get length(): number {
+		return this.#entries?.length ?? 1;
 	}
 
-	/** 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;
+	get 0(): OmpError {
+		return this.#entries?.[0] ?? this.#getEntry();
 	}
 
-	/** Prefix every entry's path with `key` (used when nesting sub-schemas). */
+	static single(path: PropertyKey[], expected: string, data: unknown, config?: ErrorConfig): OmpErrors {
+		return new OmpErrors(path, expected, data, config);
+	}
+
+	#getEntry(): OmpError {
+		if (this.#entry) return this.#entry;
+		const path = this.#path === undefined ? [] : Array.isArray(this.#path) ? [...this.#path] : [this.#path];
+		const entry = new OmpError(path, this.#expected, this.#data, this.#config);
+		this.#entry = entry;
+		return entry;
+	}
+
+	/** Append all failures from `other`, preserving traversal order. */
+	append(other: OmpErrors): this {
+		this.#entries ??= [this.#getEntry()];
+		const entries = this.#entries;
+		for (const entry of other) entries.push(entry);
+		return this;
+	}
+
+	/** Prefix every failure path with `key` 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);
+		if (this.#entries) {
+			for (const entry of this.#entries) entry.prefix(key);
+		} else {
+			const path = this.#path;
+			this.#path = path === undefined ? [key] : Array.isArray(path) ? [key, ...path] : [key, path];
+			this.#entry = undefined;
+		}
+		return this;
+	}
+
+	/** Apply schema-local message formatting without rebuilding failures. */
+	configure(config: ErrorConfig): this {
+		if (this.#entries) {
+			for (const entry of this.#entries) entry.configure(config);
+		} else {
+			this.#config = { ...this.#config, ...config };
+			this.#entry = undefined;
 		}
 		return this;
 	}
 
-	/** Human-readable digest of every failure, one per line. Built lazily. */
+	get byPath(): Readonly<Record<string, OmpError>> {
+		const result: Record<string, OmpError> = {};
+		for (const entry of this) result[entry.path.map(String).join(".")] = entry;
+		return result;
+	}
+
+	map<result>(fn: (error: OmpError, index: number, errors: OmpErrors) => result): result[] {
+		const result: result[] = [];
+		let index = 0;
+		for (const entry of this) result.push(fn(entry, index++, this));
+		return result;
+	}
+
+	filter(fn: (error: OmpError, index: number, errors: OmpErrors) => unknown): OmpError[] {
+		const result: OmpError[] = [];
+		let index = 0;
+		for (const entry of this) {
+			if (fn(entry, index++, this)) result.push(entry);
+		}
+		return result;
+	}
+
+	*[Symbol.iterator](): IterableIterator<OmpError> {
+		if (this.#entries) {
+			yield* this.#entries;
+		} else {
+			yield this.#getEntry();
+		}
+	}
+
+	/** @internal Render multiple branch failures as alternatives rather than independent failures. */
+	asAlternatives(): this {
+		this.#separator = " or ";
+		return this;
+	}
 	get summary(): string {
-		let out = "";
-		for (let i = 0; i < this.length; i++) {
-			if (i > 0) out += "\n";
-			out += this[i].message;
+		const entries = [...this];
+		if (
+			this.#separator === "\n" &&
+			entries.length > 1 &&
+			entries.every(
+				entry =>
+					Object.is(entry.data, entries[0].data) &&
+					entry.path.length === entries[0].path.length &&
+					entry.path.every((key, index) => key === entries[0].path[index]),
+			)
+		) {
+			const at = formatPath(entries[0].path);
+			const actual = typeof entries[0].data === "string" ? JSON.stringify(entries[0].data) : String(entries[0].data);
+			return `${at}${at === "" ? "" : " "}(${actual}) must be...\n${entries.map(entry => `  ◦ ${entry.expected}`).join("\n")}`;
 		}
-		return out;
+		return entries.map(error => error.message).join(this.#separator);
 	}
 
-	override toString(): string {
+	toString(): string {
 		return this.summary;
 	}
 
-	/** Throw a `TraversalError` carrying the summary. */
 	throw(): never {
 		throw new TraversalError(this);
 	}

package/src/from-json-schema.ts

@@ -0,0 +1,231 @@
+/**
+ * JSON Schema → omptype importer.
+ *
+ * Rebuilds a callable schema from JSON Schema documents — the inverse of
+ * `Type.toJsonSchema()` for the dialect omptype (and its Zod/TypeBox
+ * adapters) emits: draft-07 and draft-2020-12 structural keywords, string
+ * formats, `$defs`/`definitions` references (including recursion), enums,
+ * and composition via `anyOf`/`oneOf`/`allOf`.
+ *
+ * Unknown or non-structural keywords are ignored, matching lenient importer
+ * behavior: the result validates every constraint the schema can express in
+ * omptype IR and passes the rest through.
+ */
+import { OmpTypeError } from "./errors";
+import { type EmbeddableSchema, type IR, IR_BRAND, type PropIR, type TupleItemIR } from "./ir";
+import { keywordIR, patternIR } from "./keywords";
+import { type BaseType, type } from "./type";
+
+type JsonSchema = Record<string, unknown>;
+
+/** `format` values lowered to built-in keyword validators. */
+const FORMAT_KEYWORDS: Record<string, string> = {
+	email: "string.email",
+	uuid: "string.uuid",
+	"date-time": "string.date.iso",
+	date: "string.date.iso",
+	ipv4: "string.ip.v4",
+	ipv6: "string.ip.v6",
+	regex: "string.regex",
+};
+
+class Importer {
+	readonly #root: JsonSchema;
+	readonly #aliases = new Map<string, IR>();
+
+	constructor(root: JsonSchema) {
+		this.#root = root;
+	}
+
+	resolveRef(ref: string): IR {
+		const cached = this.#aliases.get(ref);
+		if (cached !== undefined) return cached;
+
+		let target: unknown;
+		if (ref === "#") {
+			target = this.#root;
+		} else {
+			const defsMatch = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref);
+			if (defsMatch === null) throw new OmpTypeError(`unsupported $ref: ${ref}`);
+			const defs = this.#root[defsMatch[1]];
+			target = typeof defs === "object" && defs !== null ? (defs as JsonSchema)[defsMatch[2]] : undefined;
+			if (target === undefined) throw new OmpTypeError(`unresolved $ref: ${ref}`);
+		}
+
+		// Register the alias before lowering so recursive references resolve
+		// to the same node instead of recursing forever.
+		let lowered: IR | undefined;
+		const alias: IR = {
+			k: "alias",
+			name: ref,
+			resolve: () => {
+				lowered ??= this.lower(target);
+				return lowered;
+			},
+		};
+		this.#aliases.set(ref, alias);
+		return alias;
+	}
+
+	lower(schema: unknown): IR {
+		if (schema === true) return { k: "unknown" };
+		if (schema === false) return { k: "never" };
+		if (typeof schema !== "object" || schema === null) {
+			throw new OmpTypeError("JSON Schema nodes must be booleans or objects");
+		}
+		const node = schema as JsonSchema;
+		const desc = typeof node.description === "string" ? node.description : undefined;
+		const ir = this.#lowerNode(node);
+		return desc === undefined ? ir : { ...ir, desc };
+	}
+
+	#lowerNode(node: JsonSchema): IR {
+		if (typeof node.$ref === "string") return this.resolveRef(node.$ref);
+
+		if (Array.isArray(node.enum)) {
+			const members = node.enum.map((v): IR => ({ k: "lit", v }));
+			return members.length === 1 ? members[0] : { k: "union", members };
+		}
+		if ("const" in node) return { k: "lit", v: node.const };
+
+		const branches = node.anyOf ?? node.oneOf;
+		if (Array.isArray(branches)) {
+			return { k: "union", members: branches.map(branch => this.lower(branch)) };
+		}
+		if (Array.isArray(node.allOf)) {
+			const members = node.allOf.map(branch => this.lower(branch));
+			return members.length === 1 ? members[0] : { k: "intersection", members };
+		}
+		if (typeof node.not === "object" && node.not !== null && Object.keys(node.not).length === 0) {
+			return { k: "never" };
+		}
+
+		if (Array.isArray(node.type)) {
+			const members = node.type.map(t => this.#lowerTyped(node, String(t)));
+			return members.length === 1 ? members[0] : { k: "union", members };
+		}
+		if (typeof node.type === "string") return this.#lowerTyped(node, node.type);
+
+		// No explicit type: infer from structural keywords, else accept anything.
+		if (node.properties !== undefined || node.required !== undefined) return this.#lowerObject(node);
+		if (node.items !== undefined || node.prefixItems !== undefined) return this.#lowerArray(node);
+		return { k: "unknown" };
+	}
+
+	#lowerTyped(node: JsonSchema, kind: string): IR {
+		switch (kind) {
+			case "null":
+				return { k: "null" };
+			case "boolean":
+				return { k: "boolean" };
+			case "string":
+				return this.#lowerString(node);
+			case "number":
+			case "integer": {
+				const ir: IR = { k: "number" };
+				if (kind === "integer") ir.int = true;
+				if (typeof node.minimum === "number") ir.min = node.minimum;
+				if (typeof node.maximum === "number") ir.max = node.maximum;
+				if (typeof node.exclusiveMinimum === "number") {
+					ir.min = node.exclusiveMinimum;
+					ir.xmin = true;
+				}
+				if (typeof node.exclusiveMaximum === "number") {
+					ir.max = node.exclusiveMaximum;
+					ir.xmax = true;
+				}
+				if (typeof node.multipleOf === "number") ir.divisor = node.multipleOf;
+				return ir;
+			}
+			case "object":
+				return this.#lowerObject(node);
+			case "array":
+				return this.#lowerArray(node);
+			default:
+				throw new OmpTypeError(`unsupported JSON Schema type: ${kind}`);
+		}
+	}
+
+	#lowerString(node: JsonSchema): IR {
+		const base: IR = { k: "string" };
+		if (typeof node.minLength === "number") base.min = node.minLength;
+		if (typeof node.maxLength === "number") base.max = node.maxLength;
+		if (node.format === "uri" || node.format === "url") base.url = true;
+
+		const members: IR[] = [];
+		if (typeof node.format === "string") {
+			const keyword = FORMAT_KEYWORDS[node.format];
+			if (keyword !== undefined) {
+				const formatIR = keywordIR(keyword);
+				if (formatIR !== undefined) members.push(formatIR);
+			}
+		}
+		if (typeof node.pattern === "string") members.push(patternIR(new RegExp(node.pattern)));
+
+		if (members.length === 0) return base;
+		if (base.min !== undefined || base.max !== undefined || base.url) members.unshift(base);
+		return members.length === 1 ? members[0] : { k: "intersection", members };
+	}
+
+	#lowerObject(node: JsonSchema): IR {
+		const required = new Set(Array.isArray(node.required) ? node.required.map(String) : []);
+		const props: PropIR[] = [];
+		if (typeof node.properties === "object" && node.properties !== null) {
+			for (const [key, value] of Object.entries(node.properties)) {
+				const prop: PropIR = { key, opt: !required.has(key), val: this.lower(value) };
+				if (typeof value === "object" && value !== null && "default" in value) {
+					prop.hasDefault = true;
+					prop.def = (value as JsonSchema).default;
+					prop.opt = true;
+				}
+				props.push(prop);
+			}
+		}
+		const extra = node.additionalProperties;
+		return {
+			k: "object",
+			props,
+			extras: extra === false ? "reject" : "keep",
+			...(typeof extra === "object" && extra !== null ? { index: this.lower(extra) } : {}),
+		};
+	}
+
+	#lowerArray(node: JsonSchema): IR {
+		if (Array.isArray(node.prefixItems)) {
+			const minItems = typeof node.minItems === "number" ? node.minItems : node.prefixItems.length;
+			const prefix: TupleItemIR[] = node.prefixItems.map((item, index) => ({
+				val: this.lower(item),
+				opt: index >= minItems,
+			}));
+			return {
+				k: "tuple",
+				prefix,
+				postfix: [],
+				...(node.items !== undefined && node.items !== false ? { variadic: this.lower(node.items) } : {}),
+			};
+		}
+		const ir: IR = { k: "array", el: node.items === undefined ? { k: "unknown" } : this.lower(node.items) };
+		if (typeof node.minItems === "number") ir.min = node.minItems;
+		if (typeof node.maxItems === "number") ir.max = node.maxItems;
+		return ir;
+	}
+}
+
+/**
+ * Build a callable omptype schema from a JSON Schema document.
+ *
+ * # Errors
+ * Throws {@link OmpTypeError} on malformed nodes, unresolvable `$ref`s, or
+ * types omptype cannot represent.
+ */
+export function fromJsonSchema(schema: unknown): BaseType {
+	const importer = new Importer(typeof schema === "object" && schema !== null ? (schema as JsonSchema) : {});
+	const embedded: EmbeddableSchema = {
+		[IR_BRAND]: true,
+		ir: importer.lower(schema),
+		hasSteps: false,
+		hasDefault: false,
+		run: value => value,
+	};
+	return type.raw(embedded);
+}

package/src/index.ts

@@ -1,12 +1,12 @@
 /**
  * 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.
+ * ArkType-compatible `type()`/`Type`, keyword modules, recursive scopes,
+ * composition and morph APIs, structured errors, input/output inference, and
+ * JSON Schema emission.
  */
 export * from "./errors";
+export * from "./from-json-schema";
 export * from "./infer";
 export * from "./ir";
 export * from "./json-schema";