À propos de ce cours
Objectifs de la leçon
- Situer les pipes dans le traitement d'une requête.
- Connaître l'interface PipeTransform et ArgumentMetadata.
- Distinguer un pipe de transformation d'un pipe de validation.
- Enchaîner plusieurs pipes sur un argument.
- Appliquer un pipe à un paramètre, une méthode, un contrôleur ou toute l'application.
Définition
Un pipe est une classe @Injectable() qui implémente l'interface PipeTransform. NestJS lui confie chaque argument d'un handler (paramètre de route, query string, corps…) juste avant d'appeler ce handler. Le pipe a deux usages :
- transformer: convertir la donnée dans la forme attendue (le texte
"42"devient le nombre42) ; - valider: vérifier la donnée et, si elle est incorrecte, lever une exception (par défaut 400 Bad Request).
Vous en utilisez déjà un depuis le chapitre 06 : ParseIntPipe fait les deux à la fois.
Les pipes s'exécutent en dernier, juste avant le handler.
L'interface PipeTransform
export interface PipeTransform<T = any, R = any> {
transform(value: T, metadata: ArgumentMetadata): R; // peut aussi renvoyer une Promise<R>
}
export interface ArgumentMetadata {
type: 'body' | 'query' | 'param' | 'custom'; // d'où vient l'argument
metatype?: Type<unknown>; // le type déclaré dans le handler
data?: string; // le nom passé au décorateur : @Param('id') → 'id'
}
Pour voir ces informations concrètement, écrivons un pipe « espion » qui affiche ce qu'il reçoit et renvoie la valeur sans la modifier :
📄 src/espion.pipe.ts
import { ArgumentMetadata, Injectable, PipeTransform } from '@nestjs/common';
@Injectable()
export class EspionPipe implements PipeTransform {
transform(value: unknown, metadata: ArgumentMetadata) {
console.log(
` [EspionPipe] type=${metadata.type} data=${metadata.data ?? '(tout)'} ` +
`metatype=${metadata.metatype?.name} valeur=${JSON.stringify(value)}`,
);
return value; // renvoie la valeur sans la modifier
}
}
Deux pipes : transformer, puis valider
📄 src/groupe.pipes.ts
import { ArgumentMetadata, BadRequestException, Injectable, PipeTransform } from '@nestjs/common';
// Pipe de TRANSFORMATION : renvoie une valeur modifiée
@Injectable()
export class MajusculesPipe implements PipeTransform<string, string> {
transform(value: string, metadata: ArgumentMetadata): string {
return value.trim().toUpperCase();
}
}
// Pipe de VALIDATION : renvoie la valeur telle quelle… ou lève une exception
@Injectable()
export class CodeGroupePipe implements PipeTransform<string, string> {
transform(value: string): string {
if (!/^[A-Z]{3}\d{3}$/.test(value)) {
throw new BadRequestException(`Code de groupe invalide : « ${value} » (attendu : 3 lettres et 3 chiffres, ex. DEV101)`);
}
return value;
}
}
📄 src/demo.controller.ts
import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
import { EspionPipe } from './espion.pipe';
import { CodeGroupePipe, MajusculesPipe } from './groupe.pipes';
class CreerNoteDto {
matiere: string;
valeur: number;
}
let appelsDuHandler = 0;
@Controller('demo')
export class DemoController {
@Post('notes/:id')
ajouter(
@Param('id', EspionPipe) id: string,
@Query('session', EspionPipe) session: string,
@Body(EspionPipe) dto: CreerNoteDto,
) {
return { id, session, dto };
}
@Get('groupes/:code')
groupe(@Param('code', MajusculesPipe, CodeGroupePipe) code: string) { // les pipes s'enchaînent de gauche à droite
appelsDuHandler++;
return { code, appelsDuHandler };
}
}
await appel('POST', '/api/demo/notes/7?session=principale', { corps: { matiere: 'SQL', valeur: 15 } });
await appel('GET', '/api/demo/groupes/%20dev101%20'); // « dev101 » entouré d'espaces
await appel('GET', '/api/demo/groupes/info-2');
await appel('GET', '/api/demo/groupes/dev102');
Résultat réellement obtenu :
[EspionPipe] type=body data=(tout) metatype=CreerNoteDto valeur={"matiere":"SQL","valeur":15}
[EspionPipe] type=query data=session metatype=String valeur="principale"
[EspionPipe] type=param data=id metatype=String valeur="7"
POST /api/demo/notes/7?session=principale → 201 {"id":"7","session":"principale","dto":{"matiere":"SQL","valeur":15}}
GET /api/demo/groupes/%20dev101%20 → 200 {"code":"DEV101","appelsDuHandler":1}
GET /api/demo/groupes/info-2 → 400 {"message":"Code de groupe invalide : « INFO-2 » (attendu : 3 lettres et 3 chiffres, ex. DEV101)","error":"Bad Request","statusCode":400}
GET /api/demo/groupes/dev102 → 200 {"code":"DEV102","appelsDuHandler":2}
Ce qu'il faut observer
- metadata.type vaut
body,queryouparamselon le décorateur ; data est le nom passé au décorateur (undefinedpour@Body()sans nom, qui reçoit tout le corps). - metatype vaut
CreerNoteDtopour le corps : c'est grâce à cela que leValidationPipesaura quelles règles appliquer. Pourid: string, c'estString. - La valeur de
idest"7", une chaîne: tout ce qui vient de l'URL est du texte. - Les arguments sont traités du dernier au premier (body, puis query, puis param) : c'est un détail d'implémentation, ne vous appuyez pas dessus.
- Pour
@Param('code', MajusculesPipe, CodeGroupePipe), les pipes s'enchaînent de gauche à droite: le résultat du premier ("DEV101") est passé au second. - Pour
info-2,CodeGroupePipelève une exception : réponse 400, etappelsDuHandlerpasse directement de 1 à 2 à la requête suivante. Le handler n'a pas été exécuté.
Règle d'or: quand un handler s'exécute, ses arguments ont déjà été transformés et validés. Le code du handler et du service peut donc faire confiance aux données, sans répéter les vérifications.
Les quatre niveaux d'application
| Niveau | Syntaxe | S'applique à |
|---|---|---|
| Paramètre | @Param('id', ParseIntPipe) | cet argument seulement |
| Méthode | @UsePipes(MonPipe) au-dessus du handler | tous les arguments de ce handler |
| Contrôleur | @UsePipes(MonPipe) au-dessus de la classe | tous les arguments de tous ses handlers |
| Global | app.useGlobalPipes(new MonPipe()) dans main.ts, ou provider APP_PIPE (leçon 8.6) | tous les arguments de toute l'application |
Ordre d'exécution pour un argument : global → contrôleur → méthode → paramètre (vérifié à la leçon 5.4). On peut passer une classe (ParseIntPipe), NestJS crée alors l'instance et peut lui injecter des dépendances, ou une instance (new ParseIntPipe({ … })) pour fournir des options.
Attention aux pipes de méthode, de contrôleur ou globaux: ils reçoivent tous les arguments, y compris ceux qui ne les concernent pas. Un pipe qui met en majuscules, appliqué avec @UsePipes, planterait sur le corps (un objet n'a pas de méthode toUpperCase). Un pipe destiné à ces niveaux doit tester metadata.type ou le type de la valeur.
Activités
Activité 1 Lire ArgumentMetadata
Pour le handler rechercher(@Query() filtre: FiltreDto, @Headers('x-langue') langue: string) sur lequel on place @UsePipes(EspionPipe), que va afficher l'espion pour chaque argument ?
Voir le corrigé
L'espion n'affiche qu'une ligne, pour @Query(): type=query data=(tout) metatype=FiltreDto. Les en-têtes ne passent pas par les pipes: @Headers() n'accepte d'ailleurs aucun pipe en argument (@Headers('x-langue', MonPipe) ne compile pas : « Expected 0-1 arguments, but got 2 »). Pour valider un en-tête, on le vérifie dans le handler, ou on écrit un décorateur de paramètre personnalisé (leçon 5.4), qui, lui, accepte des pipes.
Activité 2 Un pipe de transformation
Écrivez SlugPipe qui transforme un texte en « slug » : minuscules, accents supprimés, espaces remplacés par des tirets ("Développement Web" donne "developpement-web"). Utilisez-le sur GET /api/formations/:intitule.
Voir le corrigé
@Injectable()
export class SlugPipe implements PipeTransform<string, string> {
transform(value: string): string {
return value
.normalize('NFD').replace(/[̀-ͯ]/g, '') // supprime les accents
.toLowerCase().trim()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-|-$/g, '');
}
}
@Get(':intitule')
trouver(@Param('intitule', SlugPipe) slug: string) { … }
Activité 3 Ordre des pipes enchaînés
Qu'obtient-on pour GET /api/demo/groupes/%20dev101%20 si on inverse l'ordre : @Param('code', CodeGroupePipe, MajusculesPipe)? Expliquez.
Voir le corrigé
400 : CodeGroupePipe reçoit d'abord la valeur brute " dev101 " (minuscules et espaces), qui ne respecte pas l'expression ^[A-Z]{3}\d{3}$. L'ordre compte : on normalise d'abord, puis on valide.
Activité 4 Un pipe sûr au niveau méthode
Réécrivez MajusculesPipe pour qu'il puisse être utilisé avec @UsePipes() sans faire planter les autres arguments : il ne doit transformer que les valeurs de type chaîne venant de param.
Voir le corrigé
@Injectable()
export class MajusculesPipe implements PipeTransform {
transform(value: unknown, metadata: ArgumentMetadata) {
if (metadata.type === 'param' && typeof value === 'string') {
return value.trim().toUpperCase();
}
return value; // les autres arguments passent sans modification
}
}
À retenir
- Un pipe reçoit chaque argument juste avant le handler, pour le transformer ou le valider.
- PipeTransform.transform(value, metadata) renvoie la valeur (transformée) ou lève une exception.
- ArgumentMetadata : type (body, query, param, custom), data (nom), metatype (type déclaré).
- Si un pipe lève une exception, le handler n'est pas exécuté.
- Plusieurs pipes sur un argument s'enchaînent de gauche à droite.
- Niveaux : paramètre, méthode, contrôleur, global (ordre : global → contrôleur → méthode → paramètre).
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !