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

Création d'un pipe personnalisé

Cette leçon apprend à écrire ses propres pipes NestJS. Quatre exemples exécutés couvrent les cas courants : un pipe de transformation qui nettoie récursivement les chaînes d'un corps, un pipe qui vali...

0 chapitres 0 QCM Accès gratuit
Création d'un pipe personnalisé

À propos de ce cours

Cette leçon apprend à écrire ses propres pipes NestJS. Quatre exemples exécutés couvrent les cas courants : un pipe de transformation qui nettoie récursivement les chaînes d'un corps, un pipe qui valide et normalise un numéro de CIN tunisien, un pipe configurable qui reçoit un barème en option, et un pipe qui injecte un service pour transformer un identifiant en stagiaire complet ou répondre 404. La leçon explique la différence entre passer une classe et une instance, l'enregistrement de pipes globaux avec APP_PIPE et les cas où un pipe n'est pas la bonne solution. Activités corrigées.

Objectifs de la leçon

  • Écrire un pipe de transformation et un pipe de validation.
  • Rendre un pipe configurable par des options.
  • Injecter un service dans un pipe.
  • Enregistrer des pipes globaux avec APP_PIPE.
  • Savoir quand un pipe n'est pas l'outil adapté.

Trois familles de pipes personnalisés

Transformer, valider, enrichir : un pipe = une responsabilité.

La structure d'un pipe
nest g pipe common/pipes/parse-cin --no-spec      # crée parse-cin.pipe.ts
@Injectable()
export class MonPipe implements PipeTransform<TypeEntree, TypeSortie> {
  transform(value: TypeEntree, metadata: ArgumentMetadata): TypeSortie {   // ou Promise<TypeSortie>
    // 1. vérifier → sinon throw new BadRequestException(...)
    // 2. transformer → return nouvelleValeur
  }
}
1. Un pipe de transformation : nettoyer les chaînes

Les formulaires envoient souvent des espaces en trop. Ce pipe parcourt récursivement la valeur (objets, tableaux) et nettoie toutes les chaînes :

📄 src/common/pipes/nettoyer-chaines.pipe.ts

import { Injectable, PipeTransform } from '@nestjs/common';

// Nettoie récursivement toutes les chaînes d'un objet (espaces en trop)
@Injectable()
export class NettoyerChainesPipe implements PipeTransform {
  transform(value: unknown): unknown {
    if (typeof value === 'string') return value.trim().replace(/\s+/g, ' ');
    if (Array.isArray(value)) return value.map((v) => this.transform(v));
    if (value && typeof value === 'object') {
      return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, this.transform(v)]));
    }
    return value;
  }
}
2. Un pipe de validation qui normalise : le CIN

📄 src/common/pipes/parse-cin.pipe.ts

import { BadRequestException, Injectable, PipeTransform } from '@nestjs/common';

// Valide et normalise un numéro de CIN tunisien (8 chiffres)
@Injectable()
export class ParseCinPipe implements PipeTransform<string, string> {
  transform(value: string): string {
    const cin = (value ?? '').replace(/[\s.-]/g, '');            // accepte « 01 234 567 » ou « 01-234-567 »
    if (!/^\d{8}$/.test(cin)) {
      throw new BadRequestException(`CIN invalide : « ${value} ». Un CIN contient exactement 8 chiffres.`);
    }
    return cin;
  }
}
3. Un pipe configurable : le barème d'une note

Un pipe peut recevoir des options dans son constructeur. On l'utilise alors avec new, comme new ParseIntPipe({ … }):

📄 src/common/pipes/parse-note.pipe.ts

import { BadRequestException, Injectable, PipeTransform } from '@nestjs/common';

// Pipe configurable : on lui passe le barème au moment de l'utiliser
@Injectable()
export class ParseNotePipe implements PipeTransform<string, number> {
  constructor(private readonly bareme = 20) {}

  transform(value: string): number {
    const note = Number(String(value).replace(',', '.'));      // accepte « 14,5 »
    if (Number.isNaN(note) || note < 0 || note > this.bareme) {
      throw new BadRequestException(`La note doit être un nombre entre 0 et ${this.bareme} (reçu : « ${value} »)`);
    }
    return Math.round(note * 4) / 4;                            // arrondi au quart de point
  }
}
4. Un pipe qui injecte un service

