@oh-my-pi/omptype 17.2.7 → 17.2.8

package/src/json-schema.ts

@@ -3,17 +3,36 @@ import type { IR, PropIR } from "./ir";
 export interface JsonSchemaOptions {
 	description?: string;
 	target?: string;
-	dialect?: string;
+	dialect?: string | null;
+	/**
+	 * Which side of morphs and defaults to describe:
+	 * - `'input'` — accepted payloads: morphs emit their input shape, defaulted
+	 *   properties are optional (with `default` annotations).
+	 * - `'output'` — produced values: morphs emit their output shape, defaulted
+	 *   properties are required (always present after validation).
+	 * Unset keeps the hybrid legacy behavior (morph output, defaults optional).
+	 */
+	io?: "input" | "output";
 	fallback?: (context: { base: Record<string, unknown> }) => unknown;
 }
 
 type JsonSchema = Record<string, unknown>;
 
+interface EmitCtx {
+	options?: JsonSchemaOptions;
+	/** Emitted alias definitions, attached as `$defs` on the root schema. */
+	defs: Map<string, JsonSchema>;
+	/** Alias resolver identity → assigned `$defs` name (cycle-safe). */
+	refs: Map<() => IR, string>;
+}
+
 /** Emit the requested JSON Schema dialect represented by an IR tree. */
 export function irToJsonSchema(ir: IR, options?: JsonSchemaOptions): JsonSchema {
-	let schema = emit(ir, options);
+	const ctx: EmitCtx = { options, defs: new Map(), refs: new Map() };
+	let schema = emit(ir, ctx);
+	if (ctx.defs.size > 0) schema.$defs = Object.fromEntries(ctx.defs);
 	if (options?.target === "draft-07") schema = toDraft7(schema);
-	const dialect = options?.dialect ?? dialectFor(options?.target);
+	const dialect = options?.dialect === null ? undefined : (options?.dialect ?? dialectFor(options?.target));
 	if (dialect !== undefined) schema.$schema = dialect;
 	if (options?.description !== undefined) schema.description = options.description;
 	return schema;
@@ -22,11 +41,11 @@ export function irToJsonSchema(ir: IR, options?: JsonSchemaOptions): JsonSchema
 function dialectFor(target: string | undefined): string | undefined {
 	if (target === "draft-2020-12") return "https://json-schema.org/draft/2020-12/schema";
 	if (target === "draft-07") return "http://json-schema.org/draft-07/schema#";
-	return target?.startsWith("http://") || target?.startsWith("https://") ? target : undefined;
+	return target !== undefined && (target.startsWith("http://") || target.startsWith("https://")) ? target : undefined;
 }
 
-function fallback(schema: JsonSchema, options?: JsonSchemaOptions): JsonSchema {
-	const replacement = options?.fallback?.({ base: schema });
+function fallback(schema: JsonSchema, ctx: EmitCtx): JsonSchema {
+	const replacement = ctx.options?.fallback?.({ base: schema });
 	if (replacement === true) return {};
 	if (replacement === false) return { not: {} };
 	return typeof replacement === "object" && replacement !== null ? (replacement as JsonSchema) : schema;
@@ -36,7 +55,11 @@ function toDraft7(schema: JsonSchema): JsonSchema {
 	const converted: JsonSchema = {};
 	for (const key in schema) {
 		const value = schema[key];
-		if (key === "prefixItems" && Array.isArray(value)) {
+		if (key === "$ref" && typeof value === "string") {
+			converted.$ref = value.replace("#/$defs/", "#/definitions/");
+		} else if (key === "$defs") {
+			converted.definitions = toDraft7(value as JsonSchema);
+		} else if (key === "prefixItems" && Array.isArray(value)) {
 			converted.items = value.map(item =>
 				typeof item === "object" && item !== null ? toDraft7(item as JsonSchema) : item,
 			);
@@ -56,14 +79,14 @@ function toDraft7(schema: JsonSchema): JsonSchema {
 	return converted;
 }
 
-function emit(ir: IR, options?: JsonSchemaOptions): JsonSchema {
+function emit(ir: IR, ctx: EmitCtx): JsonSchema {
 	let schema: JsonSchema;
 	switch (ir.k) {
 		case "unknown":
 			schema = {};
 			break;
 		case "undefined":
-			schema = fallback({}, options);
+			schema = fallback({}, ctx);
 			break;
 		case "null":
 			schema = { type: "null" };
@@ -75,7 +98,7 @@ function emit(ir: IR, options?: JsonSchemaOptions): JsonSchema {
 			schema = { type: "integer" };
 			break;
 		case "symbol":
-			schema = fallback({}, options);
+			schema = fallback({}, ctx);
 			break;
 		case "never":
 			schema = { not: {} };
@@ -93,19 +116,19 @@ function emit(ir: IR, options?: JsonSchemaOptions): JsonSchema {
 			schema = emitLiteral(ir.v);
 			break;
 		case "union":
-			schema = emitUnion(ir.members, options);
+			schema = emitUnion(ir.members, ctx);
 			break;
 		case "intersection":
-			schema = { allOf: ir.members.map(member => emit(member, options)) };
+			schema = { allOf: ir.members.map(member => emit(member, ctx)) };
 			break;
 		case "array":
-			schema = { type: "array", items: emit(ir.el, options) };
+			schema = { type: "array", items: emit(ir.el, ctx) };
 			if (ir.min !== undefined) schema.minItems = ir.min;
 			if (ir.max !== undefined) schema.maxItems = ir.max;
 			break;
 		case "tuple": {
 			const prefixItems = ir.prefix.map(item => {
-				const itemSchema = emit(item.val, options);
+				const itemSchema = emit(item.val, ctx);
 				if (item.hasDefault) {
 					itemSchema.default = item.defFactory && typeof item.def === "function" ? item.def() : item.def;
 				}
@@ -117,35 +140,57 @@ function emit(ir: IR, options?: JsonSchemaOptions): JsonSchema {
 			);
 			schema = { type: "array", prefixItems, minItems: required };
 			if (ir.variadic === undefined) {
-				schema.maxItems = ir.prefix.length + ir.postfix.length;
 				schema.items = false;
 			} else {
-				schema.items = emit(ir.variadic, options);
+				schema.items = emit(ir.variadic, ctx);
 			}
 			break;
 		}
 		case "object":
-			schema = emitObject(ir.props, ir.index, ir.extras, options);
+			schema = emitObject(ir.props, ir.index, ir.extras, ctx);
 			break;
 		case "instance":
-			schema = ir.ctor === Date ? { type: "string", format: "date-time" } : fallback({ type: "object" }, options);
+			schema = ir.ctor === Date ? { type: "string", format: "date-time" } : fallback({ type: "object" }, ctx);
 			break;
 		case "refine":
-			schema = emit(ir.base, options);
+			schema = emit(ir.base, ctx);
 			if (ir.json !== undefined) Object.assign(schema, ir.json);
 			break;
 		case "morph":
-			schema = fallback(emit(ir.out ?? ir.input, options), options);
+			schema = ctx.options?.io === "input" ? emit(ir.input, ctx) : fallback(emit(ir.out ?? ir.input, ctx), ctx);
 			break;
-		case "alias":
-			schema = emit(ir.resolve(), options);
+		case "alias": {
+			const known = ctx.refs.get(ir.resolve);
+			if (known !== undefined) {
+				schema = { $ref: `#/$defs/${known}` };
+				break;
+			}
+			// Register before lowering so cyclic aliases resolve to the same $ref
+			// instead of recursing forever.
+			let name = ir.name.replace(/[^\w.-]/g, "_");
+			while ([...ctx.refs.values()].includes(name)) name = `${name}_`;
+			ctx.refs.set(ir.resolve, name);
+			ctx.defs.set(name, emit(ir.resolve(), ctx));
+			schema = { $ref: `#/$defs/${name}` };
 			break;
+		}
 		case "sub":
-			schema = ir.schema.hasSteps ? fallback(emit(ir.schema.ir, options), options) : emit(ir.schema.ir, options);
-			if (ir.schema.description !== undefined) schema.description = ir.schema.description;
+			if (ctx.options?.io === "output" && ir.schema.opaqueOutput) {
+				schema = {};
+			} else if (ctx.options?.io === "output" && ir.schema.stepOut !== undefined) {
+				schema = emit(ir.schema.stepOut, ctx);
+			} else if (ctx.options?.io === "input") {
+				schema = emit(ir.schema.ir, ctx);
+			} else {
+				schema = ir.schema.hasSteps ? fallback(emit(ir.schema.ir, ctx), ctx) : emit(ir.schema.ir, ctx);
+			}
+			if (ir.schema.ir.desc !== undefined) schema.description = ir.schema.ir.desc;
+			else if (ir.schema.description !== undefined && ir.descAuto !== true) {
+				schema.description = ir.schema.description;
+			}
 			break;
 	}
-	if (ir.desc !== undefined) schema.description = ir.desc;
+	if (ir.desc !== undefined && ir.descAuto !== true) schema.description = ir.desc;
 	return schema;
 }
 
@@ -184,10 +229,10 @@ function emitLiteral(value: unknown): JsonSchema {
 	}
 }
 
-function emitUnion(members: IR[], options?: JsonSchemaOptions): JsonSchema {
+function emitUnion(members: IR[], ctx: EmitCtx): JsonSchema {
 	const defined = members.filter(member => member.k !== "undefined");
 	if (defined.length === 0) return {};
-	if (defined.length === 1) return emit(defined[0], options);
+	if (defined.length === 1) return emit(defined[0], ctx);
 	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 };
@@ -195,7 +240,7 @@ function emitUnion(members: IR[], options?: JsonSchemaOptions): JsonSchema {
 		if (scalarType !== undefined) schema.type = scalarType;
 		return schema;
 	}
-	return { anyOf: defined.map(member => emit(member, options)) };
+	return { anyOf: defined.map(member => emit(member, ctx)) };
 }
 
 function homogeneousScalarType(values: unknown[]): string | undefined {
@@ -223,24 +268,27 @@ function emitObject(
 	props: PropIR[],
 	index: IR | undefined,
 	extras: "keep" | "reject" | "delete",
-	options?: JsonSchemaOptions,
+	ctx: EmitCtx,
 ): JsonSchema {
 	const properties: Record<string, unknown> = {};
 	const required: string[] = [];
+	const filled = (prop: PropIR): boolean => !prop.opt && (ctx.options?.io === "output" || !prop.hasDefault);
 	// 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)];
+	const ordered = [...props.filter(filled), ...props.filter(prop => !filled(prop))];
 	for (const prop of ordered) {
-		const propertySchema = emit(prop.val, options);
+		if (typeof prop.key === "symbol") throw new TypeError("Cannot convert a symbol to a string");
+		const key = String(prop.key);
+		const propertySchema = emit(prop.val, ctx);
 		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);
+		properties[key] = propertySchema;
+		if (filled(prop)) required.push(key);
 	}
 	const schema: JsonSchema = { type: "object", properties };
 	if (required.length > 0) schema.required = required;
-	if (index !== undefined) schema.additionalProperties = emit(index, options);
+	if (index !== undefined) schema.additionalProperties = emit(index, ctx);
 	else if (extras === "reject") schema.additionalProperties = false;
 	return schema;
 }

package/src/keywords.ts

@@ -1,6 +1,6 @@
 import type { IR, MorphContext } from "./ir";
 
-const NUMERIC = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+const NUMERIC = /^(?:(?!^-0\.?0*$)(?:-?(?:(?:0|[1-9]\d*)(?:\.\d+)?)|\.\d+?))$/;
 const INTEGER = /^[+-]?(?:0|[1-9]\d*)$/;
 const EMAIL = /^[\w%+.-]+@[\d.A-Za-z-]+\.[A-Za-z]{2,}$/;
 const SEMVER =
@@ -106,8 +106,118 @@ function isLuhnValid(input: string): boolean {
 	return value.length > 0 && sum % 10 === 0;
 }
 
+function finiteNumber(expected = "a number"): IR {
+	return {
+		k: "refine",
+		base: { k: "unknown" },
+		pred: value => typeof value === "number" && !Number.isNaN(value),
+		expected,
+	};
+}
+
+function jsonObject(): IR {
+	let value: IR;
+	const resolveValue = (): IR => value;
+	const object: IR = {
+		k: "object",
+		props: [],
+		index: { k: "alias", name: "$jsonValue", resolve: resolveValue },
+		extras: "keep",
+	};
+	const array: IR = {
+		k: "array",
+		el: { k: "alias", name: "$jsonValue", resolve: resolveValue },
+		desc: "an object",
+	};
+	value = {
+		k: "union",
+		members: [
+			object,
+			array,
+			{ k: "number" },
+			{ k: "string" },
+			{ k: "lit", v: false },
+			{ k: "null" },
+			{ k: "lit", v: true },
+		],
+	};
+	return object;
+}
+
+function instance(ctor: new (...args: never[]) => object, name: string): IR {
+	return { k: "instance", ctor, expected: `${/^[AEIOU]/.test(name) ? "an" : "a"} ${name} instance` };
+}
+
 const keywordFactories: Record<string, () => IR> = {
 	string: () => ({ k: "string" }),
+	Key: () => ({ k: "union", members: [{ k: "string" }, { k: "symbol" }] }),
+	"unknown.any": () => ({ k: "unknown" }),
+	Array: () => ({ k: "array", el: { k: "unknown" } }),
+	Function: () => instance(Function as unknown as new (...args: never[]) => object, "Function"),
+	RegExp: () => instance(RegExp, "RegExp"),
+	File: () => instance(File, "File"),
+	Error: () => instance(Error, "Error"),
+	Set: () => instance(Set, "Set"),
+	Map: () => instance(Map, "Map"),
+	WeakSet: () => instance(WeakSet, "WeakSet"),
+	WeakMap: () => instance(WeakMap, "WeakMap"),
+	Promise: () => instance(Promise, "Promise"),
+	FormData: () => instance(FormData, "FormData"),
+	"FormData.parse": () => ({
+		k: "morph",
+		input: instance(FormData, "FormData"),
+		fn: value => {
+			const out: Record<string, Bun.FormDataEntryValue | Bun.FormDataEntryValue[]> = {};
+			for (const [key, entry] of (value as FormData).entries()) {
+				const current = out[key];
+				out[key] = current === undefined ? entry : Array.isArray(current) ? [...current, entry] : [current, entry];
+			}
+			return out;
+		},
+		out: { k: "object", props: [], index: { k: "unknown" }, extras: "keep" },
+	}),
+	"object.json": jsonObject,
+	"object.json.stringify": () => ({
+		k: "morph",
+		input: jsonObject(),
+		fn: value => JSON.stringify(value),
+		out: { k: "string" },
+	}),
+	"number.epoch": () => ({
+		k: "refine",
+		base: {
+			k: "refine",
+			base: {
+				k: "refine",
+				base: finiteNumber("a number representing a Unix timestamp"),
+				pred: value => Number.isInteger(value),
+				expected: "an integer representing a Unix timestamp",
+			},
+			pred: value => (value as number) >= -8_640_000_000_000_000,
+			expected: "a Unix timestamp after -8640000000000000",
+		},
+		pred: value => (value as number) <= 8_640_000_000_000_000,
+		expected: "a Unix timestamp before 8640000000000000",
+	}),
+	"number.safe": () => ({
+		k: "refine",
+		base: {
+			k: "refine",
+			base: finiteNumber(),
+			pred: value => (value as number) >= Number.MIN_SAFE_INTEGER,
+			expected: `at least ${Number.MIN_SAFE_INTEGER}`,
+		},
+		pred: value => (value as number) <= Number.MAX_SAFE_INTEGER,
+		expected: `at most ${Number.MAX_SAFE_INTEGER}`,
+	}),
+	"number.NaN": () => ({
+		k: "refine",
+		base: { k: "unknown" },
+		pred: Number.isNaN,
+		expected: "NaN",
+	}),
+	"number.Infinity": () => ({ k: "lit", v: Number.POSITIVE_INFINITY }),
+	"number.NegativeInfinity": () => ({ k: "lit", v: Number.NEGATIVE_INFINITY }),
 	"string.alpha": () => pattern(/^[A-Za-z]*$/, "only letters"),
 	"string.alphanumeric": () => pattern(/^[\dA-Za-z]*$/, "only letters and digits 0-9"),
 	"string.hex": () => pattern(/^[\dA-Fa-f]+$/, "hex characters only"),