TypeScript-first schema validation with static type inference

This course is aimed for using `zod` effectively in projects based on TypeScript (both browser and node.js). The benefits you gain with this course is not just simply coding, but also understanding when/why/how should you perform runtime validation.

`zod` is the missing piece to TypeScript's capabilities, which can guarantee type-safety only in compile-time.

`zod` can be used whenever the compiler cannot guarantee what happens in runtime. And... it's a very frequent usecase, such as HTTP calls, websockets, etc.

In this course you get quickly up and running by:
1. using `zod` with primitives and objects
2. adapting `zod` quickly to existing projects thanks to automatic generators
3. changing the strategy frm type-first to schema-first
4. using error-throwing `parse` or non-error-throwing `safeParse` basing on your needs
5. applying `zod` to the most common usecase - validating API responses
6. handling errors the most convenient way (out of many!)

Take advantage of runtime validation with `zod`. Take advantage of the detailed lessons in this course 🔥

`zod` is a powerful library allowing to run runtime type-checks.

It's complementary to TypeScript, which does type checks in compile time.

In this lesson we create few schemas that represent primitive type values, along with `zod` utilities which make these more precise. We also create object schemas and nest one inside another.

All schemas are being validated against example values. We analyze how to interpret error messages in case of failures.

Perform Runtime Type-checks on Primitives and Objects with zod

`zod` is powerful, but writing the schemas manually for existing JSON objects, especially big ones, can be time-consuming.

But that's what `quicktype` is for! You can get 80% work done instantly! 🥳

Depending on your need - whether you want to automate the process, or do it just one time, you can:
- use an online app
- use an IDE extension
- run a CLI script
- generate a script to be executed within CI/CD environment/tooling

And this is what we learn in this lesson! 🔥🔥🔥

Get started with zod quickly!

Generate zod Schemas Automatically using Quicktype App, Extensions and Scripts

In this lesson we learn that the `zod` schemas become the single source of truth.

We shall not update TypeScript types manually, since they are generated automatically from the schema.

Same with validation functions.

Whenever the schema changes, all the rest will update accordingly. It's an important mind shift.

Treat zod Schemas as Single Source of Truth

In this lesson we learn that TypeScript cannot guarantee correct shapes of responses. That's due to TS performing checks in compile-time, while the response will be availbale in runtime - when TS doesn't exist anymore.

In some situations, such as HTTP requests, runtime type checks such as `zod` are essential for providing quick feedback around data-related errors.

Understand where are the possible mistakes to make while using TypeScript with HTTP calls. Use `fetch` and `axios` along with `zod` schema checks.

Also, note that similar mistakes or mistakes could happen while using web storage (e.g. `localStorage`)

Validate HTTP API Response with zod, fetch and axios

You might want to run `zod` schema checks in different styles.

Sometimes you prefer to conditionally throw the error - that's what `parse` does. But another time you'd prefer to receive a `boolean` property that determines whether the validation was successful or not - and perform further actions accordingly.

Additionally, the error-throwing API of `parse` works extremely well with [TypeScript assertion functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions). Their combination is just... perfect! 👌

That's what we learn in this lesson.

Use parse and safeParse Runtime Type-checks with zod

While running `zod` schema validation agains domain-rich objects, the error message saying that _a string is not a number_ might not be really useful.

Especially, when you need to provide a meaningful feeback to the user, e.g. after they have submitted a form with lots of data.

`zod` allows to customize messages on a very granular level. We can also extract repeatable customization to `zod` error maps.

Finally, in order to process an error message further (e.g. display it to the user), we need to handle the `zod` validation errors effectively. Especially, when a big object validation has failed and we could receive a handful of errors.

That's what we learn in this lesson. 🔥

Customize zod Error Messages and Handle zod Errors Effectively

typescript

Effective Runtime Type Checks with Zod

[00:00] Start by installing Zod using the npm install zod command and importing Zod from the Zod package. Now Zod exports lots of smaller utilities though we're going to access all of them using the Z utility object just for simplicity. Let's now create the first schema. So this is going to be number of guests since all examples within this course are going to relate to a room booking business domain. So what Zod allows us to do is to create a schema.

[00:35] So an expression that will exist in JavaScript will be validated against such a schema to verify whether all conditions are met. So we're going to use the number of guests and run the parse function against an expression. So I'm going to save the file and run this file here using tsnode and running the file and we see no output since this parse function is going to throw an error only in case if the expression passed doesn't meet the schema conditions. But we can of course run console.log and if the value meets the conditions of the schema then it is going to be returned. So we are expecting the value 3 and here we get it.

[01:21] Let's also see how could the validation fail. So if number is expected, then string is not going to be a correct value, which is kind of obvious, but we can also see that there is a long stack trace and there is a ZodError thrown saying that there is an invalid type. The path is empty since this is just a primitive value not an object. We can see that a number was expected, a string was received, and finally the message is expected number, received string with a long stack trace, and again this is the ZodError object. Now let's add more conditions to our schema.

[01:59] So instead of defining what is the type expected, some of the types such as numbers, string, etc. Have more specific expectations. In case of a number, we can expect a minimum value. So let's say that the minimum number of guests in order to make a booking, make a reservation is one. And let's say that the maximum number of guests for a single room is four.

[02:24] So there are some pieces that will not be visible on TypeScript level, but they are possible to be verified within JavaScript's runtime. Here, the value 3, if we make it back a number again, this is going to work. So we will see that there is a console log with value 3. But if we make it 5, then the minimum is being matched, the expectation, however the maximum for is failing and yet again we get a ZodError saying that there is a error code saying the value is too big, maximum for etc etc, number must be less than or equal to 4. And again we get a ZodError object over here.

[03:08] So let's create one more and that would be a contact email which is going to be a Z.string. So we have the equivalents to all JavaScript primitive types in Zod. So that would be number, string, boolean, symbol, bigint, null, undefined, etc. Etc. So they all have their equivalence.

[03:30] So in case of strings, we have way more utility functions such as UUID, URL, and many, many more. We're going to use the email one. So let's say that what we're going to verify is going to be in our case, the contact email dot parse. And let's say that we want to run john dot doe at example dot com and let's see whether this matches the expectations but let's also make this one pass So what we can see is 4 and this one is a correct email. However, if we try to ruin the email format we'll see that yet again we get an error.

[04:14] In this case The error code is the invalid string validation email, etc. Again, the path is empty since this is just a primitive value, not an object property. So let's now move forward to creating a object-based schema. So in order to create it we're going to do a room booking schema and this is going to be a Zod object. So Zod's API is trying to reflect how we write JavaScript or TypeScript as much as it's possible.

[04:48] So let's say that we would have a room type which is going to be a z.string. So now we're allowing all possible strings to define what the room type is. We're going to deal with that later and there would be a due date which is going to be a z.string.date so we can create a special string that is formatted to include a valid date format. Now we can use the number of guests which we've used before which is going to be essentially this line and finally we can have a price which is going to be Z number and yet another helper which is going to be a positive since obviously a price cannot be negative. Now let's create an example object const example booking and this one is going to have room type which is let's say a suit and due date which is let's say 2025 the last day of the year number of guests which is three and finally the price which is let's say 300 And here I just need to close the string and finally room booking schema.

[06:07] So we are running the parse again on the schema itself. And we're validating whether this one meets all our conditions. So, again, let's run the console log to see what is the output. So if everything is correct, then we're going to see that value itself, which is essentially parsed by Zod. So something seems to be wrong, and we can see that there is an invalid type number and an undefined was received, so number of guests.

[06:42] So I made a typo, so it's nice that it has been already figured out. So let's run it again and we can see that there is an object. By the way, if I ruin this object back again, then we can see that the path property has been correctly defined, so that we can see, okay, this is the sequence of the properties that we need to walk into from the very root of the object that is being checked. So let's make this object correct again and let's proceed by creating a nested object so in this case we're creating const guest details schema which is going to be yet another Z object and here we will define that there would be a string property under the name. The age is going to be z.number which is going to be positive or at least zero.

