À propos de ce cours
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é.
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.
ParseCinPipeaccepte une saisie avec espaces et renvoie toujours le format normalisé : le service ne reçoit que des CIN propres.findOnereçoit directement un objetStagiaire: 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
ParseNotePipeest 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
| Écriture | Qui crée le pipe ? | Conséquence |
|---|---|---|
@Param('id', StagiaireParIdPipe) | NestJS | les dépendances du constructeur sont injectées; le service doit être disponible dans le module du contrôleur |
@Query('note', new ParseNotePipe(20)) | vous | aucune 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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !