Zod Validation methods - Zod schemas, parsing methods, & more!

[00:00:00]Let's have a look at validation methods that are built into Zod and the differences between them. We're going to look at the parse, the safe parse, and also the async variants of these methods. And we'll look at what the difference between them is and when you should actually use each one. Now, Zod is something I've been using a lot recently. So, I just want to make a quick video and show some of the different usages here. And it's very popular in, for example, React applications. Before we get started, if you want to support the channel, check out our coffee page. We've got a link at the top comment. And let's get started looking at Zod validation. Now, if we go to the basic usage section, the standard workflow for Zod is to define a schema, and then you will parse some kind of data using that schema. So, you can see here we have a schema called player, and that is a Zod object with a username, which is a string, and experience points, which is some kind of number.

[00:00:49]And then we parse that data. So, for example, we take the schema here and we call dot parse, and we pass in some raw data to that. And if it's valid, Zod is going to return a strongly-typed deep clone of the input. Now, I want to do some practical examples in this video, so let's go to VS Code. We've imported the Z object from Zod, and we're going to define a user schema here, and we're going to set that equal to a Zod object.

[00:01:13]And then inside that object, we define the fields and the validation constraints. So, for example, a user might have a name, which is a Zod string. So, that's basic type validation in Zod. We might also have an age, and that is going to be a number, but we might want to specify a minimum of zero here, because of course, we cannot have negative ages. And let's add one more field here, and that's the email field, and that is going to be equal to the Zod email type. Now, this function here will basically validate email addresses, so we can then use that inside our application. But how do we take some data and use this schema to actually parse that data and validate the data accordingly? So, let's define a user variable here, and what we're going to do is take the user schema that we have above, and we're going to call dot parse as we saw in the documentation, and let's pass some information into that.

[00:02:01]So, we're passing a JavaScript object with a name, an age, and an email address. And then what I'm going to do at the bottom is just console.log the user to the terminal. And let's see what happens when we run this program. And I'm going to run node main.ts, and let's see what comes back here. We can see the object that has a name, has an age, and an email address. So, that has been validated by calling the dot parse method. Now, what happens if we pass in data that doesn't conform to the Zod object schema? For example, a negative age is disallowed by this validation, and we might set this to something that's not an email address. This time, if we run the code here, you're going to notice on the right-hand side we have some errors coming through. So, we get a Zod error here when we call the dot parse method. That's a key thing to take away here. The dot parse method is going to throw a Zod error, and it's going to stop and crash your application unless you handle that error. So, this Zod error gives you a detailed breakdown of every field that has failed, and you can find the path to the field that has failed using this path key here, and that is a list, and you can see, for example, here it's the age at the top level that has failed. And if we go down here, it's the email field that has failed in that second object in the Zod error. So, the Zod error has that breakdown. It tells you what field has went wrong. It gives you a message, and it also gives you the actual validation error. For example, in the top one, we have the code of too small. The minimum was zero, and we passed in minus five.

[00:03:28]And in the second one here, we have invalid format. It's expecting an email format. So, we get detailed information.

[00:03:35]Now, the parse method is useful for situations where invalid data should stop the running of the application. So, for example, parsing a configuration file when your application starts up.

[00:03:45]That's something that if it's wrong, you probably don't want to go ahead, so you should crash out of the app. Now, there is a more forgiving method available in Zod, and instead of parse, it is the safe parse method. Now, this is what you want to use when a validation failure is a normal expected outcome. For example, when dealing with user data being sent to your server. This is not going to throw the Zod error. Instead, it's going to return an object that has a boolean property called success, which will be true if validation has passed and false if it has failed. So, let's again see this in the terminal. If we go back here and run main.ts, we can have a look at this output, and it does look similar, but notice at the top here, we have an object being returned. It's not returning the error itself or raising that error. Instead, we get an object, and we can see that success is set to false. Now, when success is false, we have an error property here that is set to the Zod error, and that is the same output we saw before. That's the Zod error there. We can clear this out here, and if we change this back to valid data, for example, here, and I'm going to change this to safe parse as we had it before. Now, the age is valid and the email field is valid. If we save that and rerun the program, you can see we get back a different object. This time, the success boolean is true, and now, instead of an error property, we have a data property, and that is set to the validated data. So, the safe parse method is useful for form validation or API request bodies. Basically, anything coming from the outside world where there's a good chance that some of this might be invalid, but you don't want your server crashing just because someone typed the wrong age. So, safe parse gives you a way to handle that gracefully, and if we go back to the Zod documentation, let's go down to the section on handling errors. So, when validation fails, parse will throw a Zod error instance, as we saw before, and you can use the safe parse method if you want to avoid that try-catch block, and that gives you back that result object with the success property. And this is something I just want to briefly cover here. With safe parse, we get a result type that is a discriminated union. So, you can handle that code as you can see here. So, for example, we get a result by calling safe parse with some data, and then we can check if the result.success property is true or false. If it's not successful, you can look at result.error, and if it is successful, you can look at result.data.

[00:06:07]So, the return type of safe parse is a discriminated union, and the discriminant property is success. If success is true, you get back the data.

[00:06:17]If success is false, you get back the error. So, those are the two key parsing methods in Zod. We have the parse method, and we have the safe parse method. Now, notice the notes that we have here in the documentation. If your schema uses async APIs, such as the async refinements and transforms, you need to use the parse async method instead. So, there are async versions of these methods. Parse async can be used, and if we scroll down here, there's also a safe parse async. Now, I want to finish this by looking at the refinements documentation. So, in Zod, refinements are a way to perform custom validation that Zod doesn't provide a native API for. So, for example, if we look at this here, there's a variable called my string, and you can use the refine method to define a refinement.

[00:07:05]And this one here looks at the length of the string and make sure that it's less than or equal to 255 characters. Now, if we go down here, we're going to see an async variant at the bottom. So, if you need to do an asynchronous refinement, you can pass an async function. So, an example of that would be if you have a user ID variable, and you want to make sure that that ID actually exists in the database. So, looking up the database will be an async operation. You would do that inside this method, and that will return true or false. And that's where you have to use the parse async method in order to parse that data. Now, in my experience, most of the time you're using the synchronous methods, but the parse async and parse safe async methods are also available. Now, for anything that's user-facing, typically you're going to use safe parse, and then you can look at the success boolean property of the result object and determine whether there has been an error or not, and whether you have the validated data, and you can then act accordingly in your application. On the other hand, the parse method should be used with data that you control or any kind of configuration and startup data and trusted data in your application. So, that's it for this video. It's been a quick one on parsing data using Zod and using the methods available to you in the Zod API. We have safe parse, we have parse, and we also have the async variants of those. If you want to dive into Zod any further, let me know in the comments. For example, looking at those async transforms or refinements, that might be an interesting follow-up video.

[00:08:32]Let me know in the comments if you'd like to see anything else. And if you found this content useful, check out our coffee page. And thank you to everybody who has supported the channel. It's much appreciated, and we'll see you soon in the next video.