[07:42] And an email which is yet again z.string which is also a valid email. Now what we can do with our above schema if we just move it over here is that we can use one schema within another one. So that's going to be guest details which is going to use a z.array. And the array doesn't compile since there is at least one argument expected. And the argument is another schema of what is the element of the array.

[08:19] So as simple as that. So let's also run this validation. So we will see that the guest details property is missing right now. So let's also see that invalid type expected array received undefined. Yes, details property is required, but it was not passed.

[08:39] So let's add this one. So that would be guest details. And this is expected to be an array. And let's say that there would be one array, name, which is John Doe, age, which is 30. And let's say that the email is the one that we have created before.

[08:58] So John Doe at example.com. So let's see whether it meets our expectations. And as we can see, yes, it does.



https://app.egghead.io/api/v1/lessons/perform-runtime-type-checks-on-primitives-and-objects-with-zod~ctv1u/transcript

[00:00] Writing Zot! Schemas manually could be tedious and time-consuming and for this reason we can automate the process. Here we've got the example booking JSON file so let's copy the content of it and let's open an application at the app.quicktype.io. QuickType is a package that allows us to generate interfaces or classes for various different languages basing on what our JSON is. So what we're going to do right now is to create an empty JSON.

[00:33] Let's call it for instance data. We can write over here that this is going to be let's say age that is going to include I don't know 50. And let's say that this is our person schema. What we can see is that automatically the corresponding JSON schema as well as the TypeScript type is being generated. So let's paste our booking.

[00:58] So let's also define that this is called a booking. And what we get here is the room type, due date, number of guests, price etc. Everything is being generated. The difference is that we don't have the specific property utility such as the minimum and maximum for a number and we don't have also the positive for the price since there is no way for the mechanism to figure this out. However, this is still way faster than typing this manually.

[01:30] So if you have existing APIs this is the quick way to generate your Zod Schemas, at least generate the initial versions. So one option is to go to app.quicktype.io. The alternative is to install IDE extensions such as this paste JSON as code used within VS Code. So what we can do is to open the example booking. Now let's run the quick type command in the bar and what we can see here is to open QuickType for TypeScript and here we can see the example booking schema, the same one that we have seen within the web application.

[02:14] So let's say that for some reason you want a different language and that would be QuickType and setTargetLanguage and for instance TypeScript so we would have an interface of a TypeScript JSON. So we would have an interface representing the example booking. By the way, this name is being generated automatically from the file name. And as you can see for QuickType we have quite a bunch of different languages over here. So That's the second possibility.

[02:47] So the web application, the IDE VS Code extension. And finally, we can install the packages locally. So let's run npm install QuickType and QuickType-Core. So let's install these packages. And I have already prepared the packet.json scripts over here.

[03:11] So here there is a QuickType lang TypeScript zod and the source is essentially example booking JSON file so as you can see this command is pretty straightforward. So what we're going to do right now is to run the npm run quick type and what we're going to see essentially is the dot schema so most probably this would be the desired one since this can be automated using the continuous integration tools. And finally if you wanted to have even more control over what's going on here then we can take a look at the QuickType generate. So we are not going to go through all this code that has been generated. This is based on the QuickType documentation.

[03:57] So essentially this file is Generating a code which is yet going to generate a validator over here So let's run this one. So we're running TS node and here we're running the quick type Generate file. So what it's going to generate is the QuickType generator file. So let's take a look what has been generated. QuickType generator file.

[04:24] So this has been again automatically generated. So what has been created here is the TypeScript interface, the one that we have seen before, and there is a convert class. So we can create our own script that is going to use the two. So let's walk into the final file QuickType TS. So what we're going to do here is to import from the newly generated file.

[04:50] So this is what is going to potentially change basing on what the JSON content is. But this file over here is going to remain the same which you would push into your repository. And finally, there is the interface that we want to use. So what we could do is basically try to convert, let's say we want to convert to room booking, or we can convert a room booking back to JSON. So both ways, Let's say that, and by the way, this one is expected to be a stringified JSON.

[05:22] So this would be an empty one, so this is an empty object. Let's run this file, so that would be ts-node and here the QuickType file. So we will see that this is going to fail essentially because our example booking, our booking schema expects for certain properties with their corresponding types. And here, this one is basically empty. So what is returning over here, what it's throwing actually is invalid value for key room type on room booking.

