Zod is a Typescript library that allows you to validate the shape and type of your data using various utility functions and statically infer types for it.

It got a lot of hype in the last months, already surpassing millions of downloads on npm.

In this little article, I'm gonna show it to you how you can use the Zod library to validade your api request body input, in this example I'll be using Express, but the concept can be applied to any other framework that you like.

Implementation

To use Zod we first have to import it as such

import { z } from 'zod'

And now we can use it to create a "schema", a Zod schema is a variable that will hold the shape of our data, for example, lets create a basic input for creating a user, that we want to use to validate our user creation before calling our database handler.

export const createUserInput = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
});

As you can see, we are using 4 different types of zod utilities, first we call "object" wich states that the data will come in a object format, and inside of it, we can declare all the object properties, followed by its correspondent types like "string" or "number"

And notice that we also have helpers that can be called after the type function, such as "email" to validate an specific format for given data.

Other validations could also be "optional" and "nullable".

And now, we can use this zod schema to validate our api input, like the example below.

app.post('/createUser', (req: Request, res: Response) => {
  try {
    const data = createUserInput.parse(req.body);

    // send the now validated data to your service / database handler

    return res.send({
      data,
      message: 'Input validated!!',
    });
  } catch (error) {
    if (error instanceof ZodError) {
      return res.send(error);
    }
    return res.status(500).send({
      message: 'unknown error...',
    });
  }
});

The const "data" that returns from the parse function, contains the data of our object already validated and type safe, so you can safely pass it to your database functions and process the data.

If the parse function fails to validate one or more fields, it will throw a "ZodError" wich we will check in a catch block, and send it as a response to the user.

Zod errors have the following shape:

{
    "issues": [
        {
            "validation": "email",
            "code": "invalid_string",
            "message": "Invalid email",
            "path": [
                "email"
            ]
        }
    ],
    "name": "ZodError"
}

In the above example we directly return this error to the client, but in a real situation we could use a parser function to the error, to properly format into a useful message to the front end for example.

Bonus - Static type inference

The cherry on top is that zod schemas also work for type inference, so there is no need for a custom DTO class or anything like that.

So as we create our schema, we can also export a type from it, like so.

export type createUserInputType = z.infer<typeof createUserInput>;

The above example will output the exact type:

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

Docs and references

For more references and documentation about all the zod utilities, checkout their github repo

And also check this working example of the above implementation here

I hope this article was useful for you, feel free to follow me on my socials and GitHub too. Thanks for the reading!