Un pipe est un provider comme un autre : il peut recevoir des dépendances. Celui-ci transforme un identifiant en stagiaire complet, ou répond 404 :

📄 src/stagiaires/stagiaires.service.ts

import { Injectable } from '@nestjs/common';

export interface Stagiaire {
  id: number;
  nom: string;
  groupe: string;
}

@Injectable()
export class StagiairesService {
  private readonly stagiaires: Stagiaire[] = [
    { id: 1, nom: 'Ben Ali', groupe: 'DEV101' },
    { id: 2, nom: 'Trabelsi', groupe: 'DEV102' },
  ];
  trouver(id: number): Stagiaire | undefined {
    return this.stagiaires.find((s) => s.id === id);
  }
}

📄 src/stagiaires/stagiaire-par-id.pipe.ts

import { Injectable, NotFoundException, PipeTransform } from '@nestjs/common';
import { Stagiaire, StagiairesService } from './stagiaires.service';

// Pipe qui reçoit une DÉPENDANCE : il transforme un identifiant en stagiaire complet
@Injectable()
export class StagiaireParIdPipe implements PipeTransform<string, Stagiaire> {
  constructor(private readonly stagiairesService: StagiairesService) {}

  transform(value: string): Stagiaire {
    const id = Number(value);
    const stagiaire = Number.isInteger(id) ? this.stagiairesService.trouver(id) : undefined;
    if (!stagiaire) throw new NotFoundException(`Stagiaire ${value} introuvable`);
    return stagiaire;
  }
}

Le contrôleur utilise les quatre pipes :

📄 src/stagiaires/stagiaires.controller.ts

import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
import { NettoyerChainesPipe } from './nettoyer-chaines.pipe';
import { ParseCinPipe } from './parse-cin.pipe';
import { ParseNotePipe } from './parse-note.pipe';
import { StagiaireParIdPipe } from './stagiaire-par-id.pipe';
import { Stagiaire } from './stagiaires.service';

@Controller('stagiaires')
export class StagiairesController {
  @Post()
  creer(@Body(NettoyerChainesPipe) body: { nom: string; prenom: string; competences: string[] }) {
    return body;
  }

  @Get('cin/:cin')
  parCin(@Param('cin', ParseCinPipe) cin: string) {
    return { cin };
  }

  @Get(':id')
  findOne(@Param('id', StagiaireParIdPipe) stagiaire: Stagiaire) {      // le handler reçoit directement le stagiaire
    return stagiaire;
  }

  @Get(':id/simulation')
  simulation(
    @Param('id', StagiaireParIdPipe) stagiaire: Stagiaire,
    @Query('note', new ParseNotePipe(20)) note: number,
    @Query('bonus', new ParseNotePipe(2)) bonus: number,
  ) {
    return { stagiaire: stagiaire.nom, note, bonus, total: Math.min(20, note + bonus) };
  }
}
await appel('POST', '/api/stagiaires', { corps: { nom: '  Ben   Ali ', prenom: 'Sami  ', competences: [' HTML', 'CSS  '] } });
await appel('GET', '/api/stagiaires/cin/01%20234%20567');     // « 01 234 567 »
await appel('GET', '/api/stagiaires/cin/1234');
await appel('GET', '/api/stagiaires/2');
await appel('GET', '/api/stagiaires/9');
await appel('GET', '/api/stagiaires/1/simulation?note=14,6&bonus=1.5');
await appel('GET', '/api/stagiaires/1/simulation?note=21&bonus=1');
await appel('GET', '/api/stagiaires/1/simulation?note=19&bonus=3');

Résultat réellement obtenu :

