zod

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 strict mode 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