@oh-my-pi/omptype 17.2.6 → 17.2.8

package/src/json-schema.ts

@@ -2,24 +2,92 @@ import type { IR, PropIR } from "./ir";
 
 export interface JsonSchemaOptions {
 	description?: string;
+	target?: 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>;
 
-/** Emit the draft-2020-12 JSON Schema represented by an IR tree. */
+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 {
-	const schema = emit(ir);
+	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 === null ? undefined : (options?.dialect ?? dialectFor(options?.target));
+	if (dialect !== undefined) schema.$schema = dialect;
 	if (options?.description !== undefined) schema.description = options.description;
 	return schema;
 }
 
-function emit(ir: IR): 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 !== undefined && (target.startsWith("http://") || target.startsWith("https://")) ? target : undefined;
+}
+
+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;
+}
+
+function toDraft7(schema: JsonSchema): JsonSchema {
+	const converted: JsonSchema = {};
+	for (const key in schema) {
+		const value = schema[key];
+		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,
+			);
+		} else if (key === "items" && "prefixItems" in schema) {
+			converted.additionalItems =
+				typeof value === "object" && value !== null ? toDraft7(value as JsonSchema) : value;
+		} else if (Array.isArray(value)) {
+			converted[key] = value.map(item =>
+				typeof item === "object" && item !== null ? toDraft7(item as JsonSchema) : item,
+			);
+		} else if (typeof value === "object" && value !== null) {
+			converted[key] = toDraft7(value as JsonSchema);
+		} else {
+			converted[key] = value;
+		}
+	}
+	return converted;
+}
+
+function emit(ir: IR, ctx: EmitCtx): JsonSchema {
 	let schema: JsonSchema;
 	switch (ir.k) {
 		case "unknown":
-		case "undefined":
 			schema = {};
 			break;
+		case "undefined":
+			schema = fallback({}, ctx);
+			break;
 		case "null":
 			schema = { type: "null" };
 			break;
@@ -29,6 +97,12 @@ function emit(ir: IR): JsonSchema {
 		case "bigint":
 			schema = { type: "integer" };
 			break;
+		case "symbol":
+			schema = fallback({}, ctx);
+			break;
+		case "never":
+			schema = { not: {} };
+			break;
 		case "anyobject":
 			schema = { type: "object" };
 			break;
@@ -42,22 +116,81 @@ function emit(ir: IR): JsonSchema {
 			schema = emitLiteral(ir.v);
 			break;
 		case "union":
-			schema = emitUnion(ir.members);
+			schema = emitUnion(ir.members, ctx);
+			break;
+		case "intersection":
+			schema = { allOf: ir.members.map(member => emit(member, ctx)) };
 			break;
 		case "array":
-			schema = { type: "array", items: emit(ir.el) };
+			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, ctx);
+				if (item.hasDefault) {
+					itemSchema.default = item.defFactory && typeof item.def === "function" ? item.def() : item.def;
+				}
+				return itemSchema;
+			});
+			const required = ir.prefix.reduce(
+				(count, item) => count + (item.opt || item.hasDefault ? 0 : 1),
+				ir.postfix.length,
+			);
+			schema = { type: "array", prefixItems, minItems: required };
+			if (ir.variadic === undefined) {
+				schema.items = false;
+			} else {
+				schema.items = emit(ir.variadic, ctx);
+			}
+			break;
+		}
 		case "object":
-			schema = emitObject(ir.props, ir.index, ir.extras);
+			schema = emitObject(ir.props, ir.index, ir.extras, ctx);
 			break;
+		case "instance":
+			schema = ir.ctor === Date ? { type: "string", format: "date-time" } : fallback({ type: "object" }, ctx);
+			break;
+		case "refine":
+			schema = emit(ir.base, ctx);
+			if (ir.json !== undefined) Object.assign(schema, ir.json);
+			break;
+		case "morph":
+			schema = ctx.options?.io === "input" ? emit(ir.input, ctx) : fallback(emit(ir.out ?? ir.input, ctx), ctx);
+			break;
+		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 = emit(ir.schema.ir);
-			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;
 }
 
@@ -73,10 +206,12 @@ 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;
+	if (ir.divisor !== undefined) schema.multipleOf = ir.divisor;
 	return schema;
 }
 
 function emitLiteral(value: unknown): JsonSchema {
+	if (value instanceof Date) return { type: "string", format: "date-time", const: value.toISOString() };
 	if (isJsonValue(value)) return { const: value };
 	switch (typeof value) {
 		case "string":
@@ -94,10 +229,10 @@ function emitLiteral(value: unknown): JsonSchema {
 	}
 }
 
-function emitUnion(members: IR[]): 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]);
+	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 };
@@ -105,7 +240,7 @@ function emitUnion(members: IR[]): JsonSchema {
 		if (scalarType !== undefined) schema.type = scalarType;
 		return schema;
 	}