[05:52] Expected string got undefined. So again it's the same thing. So now what we can do is to comment this one out and we're going to rely on the JSON that we can basically load from our disk over here. So this is going to be the example booking.json file. So we know that Since the conversion has been generated from this file this has to work.

[06:20] And finally we are going to stringify this JSON so this is going to be JSON.stringify from what we have just loaded from the file. And finally we're going to copy this conversion and we can also assign it into the result because this is supposed to create the thing. Now if there is anything going wrong then this was basically throw an error. So if the script continues then we are sure that this is the correct shape, this is the correct object. Now convert to room booking and finally we just put the stringified version over here.

[07:00] So let's see if this works, let's rerun the script. The output is empty, as we can basically see it is a success, so we can also do a Console log with what is the result and we are going to yet see what is the output over here. And what is interesting is that the due date, it used to be basically a string, but due to what QuickType automatically and by default has generated is that since that matched a date string format, it has been moved in to become a date object. So that's one thing and there is also another possibility that we could basically extend our object to be something bigger. So let's say if we provided a something totally, totally different and I have just pasted a very, very, very big object over here then we can generally do the very same and this is going to run the QuickType Generate.

[08:02] We will see that our QuickType generated file is going to be way bigger and so we can run our QuickType TS file to see that everything is correct. Whether this is a single and small flat object or whether this is a nested object this quick type thing can cover either simple data structures or really complex ones



https://app.egghead.io/api/v1/lessons/generate-zod-schemas-automatically-using-quicktype-app-extensions-and-scripts~nkll5/transcript

[00:00] Whenever working with runtime validation libraries, it's important to realize that it's the schema which becomes the single source of truth for both the compile time types and the runtime validation functions. So typically, Whenever we create a TypeScript type or an interface, it's a type that determines what are the valid objects or other expressions or primitive types that we're using throughout our program. And whenever we update the type or the interface, we might need to update the according objects or other expressions within our codebase. However, in this case, it's the schema which should be updated as the first one and both the types and the validation functions will update automatically. So there is nothing that we should do here.

[00:48] So we have already seen that if we use the room booking schema from the previous lesson and we run parse against an object, basically whenever our schema changes, the validation function would update accordingly. Now, how about the type? So we can extract the type of a certain entity, of a certain type, interface, object, whatever that is, just by using z.infare. And what we need to pass as the time parameter here is the schema, obviously. However, due to TypeScript syntax, what we need to do is to extract the type from this runtime expression.

[01:28] And this is a runtime expression since this is basically a variable, whether it's const, let or var, doesn't matter, so we simply need to wrap it with the typeof keyword and we've got the type and so our room booking is simply a room type, due date, number of guests and the price. So what we can do now is to create an example const booking object which is not just going to be an object literal that is unrelated to any typescript type, interface or class or whatever but we're going to annotate it with the room booking type that we have just inferred from our Zod schema and as we can see since this is just an empty literal S for now this object is missing the following required properties, which is essentially all the four room type, due date, number of guests, and the price. And generally speaking, it's not about the missing properties, but it's about pretty much all the features and all the capabilities that TypeScript is able to perform in the compile time. So according to the type that has been inferred, TypeScript is capable to run all the compile time validations. And as we can see, some of these utility features are being lost.

[02:47] For instance, the price is a number, but not just any number, but a positive one. And as we can see, the fact that this is a positive number is lost because there is simply no clear way how to determine a positive number, at least according to TypeScript. And the same here. There is a minimum value one and maximum value four. And again, simply there is no clear way to define such a range in TypeScript, or at least no simple, no clear, no built in way in TypeScript.

[03:18] And so some of this information could be lost. However, the fact that this is a number is still quite important and this solves a lot of bugs anyway. So we could treat that the vast majority, we could say the Pareto principle, 80% of the important features are still being translated into TypeScript and the minority, let's say 20%, could be lost. So let's quickly fill in this object. So this is a booking which includes the room type, due date, number of guests, and the price.

