Runtime input boundaries
Validate request bodies, configuration, or other untrusted runtime data before application code consumes it.
Zod · Module
.parse
.parse validates an unknown value against a Zod schema. It returns a strongly typed deep clone on success and throws a ZodError on failure.
How it works
Call .parse on a Zod schema with an unknown value. Successful validation returns the schema's typed output as a deep clone; invalid input throws a ZodError, so use try/catch when handling failures.
Syntax
.parse(data: unknown): TParameters
| Name | Type | Description |
|---|---|---|
data | unknown | The value to validate and parse; it may be any runtime value. |
Returns
The schema's strongly typed parsed output, returned as a deep clone when validation succeeds; otherwise .parse throws a ZodError.
Key points
- Invoke
.parseon any Zod schema to perform runtime validation. - Successful parsing returns a strongly typed deep-cloned value.
- Failures provide a
ZodErrorwith detailed issue information through an exception. - Choose
.safeParse()when you want a result object instead of thrown validation errors. - Use the asynchronous counterpart for schemas containing async refinements or transforms.
Common mistakes
- Invalid input raises a
ZodErrorrather than returning a failure object. - Schemas using asynchronous refinements or transforms require
parseAsync().
Example: Validate and parse an object
import { z } from "zod";
const User = z.object({
name: z.string(),
age: z.number().int().nonnegative(),
});
const input: unknown = { name: "Ada", age: 36 };
const user = User.parse(input);
console.log(user.name); // AdaThis validates an unknown value against a schema and returns the parsed, strongly typed result when validation succeeds.
When to use it
Typed data extraction
Convert loosely typed external data into a schema-defined TypeScript value.
Exception-based validation
Fail immediately when invalid data should stop the current operation.
Interview questions
QWhat does Zod's .parse method do?
.parse validates an input against a schema and returns the validated output when successful. The result is strongly typed and is a deep clone of the input; invalid data causes a ZodError to be thrown.
Follow-up: What should be used when validation involves asynchronous behavior? Use .parseAsync() and await its result.
QWhy is .parse useful at a runtime boundary?
The argument is typed as unknown, which reflects that runtime input has not yet been trusted. The return type is the schema's output type, allowing TypeScript to use the validated result safely.
Follow-up: How can a caller avoid exceptions for ordinary validation failures? Use .safeParse(), which returns either parsed data or a ZodError in a result object.
QHow should .parse failures be handled?
A successful call returns parsed data, while a failed call throws a ZodError containing granular validation issues. Therefore, callers that expect invalid input should handle the call with try/catch.
Follow-up: When is .safeParse() preferable? Prefer it when branching on success or failure is clearer than exception handling.
Related
safeParseparseAsyncZodError