tomevault-io Zod Schema Validation
TypeScript-first schema declaration and validation library with static type inference.
Why Zod
- Zero dependencies, 2kb gzipped
- Works in Node.js and browsers
- Immutable API - methods return new instances
- Static type inference - no redundant type declarations
- JSON Schema conversion built-in
Requirements
- TypeScript v5.5+
- Enable
strictmode in tsconfig.json
Core Concepts
Schema Definition
Always define schemas before validation:
import { z } from "zod";
// Object schema
const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
age: z.number().int().positive(),
role: z.enum(["admin", "user", "guest"]),
});
// Infer TypeScript type from schema
type User = z.infer<typeof UserSchema>;
Parsing Methods
.parse() - Throws ZodError on failure:
try {
const user = UserSchema.parse(data);
// user is typed as User
} catch (e) {
if (e instanceof z.ZodError) {
console.error(e.issues);
}
}
.safeParse() - Returns discriminated union (preferred):
const result = UserSchema.safeParse(data);
if (result.success) {
console.log(result.data); // typed User
} else {
console.error(result.error.issues);
}
Async variants - Required for async refinements/transforms:
await UserSchema.parseAsync(data);
await UserSchema.safeParseAsync(data);
Primitive Types
// Basic primitives
z.string()
z.number()
z.bigint()
z.boolean()
z.date()
z.symbol()
z.undefined()
z.null()
z.void()
z.any()
z.unknown()
z.never()
// Coercion - converts input to target type
z.coerce.string() // String(input)
z.coerce.number() // Number(input)
z.coerce.boolean() // Boolean(input)
z.coerce.bigint() // BigInt(input)
z.coerce.date() // new Date(input)
String Validations
z.string()
.min(1) // Minimum length
.max(255) // Maximum length
.length(10) // Exact length
.email() // Email format
.url() // URL format
.uuid() // UUID format
.cuid() // CUID format
.regex(/pattern/) // Custom regex
.startsWith("prefix")
.endsWith("suffix")
.includes("substring")
.trim() // Transform: trim whitespace
.toLowerCase() // Transform: lowercase
.toUpperCase() // Transform: uppercase
Number Validations
z.number()
.int() // Integer only
.positive() // > 0
.nonnegative() // >= 0
.negative() // < 0
.nonpositive() // <= 0
.gt(5) // > 5
.gte(5) // >= 5 (alias: .min())
.lt(10) // < 10
.lte(10) // <= 10 (alias: .max())
.multipleOf(5) // Divisible by 5
.finite() // Excludes Infinity
.safe() // Safe integer range
Object Schemas
const PersonSchema = z.object({
name: z.string(),
age: z.number(),
});
// Make all properties optional
PersonSchema.partial();
// Make specific properties optional
PersonSchema.partial({ age: true });
// Make all properties required
PersonSchema.required();
// Pick specific properties
PersonSchema.pick({ name: true });
// Omit specific properties
PersonSchema.omit({ age: true });
// Extend with new properties
PersonSchema.extend({
email: z.string().email(),
});
// Strict mode - reject unknown keys
PersonSchema.strict();
// Passthrough - preserve unknown keys
PersonSchema.passthrough();
// Strip unknown keys (default behavior)
PersonSchema.strip();
Arrays and Tuples
// Array of strings
z.array(z.string())
.min(1) // At least 1 element
.max(10) // At most 10 elements
.length(5) // Exactly 5 elements
.nonempty(); // At least 1 element (typed)
// Alternative syntax
z.string().array();
// Tuple with fixed positions
z.tuple([
z.string(), // First element: string
z.number(), // Second element: number
]);
// Tuple with rest elements
z.tuple([z.string(), z.number()]).rest(z.boolean());
Unions and Enums
// Union types
z.union([z.string(), z.number()]);
// Shorthand
z.string().or(z.number());
// Discriminated unions (better error messages)
z.discriminatedUnion("type", [
z.object({ type: z.literal("email"), email: z.string() }),
z.object({ type: z.literal("phone"), phone: z.string() }),
]);
// Enum from array
z.enum(["admin", "user", "guest"]);
// Native enum
enum Role { Admin, User }
z.nativeEnum(Role);
Optional and Nullable
// Optional - allows undefined
z.string().optional(); // string | undefined
// Nullable - allows null
z.string().nullable(); // string | null
// Both
z.string().nullish(); // string | null | undefined
// Default values
z.string().default("anonymous");
z.string().optional().default("anonymous");
// Catch - use default on parse failure
z.string().catch("fallback");
Transforms
// Transform output type
const StringToNumber = z.string().transform((val) => parseInt(val, 10));
type Output = z.output<typeof StringToNumber>; // number
// Chain transforms
z.string()
.trim()
.toLowerCase()
.transform((val) => val.split(","));
// Preprocess input before validation
z.preprocess(
(val) => String(val),
z.string().min(1)
);
Refinements
// Custom validation
z.string().refine(
(val) => val.length <= 255,
{ message: "String must be 255 chars or less" }
);
// Async refinement
z.string().refine(
async (val) => await checkUnique(val),
{ message: "Value must be unique" }
);
// Super refine for complex validations
z.object({
password: z.string(),
confirm: z.string(),
}).superRefine((data, ctx) => {
if (data.password !== data.confirm) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Passwords don't match",
path: ["confirm"],
});
}
});
Error Handling
const result = schema.safeParse(data);
if (!result.success) {
// Access all issues
result.error.issues.forEach((issue) => {
console.log(issue.path); // Field path
console.log(issue.message); // Error message
console.log(issue.code); // Error code
});
// Flatten for form errors
const flat = result.error.flatten();
// { formErrors: string[], fieldErrors: { [key]: string[] } }
// Format for display
const formatted = result.error.format();
// { _errors: string[], field: { _errors: string[] } }
}
Common Patterns
API Request Validation
const CreateUserRequest = z.object({
email: z.string().email(),
password: z.string().min(8),
name: z.string().min(1).max(100),
});
// In Express/Fastify handler
const body = CreateUserRequest.parse(req.body);
Environment Variables
const EnvSchema = z.object({
NODE_ENV: z.enum(["development", "production", "test"]),
PORT: z.coerce.number().default(3000),
DATABASE_URL: z.string().url(),
API_KEY: z.string().min(1),
});
export const env = EnvSchema.parse(process.env);
Form Data
const ContactForm = z.object({
name: z.string().min(1, "Name is required"),
email: z.string().email("Invalid email address"),
message: z.string().min(10, "Message must be at least 10 characters"),
});
// With React Hook Form
const { register, handleSubmit } = useForm({
resolver: zodResolver(ContactForm),
});
API Response
const ApiResponse = z.object({
data: z.array(UserSchema),
pagination: z.object({
page: z.number(),
total: z.number(),
}),
});
const response = await fetch("/api/users");
const json = await response.json();
const validated = ApiResponse.parse(json);
JSON Schema Conversion
import { z } from "zod";
// Zod to JSON Schema
const jsonSchema = z.toJSONSchema(UserSchema);
// JSON Schema to Zod
const zodSchema = z.fromJSONSchema(jsonSchema);
Anti-Patterns
Avoid redundant type declarations
// Bad - duplicates schema
interface User {
name: string;
age: number;
}
const UserSchema = z.object({
name: z.string(),
age: z.number(),
});
// Good - infer from schema
const UserSchema = z.object({
name: z.string(),
age: z.number(),
});
type User = z.infer<typeof UserSchema>;
Use safeParse for user input
// Bad - throws on invalid input
const user = UserSchema.parse(userInput);
// Good - handle errors gracefully
const result = UserSchema.safeParse(userInput);
if (!result.success) {
return { errors: result.error.flatten().fieldErrors };
}
Prefer discriminated unions
// Bad - ambiguous errors
z.union([
z.object({ email: z.string() }),
z.object({ phone: z.string() }),
]);
// Good - clear error messages
z.discriminatedUnion("contactType", [
z.object({ contactType: z.literal("email"), email: z.string() }),
z.object({ contactType: z.literal("phone"), phone: z.string() }),
]);
References
Converted and distributed by TomeVault — claim your Tome and manage your conversions.