Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les pipes NestJS : transformation et validation

Cette leçon explique ce qu'est un pipe dans NestJS : une classe qui reçoit chaque argument d'un handler juste avant son appel, pour le transformer ou le valider. Un pipe espion exécuté montre le conte...

0 chapitres 0 QCM Accès gratuit
Les pipes NestJS : transformation et validation

À propos de ce cours

Cette leçon explique ce qu'est un pipe dans NestJS : une classe qui reçoit chaque argument d'un handler juste avant son appel, pour le transformer ou le valider. Un pipe espion exécuté montre le contenu réel de ArgumentMetadata (type, data, metatype) pour un paramètre de route, une query string et un corps. Deux pipes enchaînés illustrent la différence entre transformation et validation et prouvent que le handler n'est pas appelé en cas d'erreur. La leçon présente enfin les quatre niveaux d'application (paramètre, méthode, contrôleur, global) et l'ordre d'exécution. Activités corrigées.

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 nombre 42) ;
  • 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.

Position des pipes dans le cycle de requête NestJS

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, query ou param selon le décorateur ; data est le nom passé au décorateur (undefined pour @Body() sans nom, qui reçoit tout le corps).
  • metatype vaut CreerNoteDto pour le corps : c'est grâce à cela que le ValidationPipe saura quelles règles appliquer. Pour id: string, c'est String.
  • La valeur de id est "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, CodeGroupePipe lève une exception : réponse 400, et appelsDuHandler passe 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
NiveauSyntaxeS'applique à
Paramètre@Param('id', ParseIntPipe)cet argument seulement
Méthode@UsePipes(MonPipe) au-dessus du handlertous les arguments de ce handler
Contrôleur@UsePipes(MonPipe) au-dessus de la classetous les arguments de tous ses handlers
Globalapp.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é ?