@oh-my-pi/omptype 17.2.6

package/src/type.ts

@@ -0,0 +1,329 @@
+/**
+ * The public `type()` parser and `Type` schema surface — an ArkType-compatible
+ * validator with a lazy JIT:
+ *
+ * - calls 1-2 run the tree-walking interpreter (near-zero setup cost, so
+ *   schemas built per-request or validated once stay cheap)
+ * - the third call compiles a specialized validator via `new Function` and
+ *   swaps it in; hot schemas validate in tens of nanoseconds
+ *
+ * A schema is a callable: `schema(data)` returns the (possibly morphed)
+ * output, or an `OmpErrors` on failure (`result instanceof type.errors`).
+ */
+import { compile } from "./compile";
+import { OmpErrors, OmpTypeError, TraversalError } from "./errors";
+import type { InferDef, InferObjectLiteral, InferString } from "./infer";
+import { walk } from "./interp";
+import { type Def, embed, hasMorph, type IR, IR_BRAND, parseDef } from "./ir";
+import { irToJsonSchema } from "./json-schema";
+
+/** Context passed to `.narrow()` / `.pipe()` callbacks. */
+export interface NarrowContext {
+	/** Record `must be <expectation>` and signal failure. */
+	mustBe(expectation: string): false;
+	/** Record a custom problem and signal failure. */
+	reject(problem: string): false;
+}
+
+/** Options accepted by `Type.toJsonSchema` (ArkType-compatible; emission is always draft 2020-12). */
+export interface ToJsonSchemaOptions {
+	target?: string;
+	dialect?: string;
+	fallback?: (ctx: { base: Record<string, unknown> }) => unknown;
+}
+
+interface SchemaInference<out t> {
+	readonly [IR_BRAND]: true;
+	readonly infer: t;
+}
+
+/** A compiled schema: callable validator plus composition methods. */
+export interface Type<out t = unknown> {
+	(data: unknown): t | OmpErrors;
+	readonly [IR_BRAND]: true;
+	/** Structural IR (base type; runtime steps live in `steps`). */
+	readonly ir: IR;
+	/** `.pipe()` / `.narrow()` steps applied after structural validation. */
+	readonly hasSteps: boolean;
+	readonly hasDefault: boolean;
+	readonly defaultValue?: unknown;
+	readonly description?: string;
+	/** Full validate+morph pipeline; identical to calling the schema. */
+	readonly run: (data: unknown) => unknown;
+
+	/** Inference-only output type (no runtime value). */
+	readonly infer: t;
+	/** Inference-only input type (no runtime value). */
+	readonly inferIn: t;
+
+	/** Structural + narrow check without running pipes. */
+	allows(data: unknown): data is t;
+	/** Validate and return output, throwing `TraversalError` on failure. */
+	assert(data: unknown): t;
+	/** JSON Schema (draft 2020-12) for this schema's structural base. */
+	toJsonSchema(options?: ToJsonSchemaOptions): Record<string, unknown>;
+}
+
+/** Schema returned by omptype builders, with precise object-literal composition inference. */
+export interface FluentType<t = unknown> extends Type<t> {
+	describe(description: string): FluentType<t>;
+	default(value: t | (() => t)): FluentType<t>;
+	or<r>(def: SchemaInference<r>): FluentType<t | r>;
+	or<const def extends string>(def: def): FluentType<t | InferString<def>>;
+	or<const def extends Record<string, unknown>>(def: def): FluentType<t | InferObjectLiteral<def>>;
+	or(def: Def): FluentType<unknown>;
+	and<r>(def: SchemaInference<r>): FluentType<t & r>;
+	and<const def extends Record<string, unknown>>(def: def): FluentType<t & InferObjectLiteral<def>>;
+	and(def: Def): FluentType<unknown>;
+	array(): FluentType<t[]>;
+	atLeastLength(bound: number): FluentType<t>;
+	atMostLength(bound: number): FluentType<t>;
+	atLeast(bound: number): FluentType<t>;
+	atMost(bound: number): FluentType<t>;
+	pipe<r>(fn: (data: t, ctx: NarrowContext) => r): FluentType<Exclude<r, OmpErrors>>;
+	narrow<narrowed extends t>(fn: (data: t, ctx: NarrowContext) => data is narrowed): FluentType<narrowed>;
+	narrow(fn: (data: t, ctx: NarrowContext) => boolean): FluentType<t>;
+}
+
+/** Runtime constructor-like value used by ArkType-compatible `instanceof Type` checks. */
+export const Type = Object.defineProperty(function Type(): void {}, Symbol.hasInstance, {
+	value: (value: unknown): boolean =>
+		(typeof value === "function" || (typeof value === "object" && value !== null)) && IR_BRAND in value,
+});
+
+interface Step {
+	kind: "pipe" | "narrow";
+	fn: (data: never, ctx: NarrowContext) => unknown;
+}
+
+interface TypeMeta {
+	description?: string;
+	defaultValue?: unknown;
+	hasDefault?: boolean;
+}
+
+class Ctx implements NarrowContext {
+	expectation: string | undefined;
+
+	mustBe(expectation: string): false {
+		this.expectation = expectation;
+		return false;
+	}
+
+	reject(problem: string): false {
+		this.expectation = problem;
+		return false;
+	}
+}
+
+/** Calls before the JIT compiles a schema (first two run the interpreter). */
+const JIT_THRESHOLD = 3;
+
+function makeType(ir: IR, steps: Step[], meta: TypeMeta): FluentType {
+	let calls = 0;
+	let impl = (data: unknown): unknown => {
+		if (++calls >= JIT_THRESHOLD) {
+			impl = compile(ir);
+			return impl(data);
+		}
+		return walk(ir, data);
+	};
+
+	const runSteps = (data: unknown): unknown => {
+		let out = impl(data);
+		if (out instanceof OmpErrors) return out;
+		for (const step of steps) {
+			const ctx = new Ctx();
+			// steps are typed against the schema's output; validated data satisfies it
+			const fn = step.fn as (data: unknown, ctx: NarrowContext) => unknown;
+			if (step.kind === "narrow") {
+				if (!fn(out, ctx)) return OmpErrors.single([], ctx.expectation ?? "valid (narrow predicate failed)", out);
+			} else {
+				out = fn(out, ctx);
+				if (out instanceof OmpErrors) return out;
+			}
+		}
+		return out;
+	};
+
+	const callable =
+		steps.length === 0 ? (data: unknown): unknown => impl(data) : (data: unknown): unknown => runSteps(data);
+
+	const self = callable as FluentType & {
+		[IR_BRAND]: true;
+		ir: IR;
+		hasSteps: boolean;
+		hasDefault: boolean;
+		defaultValue?: unknown;
+		description?: string;
+		run: (data: unknown) => unknown;
+	};
+	self[IR_BRAND] = true;
+	self.ir = ir;
+	self.hasSteps = steps.length > 0;
+	self.hasDefault = meta.hasDefault === true;
+	self.defaultValue = meta.defaultValue;
+	self.description = meta.description;
+	self.run = callable;
+	// ArkType schema callables deliberately do not expose Function#bind. Generic
+	// tool wrappers use that distinction to bind executable methods while passing
+	// callable parameter schemas through unchanged; exposing bind here would turn
+	// the schema into a bare bound function and strip its schema surface.
+	Object.defineProperty(self, "bind", { value: undefined });
+
+	const methods: Omit<FluentType, keyof typeof self | "infer" | "inferIn" | typeof IR_BRAND> = {
+		describe: (description: string) => makeType({ ...ir, desc: description }, steps, { ...meta, description }),
+		default: (value: unknown) => makeType(ir, steps, { ...meta, defaultValue: value, hasDefault: true }),
+		or: (def: unknown) => {
+			const other = parseDef(def as Def);
+			const a = embed(self);
+			const members = [...(a.k === "union" ? a.members : [a]), ...(other.k === "union" ? other.members : [other])];
+			return makeType({ k: "union", members }, [], {});
+		},
+		and: (def: unknown) => makeType(intersect(embed(self), parseDef(def as Def)), [], {}),
+		array: () => makeType({ k: "array", el: embed(self) }, [], {}),
+		atLeastLength: (bound: number) => makeType(withLengthBound(ir, "min", bound), steps, meta),
+		atMostLength: (bound: number) => makeType(withLengthBound(ir, "max", bound), steps, meta),
+		atLeast: (bound: number) => makeType(withNumericBound(ir, "min", bound), steps, meta),
+		atMost: (bound: number) => makeType(withNumericBound(ir, "max", bound), steps, meta),
+		pipe: (fn: (data: never, ctx: NarrowContext) => unknown) => makeType(ir, [...steps, { kind: "pipe", fn }], meta),
+		narrow: (fn: (data: never, ctx: NarrowContext) => boolean) =>
+			makeType(ir, [...steps, { kind: "narrow", fn }], meta),
+		allows: (data: unknown): boolean => {
+			const out = impl(data);
+			if (out instanceof OmpErrors) return false;
+			for (const step of steps) {
+				if (step.kind !== "narrow") continue;
+				const fn = step.fn as (data: unknown, ctx: NarrowContext) => unknown;
+				if (!fn(out, new Ctx())) return false;
+			}
+			return true;
+		},
+		assert: (data: unknown): unknown => {
+			const out = callable(data);
+			if (out instanceof OmpErrors) throw new TraversalError(out);
+			return out;
+		},
+		toJsonSchema: (_options?: ToJsonSchemaOptions) =>
+			irToJsonSchema(ir, meta.description === undefined ? undefined : { description: meta.description }),
+	} as never;
+	Object.assign(self, methods);
+	return self;
+}
+
+/** Merge two IR nodes for `.and()`; supports the object/object case this repo uses. */
+function intersect(a: IR, b: IR): IR {
+	if (a.k === "object" && b.k === "object") {
+		const props = [...a.props];
+		for (const bp of b.props) {
+			const i = props.findIndex(p => p.key === bp.key);
+			if (i < 0) {
+				props.push(bp);
+			} else {
+				const ap = props[i];
+				props[i] = { ...ap, opt: ap.opt && bp.opt, val: intersect(ap.val, bp.val) };
+			}
+		}
+		const extras =
+			a.extras === "reject" || b.extras === "reject"
+				? "reject"
+				: a.extras === "delete" || b.extras === "delete"
+					? "delete"
+					: "keep";
+		const index = a.index && b.index ? intersect(a.index, b.index) : (a.index ?? b.index);
+		return { k: "object", props, index, extras };
+	}
+	if (a.k === "string" && b.k === "string") {
+		return { k: "string", min: maxOf(a.min, b.min), max: minOf(a.max, b.max), url: a.url || b.url };
+	}
+	if (a.k === "number" && b.k === "number") {
+		return {
+			k: "number",
+			int: a.int || b.int,
+			min: maxOf(a.min, b.min),
+			max: minOf(a.max, b.max),
+			xmin: a.xmin || b.xmin,
+			xmax: a.xmax || b.xmax,
+		};
+	}
+	if (a.k === "unknown") return b;
+	if (b.k === "unknown") return a;
+	if (JSON.stringify(a) === JSON.stringify(b)) return a;
+	throw new OmpTypeError(`unsupported intersection of ${a.k} and ${b.k}`);
+}
+
+function maxOf(a: number | undefined, b: number | undefined): number | undefined {
+	if (a === undefined) return b;
+	if (b === undefined) return a;
+	return Math.max(a, b);
+}
+
+function minOf(a: number | undefined, b: number | undefined): number | undefined {
+	if (a === undefined) return b;
+	if (b === undefined) return a;
+	return Math.min(a, b);
+}
+
+function withLengthBound(ir: IR, side: "min" | "max", bound: number): IR {
+	if (ir.k === "array" || ir.k === "string") {
+		return side === "min" ? { ...ir, min: bound } : { ...ir, max: bound };
+	}
+	throw new OmpTypeError(`cannot apply length bound to ${ir.k}`);
+}
+function withNumericBound(ir: IR, side: "min" | "max", bound: number): IR {
+	if (ir.k === "number") {
+		return side === "min" ? { ...ir, min: bound, xmin: false } : { ...ir, max: bound, xmax: false };
+	}
+	throw new OmpTypeError(`cannot apply numeric bound to ${ir.k}`);
+}
+
+/**
+ * The `type()` builder: parses a definition into a callable schema.
+ *
+ * The `const def` generic drives static inference (`typeof schema.infer`);
+ * the runtime is definition-shape-agnostic, hence the cast.
+ */
+export function type<const def>(def: def): FluentType<InferDef<def>> {
+	return makeType(parseDef(def as Def), [], {}) as unknown as FluentType<InferDef<def>>;
+}
+
+export namespace type {
+	/** Error aggregate returned by failed validations (`result instanceof type.errors`). */
+	export const errors = OmpErrors;
+	export type errors = OmpErrors;
+
+	/** Keyword statics for fluent building, e.g. `type.number.atLeast(5)`. */
+	export const string: FluentType<string> = makeType({ k: "string" }, [], {}) as unknown as FluentType<string>;
+	export const number: FluentType<number> = makeType({ k: "number" }, [], {}) as unknown as FluentType<number>;
+	export const boolean: FluentType<boolean> = makeType({ k: "boolean" }, [], {}) as unknown as FluentType<boolean>;
+	export const unknown: FluentType<unknown> = makeType({ k: "unknown" }, [], {});
+
+	/** Union of literal values from a runtime array (`type.enumerated(...list)`). */
+	export function enumerated<const values extends readonly unknown[]>(...values: values): FluentType<values[number]> {
+		const ir: IR =
+			values.length === 1
+				? { k: "lit", v: values[0] }
+				: { k: "union", members: values.map(v => ({ k: "lit", v }) as IR) };
+		return makeType(ir, [], {}) as unknown as FluentType<values[number]>;
+	}
+
+	/** Untyped builder for runtime-assembled definitions (`type.raw({...})`). */
+	export function raw(def: unknown): BaseType {
+		return makeType(parseDef(def as Def), [], {});
+	}
+}
+
+export interface ScopeOptions {
+	jitless?: boolean;
+}
+
+/** ArkType-compatible scope wrapper; omptype's global builder is already lazy. */
+export function scope(_aliases: Record<string, unknown>, _options?: ScopeOptions): { type: typeof type } {
+	return { type };
+}
+
+/** A schema whose output type is not statically known (`type.raw` results). */
+export type BaseType = FluentType<unknown>;
+
+/** `hasMorph` re-export for diagnostics/tooling. */
+export { hasMorph };