RFC/Feature Request: Add a type-safe convert/input output mapper method for compile time input validation

[oberbeck]

RFC/Feature Request: Add a type-safe convert/input output mapper method for compile time input validation

Summary

Introduce a new method, ie. convert, for Zod schemas that provides type-safe input validation and transformation. This method would enforce that the provided input matches the schema’s defined input type (T["_input"]) at compile time, ensuring a stricter contract compared to parse.

Motivation

Zod’s parse and safeParse methods currently accept unknown as input. While this is intentional for unstructured or untrusted data validation, there are common use cases where input data is already structured (e.g., from a typed API response, database query, or other controlled sources). For such cases, allowing type-safe input validation without relying on runtime type checking enhances both safety and developer experience.

The proposed method aligns with Zod’s TypeScript-first philosophy by:

1. Enforcing input types at compile time, reducing reliance on runtime checks.
2. Providing a clear distinction between structured and unstructured input handling.
3. Supporting scenarios where transformations (via .transform()) are applied, while maintaining type safety.

Proposed API

Add a method convert to Zod schemas with the following behavior:

schema.convert(input: T["_input"]): T["_output"];

• Input Type (T["_input"]): Enforces that the input matches the schema's input type at compile time.

• Output Type (T["_output"]): Returns the validated and transformed data, adhering to the schema's transformation logic.

  Example Usage

zod/src/__tests__/convert.test-d.ts

Lines 21 to 59 in dad8820

	test("valid schema conversion", () => {
	const userSchema = z.object({
	id: z.string(),
	name: z.string(),
	age: z.string().transform((age) => parseInt(age, 10)),
	});
	const validInput: z.input<typeof userSchema> = {
	id: "123",
	name: "Alice",
	age: "25",
	};
	const user = userSchema.convert(validInput);
	expectTypeOf(user).toMatchTypeOf<z.infer<typeof userSchema>>();
	});
	test("invalid schema conversion", () => {
	const userSchema = z.object({
	id: z.string(),
	name: z.string(),
	age: z.string().transform((age) => parseInt(age, 10)),
	});
	// Input not matching the schema's input type
	const invalidInput = {
	name: "Alice",
	age: "25",
	};
	expectTypeOf(numberToString.convert)
	.parameter(0)
	.not.toMatchTypeOf<typeof invalidInput>();
	try {
	// @ts-expect-error - compile error
	userSchema.convert(invalidInput);
	} catch {}
	});

Comparison with Existing Methods

1. parse:

   • Accepts unknown input and validates it.
   • Use case: General-purpose validation of unstructured data.

2. convert (Proposed):

   • Enforces that the input matches the schema’s input type at compile time.
   • Use case:
     • Validating already-structured data with guaranteed input types, while benefiting from transformations and Zod’s validation.
     • Using zod as typesafe converter ie. between well defined input and output types.

Potential Concerns

• Confusion with Existing Methods:
  • I am uncertain about how to name the method in order to clearly differentiate itself from parse, safeParse, transform,... to avoid ambiguity. Suggested name: convert, inputToOutput, parseConvert?

Example implementation

#3861

zod/src/types.ts

Lines 521 to 541 in dad8820

	convert(data: Input, params?: Partial<ParseParams>): Output {
	return this.parse(data, params);
	}
	safeConvert(
	data: Input,
	params?: Partial<ParseParams>
	): SafeParseReturnType<Input, Output> {
	return this.safeParse(data, params);
	}
	convertAsync(data: Input, params?: Partial<ParseParams>): Promise<Output> {
	return this.parseAsync(data, params);
	}
	safeConvertAsync(
	data: Input,
	params?: Partial<ParseParams>
	): Promise<SafeParseReturnType<Input, Output>> {
	return this.safeParseAsync(data, params);
	}