POST /api/stagiaires → 201 {"nom":"Ben Ali","prenom":"Sami","competences":["HTML","CSS"]}
GET /api/stagiaires/cin/01%20234%20567 → 200 {"cin":"01234567"}
GET /api/stagiaires/cin/1234 → 400 {"message":"CIN invalide : « 1234 ». Un CIN contient exactement 8 chiffres.","error":"Bad Request","statusCode":400}
GET /api/stagiaires/2 → 200 {"id":2,"nom":"Trabelsi","groupe":"DEV102"}
GET /api/stagiaires/9 → 404 {"message":"Stagiaire 9 introuvable","error":"Not Found","statusCode":404}
GET /api/stagiaires/1/simulation?note=14,6&bonus=1.5 → 200 {"stagiaire":"Ben Ali","note":14.5,"bonus":1.5,"total":16}
GET /api/stagiaires/1/simulation?note=21&bonus=1 → 400 {"message":"La note doit être un nombre entre 0 et 20 (reçu : « 21 »)","error":"Bad Request","statusCode":400}
GET /api/stagiaires/1/simulation?note=19&bonus=3 → 400 {"message":"La note doit être un nombre entre 0 et 2 (reçu : « 3 »)","error":"Bad Request","statusCode":400}
Ce qu'il faut observer
  • Le corps est nettoyé à tous les niveaux, y compris dans le tableau.
  • ParseCinPipe accepte une saisie avec espaces et renvoie toujours le format normalisé : le service ne reçoit que des CIN propres.
  • findOne reçoit directement un objet Stagiaire: la recherche et le 404 ont été faits par le pipe. Plusieurs routes (findOne, simulation…) partagent ce comportement sans le répéter.
  • Le même ParseNotePipe est utilisé avec deux barèmes (20 et 2). "14,6" est accepté (virgule française) et arrondi au quart de point : 14.5.
Classe ou instance : une différence importante
ÉcritureQui crée le pipe ?Conséquence
@Param('id', StagiaireParIdPipe)NestJSles dépendances du constructeur sont injectées; le service doit être disponible dans le module du contrôleur
@Query('note', new ParseNotePipe(20))vousaucune injection : vous passez vous-même les arguments du constructeur

Un pipe qui a des dépendances doit donc être passé comme classe. Inversement, si on passait ParseNotePipe comme classe, NestJS chercherait un provider pour le paramètre bareme et l'application ne démarrerait pas : c'est exactement le piège de ParseDatePipe vu à la leçon 8.3.

Des pipes globaux avec APP_PIPE

app.useGlobalPipes(new MonPipe()) crée le pipe hors du conteneur: il ne peut pas recevoir de dépendances. Pour un pipe global qui a besoin d'un service (ou pour le déclarer dans un module plutôt que dans main.ts), on utilise le jeton APP_PIPE de @nestjs/core:

📄 src/app.module.ts

import { Module, ValidationPipe } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
import { NettoyerChainesPipe } from './nettoyer-chaines.pipe';
import { GroupesController } from './groupes.controller';
import { StagiairesService } from './stagiaires.service';

@Module({
  controllers: [GroupesController],
  providers: [
    StagiairesService,
    { provide: APP_PIPE, useClass: NettoyerChainesPipe },                         // 1er pipe global
    { provide: APP_PIPE, useValue: new ValidationPipe({ whitelist: true }) },     // 2e pipe global
  ],
})
export class AppModule {}

📄 src/groupes.controller.ts

import { Body, Controller, Post } from '@nestjs/common';
import { IsString, Length } from 'class-validator';

class CreerGroupeDto {
  @IsString()
  @Length(6, 6)
  code: string;

  @IsString()
  intitule: string;
}

@Controller('groupes')
export class GroupesController {
  @Post()
  creer(@Body() dto: CreerGroupeDto) {          // aucun pipe ici : ils sont globaux
    return dto;
  }
}

Résultat réellement obtenu :

POST /api/groupes → 201 {"code":"DEV101","intitule":"Développement web"}
POST /api/groupes → 400 {"message":["code must be longer than or equal to 6 characters"],"error":"Bad Request","statusCode":400}

Les deux pipes globaux s'appliquent dans l'ordre de déclaration: le nettoyage d'abord (" DEV101 " devient "DEV101", qui fait bien 6 caractères), puis la validation. La propriété extra a été retirée par whitelist. Un pipe déclaré avec APP_PIPE est global même s'il est déclaré dans un module de fonctionnalité.

Quand ne pas utiliser un pipe ? Un pipe travaille sur un argument isolé. Une règle qui compare plusieurs arguments (date de fin après la date de début, pour deux paramètres distincts) ou qui relève du métier (« un groupe complet n'accepte plus d'inscription ») appartient au service. Les pipes servent au format et à la conversion des données d'entrée ; pour les droits d'accès, ce sont les guards (chapitre 09).

Activités

Activité 1 ParseMatriculePipe