[03:51] Now it's pretty obvious that this booking object is going to pass the validation. However, if it happens that our object, our expression is missing one of the properties or the property value is of an invalid type or anything like that and for some reason somewhere in our codebase there is an unsafe type operation applied such as the as any type assertion. Now it could happen that our expression and the TypeScript type itself is out of sync and TypeScript for some reason is just unable to find where does this error come from. And this is exactly where the runtime validation is super useful. So let's run this file and we will see that certainly the validation function is able to find out that there is simply a missing property, that this room type property on the object should be a string but is undefined.

[04:54] Now it's easy to figure out that since we have an any over here then there could be bugs and TypeScript is not capable of finding this. But what is important is to figure out what are these certain cases. And this is what we're going to do in the next lesson.



https://app.egghead.io/api/v1/lessons/treat-zod-schemas-as-single-source-of-truth~8fli2/transcript

[00:00] The situations when TypeScript is incapable of guaranteeing type safety to our codebase is most often loading data from external sources such as HTTP requests, web sockets, web storage, databases and so on and so forth. What's common for all these is that the shape of the data in runtime doesn't come from our code base but from the external data source and hence the TypeScript compiler cannot guarantee its correctness. So let's start with writing an example HTTP function and I'm going to toggle the booking example object and the booking schema. So we're going to start with a fetch data function which is going to use the native fetch API internally And we're going to use the API that is available online, the jsonplaceholder.typico.com, which basically exposes some REST resources that are being reset every few minutes. So it's very good to have a play.

[01:00] So we're going to run it against the API URL and we're going to fetch the post slash one resource. And what is obvious is that whatever the post is, it's going to be totally different than a room booking schema. These structures are going to be totally totally different and what we want to illustrate over here is that TypeScript will have no means, no way to figure out that what we will actually get and what we claim that we are going to get because this is what we're going to annotate over here is totally different. TypeScript cannot see it. TypeScript has no way to figure it out.

[01:39] So let's make the function async. Let's also create the response variable which is going to await the fetch call and let's return the response.json call. Now what is important is that response.json call returns a promise of any. This is not a mistake by any author of the types. So again TypeScript has no means to figure out what is going to be the runtime value and TypeScript exists and works in compile time, so this is before the thing will actually be executed.

[02:11] So the promise of any can be casted into a promise of a booking. Why? Because booking is either a subtype or a supertype of any and hence this could be asserted. But the function result could also be annotated with the promise.booking. Why?

[02:30] Because booking is essentially a subtype of any. So everything from TypeScript perspective is correct, but we know this is total rubbish. So let's run this function. Let's execute that there is a fetch data. And when we have actually the result we're just going to console log it.

[02:52] So let's see what is going to happen. Let's run ts-node and this is going to be the API response validation file and what we can see is the data returned from JSON placeholder which includes the user ID, ID title and body whatever that is and we can see that this is clearly totally different than the booking schema. Now the whole point of introducing runtime validation like Zod is that even though we claim that the structure that we expect is of a certain shape, but there could be any change on the backend that hasn't been yet synchronized with whatever our data structure is, the one that we expect. So if there is any mismatch, if there is any difference that we are not yet aware of, then we would like to have it automatically reported, automatically figured out. So what we can do essentially is that we can, before we do the .thenConsoleLog, we can add additional step which is going to run the validation itself.

[04:01] So if this is the result what we can do is basically parse the result. So again let's say that this is what we're expecting so that would be the booking schema and we're going to parse the result over here which is expected to fail. Fail very badly actually. There is actually a whole collection of errors. So there is an invalid type, invalid type, invalid type, invalid type, et cetera.

[04:24] But that's the whole point. So this is something that TypeScript is incapable of figuring out because this happens in runtime and hence we are running a runtime validation. Now this is not specific to Fetch API so let's introduce Axios, a popular library that is responsible for running HTTP requests. So let's also create the fetch data function, which is going to rely on Axios API, and it's going to be very similar. So we're going to run axios.get, and in the meantime, we can import the Axios function.

[05:07] So let's introduce import Axios from Axios. So we've got the Axios.get and we're going to run the exactly same request. We're going to use the async await API over here so let's make this function async. Return the response.data. Now this one is not a promise but still what we've got over here is an unknown.