-	return { anyOf: defined.map(emit) };
+	return { anyOf: defined.map(member => emit(member, ctx)) };
 }
 
 function homogeneousScalarType(values: unknown[]): string | undefined {
@@ -129,23 +264,31 @@ function jsonScalarType(value: unknown): string | undefined {
 	}
 }
 
-function emitObject(props: PropIR[], index: IR | undefined, extras: "keep" | "reject" | "delete"): JsonSchema {
+function emitObject(
+	props: PropIR[],
+	index: IR | undefined,
+	extras: "keep" | "reject" | "delete",
+	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);
+		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);
+	if (index !== undefined) schema.additionalProperties = emit(index, ctx);
 	else if (extras === "reject") schema.additionalProperties = false;
 	return schema;
 }

package/src/keywords.ts

@@ -0,0 +1,380 @@
+import type { IR, MorphContext } from "./ir";
+
+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 =
+	/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*))*))?(?:\+([\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*))?$/;
+const UUID = /^[\da-f]{8}-[\da-f]{4}-[1-8][\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}$/i;
+const IPV4_SEGMENT = "(?:[0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])";
+const IPV4_ADDRESS = `(?:${IPV4_SEGMENT}[.]){3}${IPV4_SEGMENT}`;
+const IPV4 = new RegExp(`^${IPV4_ADDRESS}$`);
+const IPV6_SEGMENT = "(?:[0-9a-fA-F]{1,4})";
+const IPV6 = new RegExp(
+	"^(" +
+		`(?:${IPV6_SEGMENT}:){7}(?:${IPV6_SEGMENT}|:)|` +
+		`(?:${IPV6_SEGMENT}:){6}(?:${IPV4_ADDRESS}|:${IPV6_SEGMENT}|:)|` +
+		`(?:${IPV6_SEGMENT}:){5}(?::${IPV4_ADDRESS}|(:${IPV6_SEGMENT}){1,2}|:)|` +
+		`(?:${IPV6_SEGMENT}:){4}(?:(:${IPV6_SEGMENT}){0,1}:${IPV4_ADDRESS}|(:${IPV6_SEGMENT}){1,3}|:)|` +
+		`(?:${IPV6_SEGMENT}:){3}(?:(:${IPV6_SEGMENT}){0,2}:${IPV4_ADDRESS}|(:${IPV6_SEGMENT}){1,4}|:)|` +
+		`(?:${IPV6_SEGMENT}:){2}(?:(:${IPV6_SEGMENT}){0,3}:${IPV4_ADDRESS}|(:${IPV6_SEGMENT}){1,5}|:)|` +
+		`(?:${IPV6_SEGMENT}:){1}(?:(:${IPV6_SEGMENT}){0,4}:${IPV4_ADDRESS}|(:${IPV6_SEGMENT}){1,6}|:)|` +
+		`(?::((?::${IPV6_SEGMENT}){0,5}:${IPV4_ADDRESS}|(?::${IPV6_SEGMENT}){1,7}|:))` +
+		")(?:%[\\d.A-Za-z]{1,})?$",
+);
+const ISO_DATE =
+	/^([+-]?\d{4}(?!\d{2}\b))((-?)((0[1-9]|1[0-2])(\3([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-3])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6])))(T((([01]\d|2[0-3])((:?)[0-5]\d)?|24:?00)([,.]\d+(?!:))?)?(\17[0-5]\d([,.]\d+)?)?([Zz]|([+-])([01]\d|2[0-3]):?([0-5]\d)?)?)?)?$/;
+
+function pattern(regex: RegExp, expected: string, format?: string): IR {
+	return {
+		k: "refine",
+		base: { k: "string" },
+		pred: value => {
+			regex.lastIndex = 0;
+			return regex.test(value as string);
+		},
+		expected,
+		json: format === undefined ? { pattern: regex.source } : { pattern: regex.source, format },
+	};
+}
+
+function morph(input: IR, fn: (value: string, context: MorphContext) => unknown, out?: IR): IR {
+	return { k: "morph", input, fn: (value, context) => fn(value as string, context), out };
+}
+
+function parsableJson(): IR {
+	return {
+		k: "refine",
+		base: { k: "string" },
+		pred: value => {
+			try {
+				JSON.parse(value as string);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		expected: "a JSON string",
+		json: { contentMediaType: "application/json" },
+	};
+}
+
+function parsableDate(expected = "a parsable date"): IR {
+	return {
+		k: "refine",
+		base: { k: "string" },
+		pred: value => !Number.isNaN(new Date(value as string).valueOf()),
+		expected,
+		json: { format: "date-time" },
+	};
+}
+
+function normalize(form: "NFC" | "NFD" | "NFKC" | "NFKD"): IR {
+	return morph({ k: "string" }, value => value.normalize(form), patternForNormalized(form));
+}
+
+function patternForNormalized(form: "NFC" | "NFD" | "NFKC" | "NFKD"): IR {
+	return {
+		k: "refine",
+		base: { k: "string" },
+		pred: value => (value as string).normalize(form) === value,
+		expected: `${form}-normalized unicode`,
+	};
+}
+
+function uuidVersion(version: string): IR {
+	return pattern(
+		new RegExp(`^[\\da-f]{8}-[\\da-f]{4}-${version}[\\da-f]{3}-[89ab][\\da-f]{3}-[\\da-f]{12}$`, "i"),
+		`a UUIDv${version}`,
+		"uuid",
+	);
+}
+
+function isLuhnValid(input: string): boolean {
+	const value = input.replace(/[ -]+/g, "");
+	let sum = 0;
+	let double = false;
+	for (let index = value.length - 1; index >= 0; index--) {
+		let digit = Number(value[index]);
+		if (double) {
+			digit *= 2;
+			if (digit > 9) digit -= 9;
+		}
+		sum += digit;
+		double = !double;
+	}
+	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"),
+	"string.base64": () => pattern(/^(?:[\d+/A-Za-z]{4})*(?:[\d+/A-Za-z]{2}==|[\d+/A-Za-z]{3}=)?$/, "base64-encoded"),
+	"string.base64.url": () =>
+		pattern(/^(?:[\w-]{4})*(?:[\w-]{2}(?:==|%3D%3D)?|[\w-]{3}(?:=|%3D)?)?$/, "base64url-encoded"),
+	"string.capitalize": () => morph({ k: "string" }, value => value.charAt(0).toUpperCase() + value.slice(1)),
+	"string.capitalize.preformatted": () => pattern(/^[A-Z].*$/, "capitalized"),
+	"string.creditCard": () => ({
+		k: "refine",
+		base: pattern(
+			/^(?:4\d{12}(?:\d{3,6})?|5[1-5]\d{14}|3[47]\d{13}|6(?:011|5\d\d)\d{12,15})$/,
+			"a credit card number",
+		),
+		pred: value => isLuhnValid(value as string),
+		expected: "a credit card number",
+	}),
+	"string.date": () => parsableDate(),
+	"string.date.parse": () =>
+		morph(parsableDate(), value => new Date(value), { k: "instance", ctor: Date, expected: "a Date" }),
+	"string.date.iso": () => pattern(ISO_DATE, "an ISO 8601 date", "date-time"),
+	"string.date.iso.parse": () =>
+		morph(pattern(ISO_DATE, "an ISO 8601 date", "date-time"), value => new Date(value), {
+			k: "instance",
+			ctor: Date,
+			expected: "a Date",
+		}),
+	"string.date.epoch": () => pattern(INTEGER, "an integer string representing a Unix timestamp"),
+	"string.date.epoch.parse": () =>
+		morph(pattern(INTEGER, "an integer string representing a Unix timestamp"), value => new Date(Number(value)), {
+			k: "instance",
+			ctor: Date,
+			expected: "a Date",
+		}),
+	"string.digits": () => pattern(/^\d*$/, "only digits 0-9"),
+	"string.email": () => pattern(EMAIL, "an email address", "email"),
+	"string.integer": () => pattern(INTEGER, "a well-formed integer string"),
+	"string.integer.parse": () =>
+		morph(
+			pattern(INTEGER, "a well-formed integer string"),
+			(value, context) => {
+				const parsed = Number.parseInt(value, 10);
+				return Number.isSafeInteger(parsed) ? parsed : context.error("a safe integer string");
+			},
+			{ k: "number", int: true },
+		),
+	"string.ip": () => ({
+		k: "union",
+		members: [pattern(IPV4, "an IPv4 address", "ipv4"), pattern(IPV6, "an IPv6 address", "ipv6")],
+	}),
+	"string.ip.v4": () => pattern(IPV4, "an IPv4 address", "ipv4"),
+	"string.ip.v6": () => pattern(IPV6, "an IPv6 address", "ipv6"),
+	"string.json": () => parsableJson(),
+	"string.json.parse": () =>
+		morph(parsableJson(), (value, context) => {
+			try {
+				return JSON.parse(value);
+			} catch {
+				return context.error("a JSON string");
+			}
+		}),
+	"string.lower": () => morph({ k: "string" }, value => value.toLowerCase()),
+	"string.lower.preformatted": () => pattern(/^[a-z]*$/, "only lowercase letters"),
+	"string.normalize": () => normalize("NFC"),
+	"string.normalize.NFC": () => normalize("NFC"),
+	"string.normalize.NFC.preformatted": () => patternForNormalized("NFC"),
+	"string.normalize.NFD": () => normalize("NFD"),
+	"string.normalize.NFD.preformatted": () => patternForNormalized("NFD"),
+	"string.normalize.NFKC": () => normalize("NFKC"),
+	"string.normalize.NFKC.preformatted": () => patternForNormalized("NFKC"),
+	"string.normalize.NFKD": () => normalize("NFKD"),
+	"string.normalize.NFKD.preformatted": () => patternForNormalized("NFKD"),
+	"string.numeric": () => pattern(NUMERIC, "a well-formed numeric string"),
+	"string.numeric.parse": () =>
+		morph(pattern(NUMERIC, "a well-formed numeric string"), value => Number.parseFloat(value), { k: "number" }),
+	"string.regex": () => ({
+		k: "refine",
+		base: { k: "string" },
+		pred: value => {
+			try {
+				new RegExp(value as string);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		expected: "a regex pattern",
+		json: { format: "regex" },
+	}),
+	"string.semver": () => pattern(SEMVER, "a semantic version"),
+	"string.trim": () => morph({ k: "string" }, value => value.trim()),
+	"string.trim.preformatted": () => pattern(/^\S.*\S$|^\S?$/, "trimmed"),
+	"string.upper": () => morph({ k: "string" }, value => value.toUpperCase()),
+	"string.upper.preformatted": () => pattern(/^[A-Z]*$/, "only uppercase letters"),
+	"string.url": () => ({ k: "string", url: true }),
+	"string.url.parse": () =>
+		morph({ k: "string", url: true }, value => new URL(value), { k: "instance", ctor: URL, expected: "a URL" }),
+	"string.uuid": () => pattern(UUID, "a UUID", "uuid"),
+	"string.uuid.v1": () => uuidVersion("1"),
+	"string.uuid.v2": () => uuidVersion("2"),
+	"string.uuid.v3": () => uuidVersion("3"),
+	"string.uuid.v4": () => uuidVersion("4"),
+	"string.uuid.v5": () => uuidVersion("5"),
+	"string.uuid.v6": () => uuidVersion("6"),
+	"string.uuid.v7": () => uuidVersion("7"),
+	"string.uuid.v8": () => uuidVersion("8"),
+	"parse.number": () =>
+		morph(pattern(NUMERIC, "a well-formed numeric string"), value => Number.parseFloat(value), { k: "number" }),
+	"parse.integer": () =>
+		morph(pattern(INTEGER, "a well-formed integer string"), value => Number.parseInt(value, 10), {
+			k: "number",
+			int: true,
+		}),
+	"parse.json": () => keywordFactories["string.json.parse"](),
+	"parse.date": () => keywordFactories["string.date.parse"](),
+	"parse.url": () => keywordFactories["string.url.parse"](),
+	"parse.boolean": () =>
+		morph(pattern(/^(?:true|false)$/, "a boolean string"), value => value === "true", { k: "boolean" }),
+	"parse.bigint": () => morph(pattern(INTEGER, "an integer string"), value => BigInt(value), { k: "bigint" }),
+};
+
+/** Lower a built-in keyword into fresh validation IR. */
+export function keywordIR(name: string): IR | undefined {
+	return keywordFactories[name]?.();
+}
+
+/** Lower a regular expression into a string refinement. */
+export function patternIR(regex: RegExp): IR {
+	return pattern(regex, `a string matching ${regex}`);
+}
+
+/** Lower an ArkType-style template literal into a string pattern. */
+export function templateIR(source: string): IR {
+	let patternSource = "^";
+	let index = 0;
+	const placeholder = /\$\{(string|number|bigint|boolean)\}/g;
+	for (let match = placeholder.exec(source); match; match = placeholder.exec(source)) {
+		patternSource += escapeRegex(source.slice(index, match.index));
+		switch (match[1]) {
+			case "number":
+				patternSource += "[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)";
+				break;
+			case "bigint":
+				patternSource += "[+-]?\\d+";
+				break;
+			case "boolean":
+				patternSource += "(?:true|false)";
+				break;
+			default:
+				patternSource += ".*";
+		}
+		index = match.index + match[0].length;
+	}
+	patternSource += `${escapeRegex(source.slice(index))}$`;
+	return pattern(new RegExp(patternSource), `a string matching \`${source}\``);
+}
+
+function escapeRegex(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}