Skip to content

Commit 21279e4

Browse files
kamilmysliwieckamilmysliwiec
authored
Merge pull request #1140 from johnbiundo/biundo/pipes-reorg
docs(validation) move vailidation pipe out to validation chapter
2 parents 20716b2 + a942834 commit 21279e4

File tree

2 files changed

+98
-96
lines changed

2 files changed

+98
-96
lines changed

‎content/pipes.md

Lines changed: 1 addition & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -445,97 +445,5 @@ We leave the implementation of this pipe to the reader, but note that like all o
445445

446446
#### The built-in ValidationPipe
447447

448-
Fortunately, you don't have to build these pipes on your own since the `ValidationPipe` and the `ParseIntPipe` are provided by Nest out-of-the-box. (Keep in mind that `ValidationPipe` requires both `class-validator` and `class-transformer` packages to be installed).
448+
Fortunately, you don't have to build these pipes on your own since the `ValidationPipe` (along with `ParseIntPipe`, `ParseBoolPipe`, `ParseArrayPipe` and `ParseUUIDPipe`) are provided by Nest out-of-the-box. The built-in `ValidationPipe` offers more options than in the sample we built in this chapter, which has been kept basic for the sake of illustrating the basic mechanics of a pipe. You can find full details, along with lots of examples [here](/techniques/validation).
449449