[05:35] Now, not an any, but a known. So let's see where does this come from. So if we take a look at axios.get, then we will see that there is a generic type over here that we don't define and actually there is no way for TypeScript to figure out what is this t. So a default value for the type parameter is being used and the default for TypeScript type parameters is unknown. But what we can do actually over here is that we can say that hey I'm expecting a booking object over here.

[06:08] And finally FetchDataAxios it's claiming to return the booking object which is of course wrong. So what we can do is to run fetch data axis. And again, then what we can do is to run the booking schema parse with the result. So let's just pass the result over here. And yeah, of course we have to run the function and this would be the result and let's also Break it into the next line and I can just comment this out so that when we are running this file we will see only the Axios API running and we see exactly the same errors because essentially this is the same API though it doesn't matter which API we're using whether it's Fetch or Axios and whether it's HTTP requests, WebSockets, WebStorage, databases, etc.

[07:06] TypeScript again has no means to figure out in compile time what is going to be the exact shape in runtime. So we have to make some assertions over here like this one or like this one. This depends on the API. Another common situation is when we're using web storage such as local storage. So let's say that we have a key that is holding let's say the state of our application and what we're going to do is to get the value from a certain key, so that would be get item over the local storage object and let's say that the key over here is the state.

[07:48] So the nature of local storage is that all keys, if they exist, they hold a string value. If they don't exist then what is being returned is a null. Now the whole point most often is that we're going to stringify a big JSON object whether it's nested or flat, whether it's big or small, but we're going to stringify it. So if this thing exists, we would need to run an if statement, So let's just simplify things and exclude the null just for the sake of simplicity. So now this is a string.

[08:23] Let's also parse the JSON that we would keep over here. So that would be json.parse over what we've had over here. Now what does JSON.parse return? Any. For the very same reason.

[08:37] Because TypeScript has no means to figure out what is going to be the data structure in runtime. And yet again this is just a question of whatever we claim here but we could be wrong. So in all these cases it's a good idea to include or at least to consider including a runtime validation.



https://app.egghead.io/api/v1/lessons/validate-http-api-response-with-zod-fetch-and-axios~re94k/transcript

[00:00] I have copied some code from the previous lessons and so we have a booking schema which is exactly the same as before, exactly the same shape. Now we have the type booking which is inferred from the schema, again same as before. We have also the same example booking object in this case annotated to the inferred type which includes everything that is required within the booking type so we can also collapse this one and there is a new object an invalid booking example object that includes all the properties that are required but some of the values under these properties are invalid, like their values are invalid against the schema itself. Because we can see that TypeScript does compile but for instance what the schema expects is that a due date is a string. And here it is a string, but it's a special string, which has a certain format that can be verified in runtime.

[00:58] And the number of guests is indeed a number, but it should be between one and four. And what we have here is 5 and finally that the price should be a positive number but what we pass here is a negative one. And as we can see TypeScript is pretty often incapable of finding these small nuances. So again this depends on how much precise, how precise we want our Zot Schemas to become. Anyway we're running the schema.parse method over here against the valid booking object so let's just run ts.node against this file and we will see that there is no output since this object conforms to the schema.

[01:41] So there is nothing interesting going on here. And if we just make sure that when we run it against the invalid booking one, then we'll get an array of errors. And here we can see that there is a problem with due date because it's an invalid date. There is a problem with number of guests because it's basically too big maximum for what we passed is five. And finally, that the value of the price is too small, since we expected a positive number, and we passed a negative one.

[02:11] Now running parse directly is probably the simplest way to run Zod Schema validation but probably not the best one. And let's see an example over here. Let's say that we have a variable of type unknown. We just don't know what it is and I just don't want to assign any value over here so I'll just use the declare keyword. Now if we run the same validation API which is basically schema.parse and here we pass against x the thing is if the object was correct then the program would basically carry on and execute the next lines just below the parse line.

