It is best practice to validate the correctness of any data sent into a web application. To automatically validate incoming requests, Nest provides several pipes available right out-of-the-box:
ValidationPipe makes use of the powerful class-validator package and its declarative validation decorators. The
ValidationPipe provides a convenient approach to enforce validation rules for all incoming client payloads, where the specific rules are declared with simple annotations in local class/DTO declarations in each module.
In the Pipes chapter, we went through the process of building simple pipes and binding them to controllers, methods or to the global app to demonstrate how the process works. Be sure to review that chapter to best understand the topics of this chapter. Here, we'll focus on various real world use cases of the
ValidationPipe, and show how to use some of its advanced customization features.
info Hint The
ValidationPipeis exported from the
Because this pipe uses the
class-transformer libraries, there are many options available. You configure these settings via a configuration object passed to the pipe. Following are the built-in options:
In addition to these, all
class-validator options (inherited from the
ValidatorOptions interface) are available:
|If set to true, validator will skip validation of all properties that are missing in the validating object.|
|If set to true, validator will strip validated (returned) object of any properties that do not use any validation decorators.|
|If set to true, instead of stripping non-whitelisted properties validator will throw an exception.|
|If set to true, attempts to validate unknown objects fail immediately.|
|If set to true, validation errors will not be returned to the client.|
|This setting allows you to specify which exception type will be used in case of an error. By default it throws |
|Takes an array of the validation errors and returns an exception object to be thrown.|
|Groups to be used during validation of the object.|
|If set to true, the validation will not use default messages. Error message always will be |
|Indicates if target should be exposed in |
|Indicates if validated value should be exposed in |
info Notice Find more information about the
class-validatorpackage in its repository.
We'll start by binding
ValidationPipe at the application level, thus ensuring all endpoints are protected from receiving incorrect data.
To test our pipe, let's create a basic endpoint.
info Hint Since TypeScript does not store metadata about generics or interfaces, when you use them in your DTOs,
ValidationPipemay not be able to properly validate incoming data. For this reason, consider using concrete classes in your DTOs.
Now we can add a few validation rules in our
CreateUserDto. We do this using decorators provided by the
class-validator package, described in detail here. In this fashion, any route that uses the
CreateUserDto will automatically enforce these validation rules.
With these rules in place, if a request hits our endpoint with an invalid
400 Bad Request code, along with the following response body:
In addition to validating request bodies, the
ValidationPipe can be used with other request object properties as well. Imagine that we would like to accept
:id in the endpoint path. To ensure that only numbers are accepted for this request parameter, we can use the following construct:
FindOneParams, like a DTO, is simply a class that defines validation rules using
class-validator. It would look like this:
Error messages can be helpful to explain what was incorrect in a request. However, some production environments prefer to disable detailed errors. Do this by passing an options object to the
As a result, detailed error messages won't be displayed in the response body.
ValidationPipe can also filter out properties that should not be received by the method handler. In this case, we can whitelist the acceptable properties, and any property not included in the whitelist is automatically stripped from the resulting object. For example, if our handler expects
password properties, but a request also includes an
age property, this property can be automatically removed from the resulting DTO. To enable such behavior, set
When set to true, this will automatically remove non-whitelisted properties (those without any decorator in the validation class).
Alternatively, you can stop the request from processing when non-whitelisted properties are present, and return an error response to the user. To enable this, set the
forbidNonWhitelisted option property to
true, in combination with setting
ValidationPipe can automatically transform payloads to be objects typed according to their DTO classes. To enable auto-transformation, set
true. This can be done at a method level:
To enable this behavior globally, set the option on a global pipe:
With the auto-transformation option enabled, the
ValidationPipe will also perform conversion of primitive types. In the following example, the
findOne() method takes one argument which represents an extracted
id path parameter:
By default, every path parameter and query parameter comes over the network as a
string. In the above example, we specified the
id type as a
number (in the method signature). Therefore, the
ValidationPipe will try to automatically convert a string identifier to a number.
In the above section, we showed how the
ValidationPipe can implicitly transform query and path parameters based on the expected type. However, this feature requires having auto-transformation enabled.
Alternatively (with auto-transformation disabled), you can explicitly cast values using the
ParseBoolPipe (note that
ParseStringPipe is not needed because, as mentioned earlier, every path parameter and query parameter comes over the network as a
string by default).
info Hint The
ParseBoolPipeare exported from the
As you build out features like CRUD (Create/Read/Update/Delete) it's often useful to construct variants on a base entity type. Nest provides several utility functions that perform type transformations to make this task more convenient.
Warning If your application uses the
@nestjs/swaggerpackage, see this chapter for more information about Mapped Types. Likewise, if you use the
@nestjs/graphqlpackage see this chapter. Both packages heavily rely on types and so they require a different import to be used. Therefore, if you used
@nestjs/mapped-types(instead of an appropriate one, either
@nestjs/graphqldepending on the type of your app), you may face various, undocumented side-effects.
When building input validation types (also called DTOs), it's often useful to build create and update variations on the same type. For example, the create variant may require all fields, while the update variant may make all fields optional.
Nest provides the
PartialType() utility function to make this task easier and minimize boilerplate.
PartialType() function returns a type (class) with all the properties of the input type set to optional. For example, suppose we have a create type as follows:
By default, all of these fields are required. To create a type with the same fields, but with each one optional, use
PartialType() passing the class reference (
CreateCatDto) as an argument:
info Hint The
PartialType()function is imported from the
PickType()function constructs a new type (class) by picking a set of properties from an input type. For example, suppose we start with a type like:
We can pick a set of properties from this class using the
PickType() utility function:
info Hint The
PickType()function is imported from the
OmitType()function constructs a type by picking all properties from an input type and then removing a particular set of keys. For example, suppose we start with a type like:
We can generate a derived type that has every property except
name as shown below. In this construct, the second argument to
OmitType is an array of property names.
info Hint The
OmitType()function is imported from the
IntersectionType()function combines two types into one new type (class). For example, suppose we start with two types like:
We can generate a new type that combines all properties in both types.
info Hint The
IntersectionType()function is imported from the
The type mapping utility functions are composable. For example, the following will produce a type (class) that has all of the properties of the
CreateCatDto type except for
name, and those properties will be set to optional:
TypeScript does not store metadata about generics or interfaces, so when you use them in your DTOs,
ValidationPipe may not be able to properly validate incoming data. For instance, in the following code,
createUserDtos won't be correctly validated:
To validate the array, create a dedicated class which contains a property that wraps the array, or use the
In addition, the
ParseArrayPipe may come in handy when parsing query parameters. Let's consider a
findByIds() method that returns users based on identifiers passed as query parameters.
This construction validates the incoming query parameters from an HTTP
GET request like the following:
While this chapter shows examples using HTTP style applications (e.g., Express or Fastify), the
ValidationPipe works the same for WebSockets and microservices, regardless of the transport method that is used.
Read more about custom validators, error messages, and available decorators as provided by the
class-validator package here.