450-
The built-in `ValidationPipe` offers more options than in the sample we built in this chapter, which has been kept basic for the sake of illustrating the basic mechanics of a pipe. You can find lots of examples [here](/techniques/validation).
451-
452-
One such option is `transform`. Recall the earlier discussion about deserialized body objects being vanilla JavaScript objects (i.e., not having our DTO type). So far, we've used the pipe to validate our payload. You may recall that in the process, we used `class-transform` to temporarily convert our plain object into a typed object so that we could do the validation. The built-in ValidationPipe can also, optionally, return this converted object. We enable this behavior by passing in a configuration object to the pipe. For this option, pass a config object with the field `transform` with a value `true` as shown below:
453-
454-
```typescript
455-
@@filename(cats.controller)
456-
@Post()
457-
@UsePipes(new ValidationPipe({ transform: true }))
458-
async create(@Body() createCatDto: CreateCatDto) {
459-
this.catsService.create(createCatDto);
460-
}
461-
```
462-
463-
> info **Hint** The `ValidationPipe` is imported from the `@nestjs/common` package.
464-
465-
Because this pipe is based on the `class-validator` and `class-transformer` libraries, there are many additional options available. Like the `transform` option above, you configure these settings via a configuration object passed to the pipe. Following are the built-in options:
466-
467-
```typescript
468-
export interface ValidationPipeOptions extends ValidatorOptions {
469-
transform?: boolean;
470-
disableErrorMessages?: boolean;
471-
exceptionFactory?: (errors: ValidationError[]) => any;
472-
}
473-
```
474-
475-
In addition to these, all `class-validator` options (inherited from the `ValidatorOptions` interface) are available:
476-
477-
<table>
478-
<tr>
479-
<th>Option</th>
480-
<th>Type</th>
481-
<th>Description</th>
482-
</tr>
483-
<tr>
484-
<td><code>skipMissingProperties</code></td>
485-
<td><code>boolean</code></td>
486-
<td>If set to true, validator will skip validation of all properties that are missing in the validating object.</td>
487-
</tr>
488-
<tr>
489-
<td><code>whitelist</code></td>
490-
<td><code>boolean</code></td>
491-
<td>If set to true, validator will strip validated (returned) object of any properties that do not use any validation decorators.</td>
492-
</tr>
493-
<tr>
494-
<td><code>forbidNonWhitelisted</code></td>
495-
<td><code>boolean</code></td>
496-
<td>If set to true, instead of stripping non-whitelisted properties validator will throw an exception.</td>
497-
</tr>
498-
<tr>
499-
<td><code>forbidUnknownValues</code></td>
500-
<td><code>boolean</code></td>
501-
<td>If set to true, attempts to validate unknown objects fail immediately.</td>
502-
</tr>
503-
<tr>
504-
<td><code>disableErrorMessages</code></td>
505-
<td><code>boolean</code></td>
506-
<td>If set to true, validation errors will not be returned to the client.</td>
507-
</tr>
508-
<tr>
509-
<td><code>errorHttpStatusCode</code></td>
510-
<td><code>number</code></td>
511-
<td>This setting allows you to specify which exception type will be used in case of an error. By default it throws <code>BadRequestException</code>.</td>
512-
</tr>
513-
<tr>
514-
<td><code>exceptionFactory</code></td>
515-
<td><code>Function</code></td>
516-
<td>Takes an array of the validation errors and returns an exception object to be thrown.</td>
517-
</tr>
518-
<tr>
519-
<td><code>groups</code></td>
520-
<td><code>string[]</code></td>
521-
<td>Groups to be used during validation of the object.</td>
522-
</tr>
523-
<tr>
524-
<td><code>dismissDefaultMessages</code></td>
525-
<td><code>boolean</code></td>
526-
<td>If set to true, the validation will not use default messages. Error message always will be <code>undefined</code> if
527-
its not explicitly set.</td>
528-
</tr>
529-
<tr>
530-
<td><code>validationError.target</code></td>
531-
<td><code>boolean</code></td>
532-
<td>Indicates if target should be exposed in <code>ValidationError</code></td>
533-
</tr>
534-
<tr>
535-
<td><code>validationError.value</code></td>
536-
<td><code>boolean</code></td>
537-
<td>Indicates if validated value should be exposed in <code>ValidationError</code>.</td>
538-
</tr>
539-
</table>
540-
541-
> info **Notice** Find more information about the `class-validator` package in its [repository](https://github.com/typestack/class-validator).

‎content/techniques/validation.md

Lines changed: 97 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,90 @@ The `ValidationPipe` makes use of the powerful [class-validator](https://github.
1212

1313
#### Overview
1414

15-
In the [Pipes](/pipes) chapter, we went through the process of building simple pipes 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.
15+
In the [Pipes](/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.
16+
17+
#### Using the built-in ValidationPipe
18+
19+
> info **Hint** The `ValidationPipe` is imported from the `@nestjs/common` package.
20+
21+
Because this pipe uses the `class-validator` and `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:
22+
23+
```typescript
24+
export interface ValidationPipeOptions extends ValidatorOptions {
25+
transform?: boolean;
26+
disableErrorMessages?: boolean;
27+
exceptionFactory?: (errors: ValidationError[]) => any;
28+
}
29+
```
30+
31+
In addition to these, all `class-validator` options (inherited from the `ValidatorOptions` interface) are available:
32+
33+
<table>
34+
<tr>
35+
<th>Option</th>
36+
<th>Type</th>
37+
<th>Description</th>
38+
</tr>
39+
<tr>
40+
<td><code>skipMissingProperties</code></td>
41+
<td><code>boolean</code></td>
42+
<td>If set to true, validator will skip validation of all properties that are missing in the validating object.</td>
43+
</tr>
44+
<tr>
45+
<td><code>whitelist</code></td>
46+
<td><code>boolean</code></td>
47+
<td>If set to true, validator will strip validated (returned) object of any properties that do not use any validation decorators.</td>
48+
</tr>
49+
<tr>
50+
<td><code>forbidNonWhitelisted</code></td>
51+
<td><code>boolean</code></td>
52+
<td>If set to true, instead of stripping non-whitelisted properties validator will throw an exception.</td>
53+
</tr>
54+
<tr>
55+
<td><code>forbidUnknownValues</code></td>
56+
<td><code>boolean</code></td>
57+
<td>If set to true, attempts to validate unknown objects fail immediately.</td>
58+
</tr>
59+
<tr>
60+
<td><code>disableErrorMessages</code></td>
61+
<td><code>boolean</code></td>
62+
<td>If set to true, validation errors will not be returned to the client.</td>
63+
</tr>
64+
<tr>
65+
<td><code>errorHttpStatusCode</code></td>
66+
<td><code>number</code></td>
67+
<td>This setting allows you to specify which exception type will be used in case of an error. By default it throws <code>BadRequestException</code>.</td>
68+
</tr>
69+
<tr>
70+
<td><code>exceptionFactory</code></td>
71+
<td><code>Function</code></td>
72+
<td>Takes an array of the validation errors and returns an exception object to be thrown.</td>
73+
</tr>
74+
<tr>
75+
<td><code>groups</code></td>
76+
<td><code>string[]</code></td>
77+
<td>Groups to be used during validation of the object.</td>
78+
</tr>
79+
<tr>
80+
<td><code>dismissDefaultMessages</code></td>
81+
<td><code>boolean</code></td>
82+
<td>If set to true, the validation will not use default messages. Error message always will be <code>undefined</code> if
83+
its not explicitly set.</td>
84+
</tr>
85+
<tr>
86+
<td><code>validationError.target</code></td>
87+
<td><code>boolean</code></td>
88+
<td>Indicates if target should be exposed in <code>ValidationError</code></td>
89+
</tr>
90+
<tr>
91+
<td><code>validationError.value</code></td>
92+
<td><code>boolean</code></td>
93+
<td>Indicates if validated value should be exposed in <code>ValidationError</code>.</td>
94+
</tr>
95+
</table>
96+
97+
> info **Notice** Find more information about the `class-validator` package in its [repository](https://github.com/typestack/class-validator).
98+
1699

17100
#### Auto-validation
18101

@@ -36,7 +119,7 @@ create(@Body() createUserDto: CreateUserDto) {
36119
}
37120
```
38121

39-
> info **Hint** Since TypeScript does not store metadata about **generics or interfaces**, when you use them in your DTOs, `ValidationPipe` may not be able to properly validate incoming data.
122+
> info **Hint** Since TypeScript does not store metadata about **generics or interfaces**, when you use them in your DTOs, `ValidationPipe` may not be able to properly validate incoming data. For this reason, consider using concrete classes in your DTOs.
40123
41124
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](https://github.com/typestack/class-validator#validation-decorators). In this fashion, any route that uses the `CreateUserDto` will automatically enforce these validation rules.
42125

@@ -116,7 +199,18 @@ Alternatively, you can stop the request from processing when non-whitelisted pro
116199

117200
#### Transform payload objects
118201

119-
Payloads coming in over the network are plain JavaScript objects. The `ValidationPipe` can automatically transform payloads to be objects typed according to their DTO classes. To enable auto-transformation, set `transform` to `true`.
202+
Payloads coming in over the network are plain JavaScript objects. The `ValidationPipe` can automatically transform payloads to be objects typed according to their DTO classes. To enable auto-transformation, set `transform` to `true`. This can be done at a method level:
203+
204+
```typescript
205+
@@filename(cats.controller)
206+
@Post()
207+
@UsePipes(new ValidationPipe({ transform: true }))
208+
async create(@Body() createCatDto: CreateCatDto) {
209+
this.catsService.create(createCatDto);
210+
}
211+
```
212+
213+
To enable this behavior globally, set the option on a global pipe:
120214

121215
```typescript
122216
app.useGlobalPipes(

0 commit comments

Comments
 (0)