[02:51] Now we've had no data, no knowledge about what X is, but after we run parse itself, we do know that x needs to be a booking schema, or from type 2 perspective that this is a booking. Now what do we know after this line? We still know nothing. Also what we know is that if x didn't conform to the schema, then basically an error would be thrown so we would not carry on with executing the code anyway. All in all, the negative path is correct but in the positive path when x conforms to the schema we would like to know that this is of type booking.

[03:30] What we can use is we can just wrap this call with a TypeScript assertion function. So this is basically a function that asserts that something is a room booking. And we can also add that the room booking schema is matched just to make the name more precise. So this is basically the candidate and this asserts that whatever we pass over here, so here is the data, is of whatever is the type that we are going to verify over here. So this is going to be of type booking.

[04:02] And what we can do is simply run the validation. So this is going to be the booking schema dot parse and what we verify over here is booking itself. So the way TypeScript assertion functions work is that if the thing does conform to whatever are the conditions then we simply do nothing. But if it doesn't conform that an error should be thrown. And this is exactly what the schema.parse() method is doing.

[04:34] So all in all, instead of this case, where we still have no information about the type, what we can do over here is we can just assert room booking schema matched or whatever name of the assertion function we pass and now we know that if the assertion was correct then we can carry on with the rest of the code knowing more about what x is and if it didn't succeed then there would be an error that would basically wipe out the code anyway. Now there is one more way to run the validation which is different than parse itself, the safeParse method which is going to be pretty similar to parse itself though the difference is that this is not going to throw an error, but return the safe parse return type, which is going to include the type of the result, like success or a failure, and either the data or the error itself. And let's just rerun the script to see that there is no output and we can take a closer look at what is the safe parse going to return in both the positive and the negative scenario. So what we can see here is that there is an object that always includes success which if true includes the data and if the success is false then there is an error, the reason for this failure.

[06:04] Now if we also make an if statement in TypeScript then we could make a type guard over this discriminant property since if success is true then the data needs to be here if success is false then the error needs to be here so if we store the validation result in a variable and let's just copy and it doesn't matter whether it's going to be the valid one or the invalid one, and we want to take a look at the validation result, then we would see that success is a Boolean. So again, not sure whether it's true or false yet. And the error could be here or not, so it could be undefined. And the data could be here or not undefined because we don't know yet. However, if we walk through an if statement, just checking whether the validation result success is true, then we need to be in this very branch, so that we know that the validation result.success is true, obviously, but we also know that data cannot be undefined at this point.

[07:15] And what you can see over here that we're not doing the type guard over data we're doing the type guard over success so essentially internally there is a TypeScript object union type over the validation result of the safe parse In the same way if we did the opposite check and we would see that there is a validation result and we are sure that success needs to be false over here then error cannot be undefined because if it failed then there needs to be an error. This is also quite useful when using Zot in production applications.



https://app.egghead.io/api/v1/lessons/use-parse-and-safe-parse-runtime-type-checks-with-zod~bvxrh/transcript

[00:00] Initially, our object passes the schema validation over here. So let's just run this file against ts-node to see that the output of the script is empty, since again, the schema validation works correctly. Now let's modify this object. And for this reason, I'm just going to spread it and overwrite one of the properties. So let's say that the number of guests is going to be overridden to zero.

[00:27] Now I want to provoke a situation where the schema fails. So let's run this one back again. We're going to get an error saying that there is a too small value for the type of number and the message is the number of guests. And here we have a pretty generic message saying that number must be greater than or equal to 1. Now, we might want to customize this error message, for instance, when we are validating the input that comes from a user field form.

[01:01] So most of these Zod-based utility functions allow us to customize the error message. And so the min utility accepts the value that is going to determine what is the minimum value, but also what is the message. So let's say in this case, we just don't want it to be greater than or equal to one, what one. So we can write that there must be at least one guest, since this is our domain. Now the same for the maximum value so at most four guests are allowed within a single booking.

[01:43] So let's see how would this error look like right now? So we can see that there must be at least one guest. Now, the same way we can customize the error message for the positive. So let's say that, like, how could a price be negative? Right?

