Introduction to Zod

I was first introduced to Zod by Adam Bobrow - a colleague of mine and a dear friend. Adam was sick and tired from JavaScript's brittleness, and about two years ago he started migrating our code base to TypeScript. But that wasn't enough for him. He kept complaining: "What good are my types, if some other service decides to send me bad data and breaks my code?". That's when he discovered Zod.

At first I thought: "Yah yah, yet another input validation library. We already use Joi." 5 minutes later I was convinced. Zod was not yet another input validation library. It does something extra, but very important, that other libraries don't do - it infers types out of schemas 🪄 .

The purpose of this series is to walk you through using Zod from the very basics to plugging it into every I/O operations your system does - making it de-facto strongly typed.

What is Zod?

Zod is a TypeScript library used for creating schemas to validate data types. It helps ensure that the data our program receives or works with matches the expected format, like checking if a variable is a number, a string, or a more complex object with specific properties. Zod is particularly useful because it's designed with TypeScript's type system in mind. It allows developers to define schemas that not only validate the shape and type of data at runtime but also automatically infer TypeScript types from these schemas.

Let's look at a basic example:

import { z } from 'zod';

// Define a schema for the user
const UserSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
});

// Create a user data object to validate
const userData = {
  name: 'John Doe',
  age: 30,
  email: 'john.doe@example.com',
};

// Validate the user data against the schema
const validationResult = UserSchema.safeParse(userData);

if (validationResult.success) {
  console.log('Validation succeeded:', validationResult.data);
} else {
  console.log('Validation failed:', validationResult.error);
}

The above example is not very exciting since it's not that different from what we could do with other validation libraries. To make it interesting, let's add some type inference to the mix.

import { z } from 'zod';

// Define a schema for the user
const UserSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
});

// This is where the magic happens..
type User = z.infer<typeof UserSchema>;

// Create a user data object to validate
const userData = {
  name: 'John Doe',
  age: 30,
  email: 'john.doe@example.com',
};

// Validate the user data against the schema
const user: User = UserSchema.parse(userData);

Notice how Zod automatically inferred the type User out of UserSchema. Why is that a big deal? Because it creates a single source of truth for all our types and enforces any external input to conform to that source of truth. Other schema validation libraries will force us to manually define types and keep those types in sync with our schemas. Here's an example of how we would do it with Joi:

import * as Joi from 'joi';

// Define a schema for the user with Joi
const UserSchema = Joi.object({
  name: Joi.string().required(),
  age: Joi.number().required(),
  email: Joi.string().email().required(),
});

type User = {
  name: string;
  age: number;
  email: string;
};

// Create a user data object to validate
const userData = {
  name: 'John Doe',
  age: 30,
  email: 'john.doe@example.com',
};

// Validate the user data against the schema
const { value } = UserSchema.validate(userData);

// Cast value to User
const user: User = value;

One clear difference is that we had to define the User type ourselves in addition to the schema. Unfortunately that also means that changing the schema does not force us to change the type or vice versa. So let's assume that we've added the address property to User but haven't changed the schema:

type User = {
  name: string;
  age: number;
  email: string;
  address: string; // <- new property
};

Our original code will continue to compile but the following code will fail in runtime:

const userData = {
  name: 'John Doe',
  age: 30,
  email: 'john.doe@example.com',
};

const { value } = UserSchema.validate(userData); // <- validation passes
const user: User = value;

console.log(user.address.toUpperCase()); // <- but this line fail miserably

With Zod, to change the type we would need to change the schema (single source of truth), ensuring that any bad input is validated before we reach any significant business logic.

Next in our series, we'll use Zod to validate input from HTTP requests.