Écrivez un pipe qui accepte un matricule de la forme stg-2026-7 ou STG-2026-0007 (insensible à la casse, numéro de 1 à 4 chiffres) et renvoie toujours STG-2026-0007. Toute autre forme donne 400.

Voir le corrigé
@Injectable()
export class ParseMatriculePipe implements PipeTransform<string, string> {
  transform(value: string): string {
    const m = /^stg-(\d{4})-(\d{1,4})$/i.exec((value ?? '').trim());
    if (!m) throw new BadRequestException(`Matricule invalide : « ${value} » (format attendu : STG-AAAA-NNNN)`);
    return `STG-${m[1]}-${m[2].padStart(4, '0')}`;
  }
}

Ce pipe sera utilisé dans le TP 5.

Activité 2 Un pipe asynchrone

Modifiez StagiaireParIdPipe en supposant que trouver() devient asynchrone (Promise<Stagiaire | undefined>), comme ce sera le cas avec une base de données au chapitre 11. Que faut-il changer ?

Voir le corrigé
@Injectable()
export class StagiaireParIdPipe implements PipeTransform<string, Promise<Stagiaire>> {
  constructor(private readonly stagiairesService: StagiairesService) {}

  async transform(value: string): Promise<Stagiaire> {
    const id = Number(value);
    const stagiaire = Number.isInteger(id) ? await this.stagiairesService.trouver(id) : undefined;
    if (!stagiaire) throw new NotFoundException(`Stagiaire ${value} introuvable`);
    return stagiaire;
  }
}

Il suffit de rendre transform asynchrone : NestJS attend la promesse avant d'appeler le handler. Rien ne change dans le contrôleur.

Activité 3 Paramétrer par une option

Ajoutez à NettoyerChainesPipe une option { majuscules?: string[] }: les propriétés listées sont en plus mises en majuscules (par exemple ['groupe', 'code']). Utilisez-le ponctuellement avec new.

Voir le corrigé
@Injectable()
export class NettoyerChainesPipe implements PipeTransform {
  constructor(private readonly options: { majuscules?: string[] } = {}) {}

  transform(value: unknown, _meta?: ArgumentMetadata, cle?: string): unknown {
    if (typeof value === 'string') {
      const propre = value.trim().replace(/\s+/g, ' ');
      return cle && this.options.majuscules?.includes(cle) ? propre.toUpperCase() : propre;
    }
    if (Array.isArray(value)) return value.map((v) => this.transform(v, _meta, cle));
    if (value && typeof value === 'object') {
      return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, this.transform(v, _meta, k)]));
    }
    return value;
  }
}

// @Body(new NettoyerChainesPipe({ majuscules: ['groupe'] })) dto: CreerStagiaireDto

Attention : avec un constructeur à paramètre, ce pipe ne peut plus être déclaré comme classe (APP_PIPE avec useClass) ; utilisez useValue: new NettoyerChainesPipe().

Activité 4 Pipe ou service ?

Pour chaque règle, dites s'il faut un pipe, un DTO validé ou le service : (a) l'identifiant est un entier ; (b) l'e-mail n'est pas déjà utilisé ; (c) le code postal a 4 chiffres ; (d) un stagiaire ne peut pas avoir plus de 3 absences non justifiées pour s'inscrire à l'examen ; (e) le matricule est mis au format STG-AAAA-NNNN.

Voir le corrigé

(a) Pipe natif (ParseIntPipe). (b) Service : il faut consulter les données existantes, et c'est une règle métier (409 Conflict). (c) DTO validé (@Matches). (d) Service : règle métier. (e) Pipe personnalisé (normalisation d'un paramètre).

À retenir

  • Un pipe personnalisé : @Injectable() + PipeTransform + transform() qui renvoie ou lève une exception.
  • Trois usages : transformer (nettoyer), valider et normaliser (CIN, matricule), enrichir (id → entité, avec injection).
  • Options → constructeur et utilisation avec new ; dépendances → passer la classe pour que NestJS injecte.
  • transform() peut être async : NestJS attend la promesse.
  • Pipes globaux avec dépendances : { provide: APP_PIPE, useClass: … }, appliqués dans l'ordre de déclaration.
  • Les règles métier et celles qui comparent plusieurs arguments restent dans le service.

Cet article vous a-t-il aidé ?