[02:02] So let's again, drop this one and provide the price that would be let's say minus 100 and again let's run this validation we've got the message that is negative price huh So this could be directly used within the form that is displaying the error messages to the user. So you don't have to do it on the level of your React, Angular or whatever are using forms, but directly within the schema itself. So one more thing that we would like to take a look at is that when we define the min and max, they make either the number or strings or other different types more precise. But when we take a look at the options of the string over here Then we will see that we have way more possibilities So params is first of all an option bag so an object that is going to include quite a lot of these So let's take a look at the options and we're interested in four of them. So message is what we've seen so if the value under a certain property is wrong then this is the one that is going to be used.

[03:12] When we require a property and it is not passed in the object that is being validated, then required error is being used instead. Now, we might be using both the message and the required error properties to determine what are the errors, but it could happen that we might want to reuse them across different properties of a given schema or across many different schemas within the same code base. In this case, we might be interested in creating a separate error map object that is going to be just pass as the reference to a certain property or to many different properties within a schema. And the description is the property that is going to describe what is the whole meaning, what is the semantics of this property. So this one is not used directly by the validation itself, but is being used by many different tools in the Zod ecosystem.

[04:09] So now let's put the message and we're in the due date property. So let's say that there is invalid due date. However, what is important in this case is that there is a due date message on the string utility, but we could also provide the date utility. So now the question is on which step does it fail? Does it fail on the step that a string was expected and let's say a number has been passed or was a string passed and it failed on the date formatter validation itself?

[04:44] So let's see the difference between the two. So we can just remove this one and provide that there would be a due date which is not going to be a string so this is going to fail on the Z string and let's see this over here and we would see that yep this is the invalid due date however if we want to provide a separate message when it is a string, however, the strings format is wrong. Now we could write that the date format is wrong over here and we can now provide it as a string and this error message is going to be displayed in this case. And we can already see that, yep, date format is wrong. So as we can see, there is a sequence of validators that are being executed one by one.

[05:36] So there is one more useful feature that we will cover here, and that is processing Zod errors on TypeScript level. So as we can remember, parse is conditionally throwing errors, and for this reason, we're going to wrap it with a try catch block. So let's put the catch E over here and depending on our TypeScript setup, E could be either off type, any or unknown. Here TypeScript is more strict so this is unknown. Now if something is unknown then we don't know what it is hence we don't know what are the properties.

[06:09] So it would be nice if there was a way for TypeScript to figure out to apply a type guard to verify what exactly this error is. And thankfully Zod does provide a certain prototype for us to verify what this error is. So we are running the E instance of and here we are using the Zod error. Now, if this if statement turns out to be true then what we know immediately is that the error is something that could have the issue or issues added, there is a cause etc but most importantly it has the issues itself. So since we do have issues it is possible for us that we can iterate over them.

[06:54] So let's just iterate for and here const Zod issue of the E.issues and here we can walk into the details over here so if you need for any reason to manipulate the messages, to use them, to combine them with your local component state, whatever that is, then we can simply use them directly. So what we can do is to access the Zod issue, the code of the error. So for many of these positive, min, max, email, UUID and many other utilities there is a code. So that's one thing. The message is that you might probably want to display to the user if this is more meaningful than the technical messages.

[07:42] And finally, the path saying which property did fail. So let's quickly see this one in action and we can see that there is an invalid string, date format is wrong and the due date so accordingly the code message and the path. So it could happen that instead of parse you might also want to use the safe parse, the equivalent that doesn't throw an error and stores the result in a boolean variable. So let's do this one. So that would be the safe parse result.

[08:11] Let's call it this way and let's just replace the parse with safe parse and let's just stick to the error that we've had right now And if we want to take a look at what the error is Then again, we can run the type guard over this So SP result and let's check whether the error does exist over here. So here we know that the error does exist so there would be a format over here. So yeah this is the format so let's also console log what this error is going to be. Let's run this in the script and we can see that there is errors for the whole schema, for the whole object, but there is also for the due date that there is an error that the date format is wrong. So this is yet another structure that we can iterate over.



https://app.egghead.io/api/v1/lessons/customize-zod-error-messages-and-handle-zod-errors-effectively~y0quo/transcript

Effective Runtime Type Checks with Zod

Tomasz Ducin

Course Content