TypeScript is useful for checking the types of our variables at the type level.

However, we can't always be sure about what type of variables we'll get from external sources like API endpoints or form inputs.

Zod lets us work around this by checking types at the _runtime_ level as well as the type level, making it a useful library to add to your repertoire.

## A First Look at Runtime Checking

Consider this `toString()` function:

```typescript
export const toString = (num: unknown) => {
  return String(num);
};
```

We're taking in a `num` variable that we've typed as `unknown`.

This means that we can call `toString()` with anything we want on the type level, including object types or `undefined`:



```typescript
toString('blah')
toString(undefined)
toString({name: 'Matt'})
```

For now all of these would work, but we want to prevent this at the _runtime_ level.

If we call `toString()` with a string, we want it to throw an error and say that it expected a number but received a string:



```typescript
it("Should throw a runtime error when called with not a number", () => {
  expect(() => toString("123")).toThrowError(
    "Expected number, received string",
  );
});
```

If we pass in a number, `toString()` should work as expected:

```typescript
it("Should return a string when called with a number", () => {
  expect(toString(1)).toBeTypeOf("string");
});
```

## Challenge

Inside of `01-number.problem.ts`, use Zod to update the tests to make them pass.

Run `yarn e 01` to check your work.

**Hint:** Check the Zod docs for <a href="https://zod.dev/?id=parse" target="_blank" rel="noopener">.parse</a> and <a href="https://zod.dev/?id=numbers" target="_blank" rel="noopener">Numbers</a>

## Create a `numberParser`

Parsers are one of the most basic features of Zod.

To start our solution, we'll create a `numberParser` by invoking `z.number()`.

This creates something called `z.ZodNumber` that provides several helpful methods.

```typescript
const numberParser = z.number();
```

Passing data into `numberParser.parse()` will error if it's not a number.

This means that any variable we create by calling `numberParser.parse()` will be typed as a number, and our tests pass!

Here's our updated `toString` function after adding in `numberParser`:



```typescript
const numberParser = z.number();

export const toString = (num: unknown) => {
  const parsed = numberParser.parse(num);
  return String(parsed);
};
```

## Experiment with Different Types

Zod allows us to use this same technique with other types as well.

For example, if we wanted to accept a boolean instead, then we could update our `numberParser` to be `z.boolean()`.

Now our tests will fail because they expected a number but got a Boolean.

This technique with Zod gives us a solid base to build up from. As we proceed, you'll find that Zod mimics a lot of what you're used to in TypeScript.

Check out the full list of primitives <a href="https://zod.dev/?id=primitives" target="_blank" rel="noopener">in the Zod docs</a>.

Update the toString Function

The solution here is to use the very, very basic stuff that Zod gives you, which is, first of all, we're going to create a numberParser. This numberParser is going to be invoked from `z.number`. This creates something called `z.ZodNumber`.

0:16 We can use numberParser in a bunch of ways. We can go .parse. We can pass in some random data. It will error if it's not a number. Anything that we return from this, as you can see,` numberParser.parse(num),` this is now typed as a number. If we wanted to accept a Boolean instead, then we would go z.boolean. Now this would be typed as a Boolean.

0:38 Importantly, it's now erroring correctly. It's expecting a number but received a string, when this is called. Here, if we instead change it to be a Boolean, then this will error, but it's going to error in the wrong way, "Expected boolean, received number." Rather, that's on the one down there.

0:57 These really basic elements of Zod here, like z.string, z.boolean, z.number, these are really, really important primitives because they allow you to build up from a solid base.

1:10 They represent the basic elements of TypeScript too. You've got Boolean. You've got string. You've got number. You've got bigint and null and undefined. You can even have `z.undefined`, `z.null`. What you'll start to see about Zod is that it mimics a lot of what you're used to in TypeScript with its runtime type system.

Runtime Type Checking with Zod

Matt Pocock: 0:00 Zod is really, really useful at runtime when you want to make sure that a variable or anything, really, is of a certain type. Typescript does this on the type level, but Zod can do it on the runtime level and the type level.

0:15 Here, we've got a `toString` function where we're taking in this num variable which we've typed as unknown. That means we can call `toString` with anything we want on the type level. We call it with undefined. We can call it with an object.

0:30 What we want to do here is we want to actually prevent that at the runtime level. We want to say if you call it with a string, you want to say expected number and received string. We want it to throw an error.

0:42 We do want it to work when you pass it a number. This mimics a lot of situations that Zod is really, really helpful for. When you have a variable that you just don't know quite what type it is. You need to make sure it's a certain type.

0:56 A great example might be a form input or something coming from an external source, like an API endpoint or something. Your challenge is to somehow use Zod to make sure that these tests pass because if we run `yarn e 01`, then this is not going to parse unknown because this test is failing because it's not erroring in right way.

TypeScript is great for checking variables at the type level.

For example, you can specify that the `age` property for a `User` should be a number.

However, you can’t always be sure what you’re going to get from a form input. TypeScript will present an error if it’s not a number, but on its own it doesn’t know if a number is too low or too high to be realistic for your use case.

There’s a similar problem with third-party API responses.

You can reference documentation to get an idea for what a response includes, but TypeScript can’t tell how to type it. And what happens if you get an error instead?

Zod allows you to work around uncertainty by checking types at the _runtime_ level as well at the type level.

In this tutorial, you’ll gain hands-on practice with Zod by working through a series of exercises that demonstrate how useful runtime checking is.

## **What is Zod?**

Zod ([github](https://github.com/colinhacks/zod#introduction)) is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple **`string`** to a complex nested object.

Zod is designed to be as developer-friendly as possible. The goal is to eliminate duplicative type declarations. With Zod, you declare a validator _once_ and Zod will automatically infer the static TypeScript type. It's easy to compose simpler types into complex data structures.

## **Instructions**

This tutorial is a set of problem exercises for you to work through. Each exercise has a short video that presents the problem along with a code editor to solve the problem in the browser.

You'll know you've solved the exercise when the tests pass.

This Zod tutorial encourages **active, exploratory learning**. In each exercise, I'll explain a problem, and **you'll be asked to try to find a solution**.

To attempt a solution, you'll need to:

1. Look for any 🕵️‍♂️ emojis to give you a hint on what to change
2. Check out <a href="https://github.com/colinhacks/zod" target="_blank" rel="noopener">Zod's docs</a>
3. Try to find something that looks relevant.
4. Give it a go to see if it solves the problem.

You'll know if you've succeeded because the tests will pass.

**If you succeed**, or **if you get stuck**, watch the solution video and check out the **`*.solution.ts`**.

You can see if your solution is better or worse than mine!

### **Prerequisites**

You'll need a working understanding of JavaScript, but even if you are new to TypeScript this tutorial is for you.

### **Running the Exercises Locally**

You'll want to have an understanding of git to clone the repository, basic node and npm (yarn) , as well as TypeScript itself to work through this tutorial.

If you want to save your work or work in a different environment, you can also [clone the git repository](https://github.com/total-typescript/zod-tutorial) and work locally in the editor of your choice. If you [follow this link to use gitpod](https://gitpod.io/#https://github.com/total-typescript/zod-tutorial), you can work in a full VS Code coding environment running in your browser.

Follow the instructions in the [README](https://github.com/total-typescript/zod-tutorial/blob/main/README.md) to get the exercises running.

Zod is a TypeScript-first schema declaration and validation library. In this tutorial, Matt Pocock has prepared a set of exercises that will help you level up.

Transcript

Runtime Type Checking with Zod

Transcript