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

Les pipes natifs (ParseIntPipe, ParseUUIDPipe, DefaultValuePipe…)

Cette leçon passe en revue les pipes fournis par NestJS 11 : ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, ParseDatePipe et DefaultValuePipe. Une vingtaine...

0 chapitres 0 QCM Accès gratuit
Les pipes natifs (ParseIntPipe, ParseUUIDPipe, DefaultValuePipe…)

À propos de ce cours

Cette leçon passe en revue les pipes fournis par NestJS 11 : ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, ParseDatePipe et DefaultValuePipe. Une vingtaine de requêtes exécutées montrent pour chacun la valeur obtenue et le message d'erreur réel. La leçon présente les options communes (optional, errorHttpStatusCode, exceptionFactory), la combinaison DefaultValuePipe et ParseIntPipe pour la pagination, et un piège de NestJS 11 : ParseDatePipe doit être instancié. Activités corrigées.

Objectifs de la leçon

  • Connaître les pipes natifs de NestJS et leur usage.
  • Lire les messages d'erreur qu'ils produisent.
  • Configurer un pipe natif avec ses options.
  • Donner une valeur par défaut à un paramètre facultatif.

Les pipes natifs de NestJS

Chaque pipe transforme le texte reçu dans le type attendu, ou refuse la requête.

Les pipes natifs

Ils sont tous exportés par @nestjs/common. Les pipes Parse* font à la fois la validation et la transformation ; DefaultValuePipe fournit une valeur quand le paramètre est absent. Un seul contrôleur les montre tous :

📄 src/natifs.controller.ts

import {
  Controller, DefaultValuePipe, Get, HttpStatus, Param, ParseArrayPipe, ParseBoolPipe, ParseDatePipe,
  ParseEnumPipe, ParseFloatPipe, ParseIntPipe, ParseUUIDPipe, Query,
} from '@nestjs/common';

enum Session {
  Principale = 'principale',
  Controle = 'controle',
}

@Controller('natifs')
export class NatifsController {
  @Get('entier/:id')
  entier(@Param('id', ParseIntPipe) id: number) {
    return { id, type: typeof id };
  }

  @Get('entier-406/:id')
  entier406(@Param('id', new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE })) id: number) {
    return { id };
  }

  @Get('reel')
  reel(@Query('note', ParseFloatPipe) note: number) {
    return { note, surVingt: note <= 20 };
  }

  @Get('booleen')
  booleen(@Query('actifs', new ParseBoolPipe({ optional: true })) actifs?: boolean) {
    return { actifs: actifs ?? 'non précisé' };
  }

  @Get('uuid/:ref')
  uuid(@Param('ref', new ParseUUIDPipe({ version: '4' })) ref: string) {
    return { ref };
  }

  @Get('session/:s')
  session(@Param('s', new ParseEnumPipe(Session)) s: Session) {
    return { session: s };
  }

  @Get('liste')
  liste(@Query('ids', new ParseArrayPipe({ items: Number, separator: ',' })) ids: number[]) {
    return { ids, somme: ids.reduce((a, b) => a + b, 0) };
  }

  @Get('date')
  date(@Query('du', new ParseDatePipe()) du: Date) {
    return { du: du.toISOString(), estUneDate: du instanceof Date };
  }

  @Get('page')
  page(
    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
    @Query('limite', new DefaultValuePipe(10), ParseIntPipe) limite: number,
  ) {
    return { page, limite };
  }
}
await appel('GET', '/api/natifs/entier/42');
await appel('GET', '/api/natifs/entier/abc');
await appel('GET', '/api/natifs/entier/4.5');
await appel('GET', '/api/natifs/entier-406/abc');
await appel('GET', '/api/natifs/reel?note=14.75');
await appel('GET', '/api/natifs/reel');
await appel('GET', '/api/natifs/booleen?actifs=true');
await appel('GET', '/api/natifs/booleen');
await appel('GET', '/api/natifs/booleen?actifs=oui');
await appel('GET', '/api/natifs/uuid/3f2b8c1e-9d4a-4f6b-8e2a-1c5d7e9f0a3b');
await appel('GET', '/api/natifs/uuid/123');
await appel('GET', '/api/natifs/session/controle');
await appel('GET', '/api/natifs/session/rattrapage');
await appel('GET', '/api/natifs/liste?ids=3,8,12');
await appel('GET', '/api/natifs/liste?ids=3,x,12');
await appel('GET', '/api/natifs/date?du=2026-09-15');
await appel('GET', '/api/natifs/date?du=hier');
await appel('GET', '/api/natifs/page');
await appel('GET', '/api/natifs/page?page=3&limite=25');
await appel('GET', '/api/natifs/page?page=trois');

Résultat réellement obtenu :

GET /api/natifs/entier/42 → 200 {"id":42,"type":"number"}
GET /api/natifs/entier/abc → 400 {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
GET /api/natifs/entier/4.5 → 400 {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
GET /api/natifs/entier-406/abc → 406 {"message":"Validation failed (numeric string is expected)","error":"Not Acceptable","statusCode":406}
GET /api/natifs/reel?note=14.75 → 200 {"note":14.75,"surVingt":true}
GET /api/natifs/reel → 400 {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
GET /api/natifs/booleen?actifs=true → 200 {"actifs":true}
GET /api/natifs/booleen → 200 {"actifs":"non précisé"}
GET /api/natifs/booleen?actifs=oui → 400 {"message":"Validation failed (boolean string is expected)","error":"Bad Request","statusCode":400}
GET /api/natifs/uuid/3f2b8c1e-9d4a-4f6b-8e2a-1c5d7e9f0a3b → 200 {"ref":"3f2b8c1e-9d4a-4f6b-8e2a-1c5d7e9f0a3b"}
GET /api/natifs/uuid/123 → 400 {"message":"Validation failed (uuid v 4 is expected)","error":"Bad Request","statusCode":400}
GET /api/natifs/session/controle → 200 {"session":"controle"}
GET /api/natifs/session/rattrapage → 400 {"message":"Validation failed (enum string is expected)","error":"Bad Request","statusCode":400}
GET /api/natifs/liste?ids=3,8,12 → 200 {"ids":[3,8,12],"somme":23}
GET /api/natifs/liste?ids=3,x,12 → 400 {"message":"[1] item must be a number","error":"Bad Request","statusCode":400}
GET /api/natifs/date?du=2026-09-15 → 200 {"du":"2026-09-15T00:00:00.000Z","estUneDate":true}
GET /api/natifs/date?du=hier → 400 {"message":"Validation failed (invalid date format)","error":"Bad Request","statusCode":400}
GET /api/natifs/page → 200 {"page":1,"limite":10}
GET /api/natifs/page?page=3&limite=25 → 200 {"page":3,"limite":25}
GET /api/natifs/page?page=trois → 400 {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
Pipe par pipe
PipeUsageRemarques
ParseIntPipeidentifiants, quantitésrefuse les décimaux (4.5) et le texte
ParseFloatPipenotes, montantsrefuse un paramètre absent : combinez avec DefaultValuePipe ou optional: true
ParseBoolPipefiltres oui/nonaccepte seulement true et false (pas oui, ni 1)
ParseUUIDPipeidentifiants UUID (chapitre 11)option version: '3', '4', '5', '7'…
ParseEnumPipevaleurs dans une liste ferméereçoit l'enum en paramètre du constructeur
ParseArrayPipelistes dans la query stringoptions items (type de chaque élément) et separator; nécessite les paquets class-validator et class-transformer (leçon 8.4)
ParseDatePipedates (nouveau dans NestJS 11)renvoie un objet Date
DefaultValuePipevaleur par défautà placer avant le pipe de conversion
Les options communes
// Paramètre facultatif : undefined s'il est absent, au lieu d'une erreur 400
@Query('actifs', new ParseBoolPipe({ optional: true })) actifs?: boolean

// Changer le statut de l'erreur
@Param('id', new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE })) id: number

// Remplacer complètement l'exception (et donc le message)
@Param('id', new ParseIntPipe({
  exceptionFactory: () => new BadRequestException("L'identifiant doit être un nombre entier"),
})) id: number
DefaultValuePipe pour la pagination

Pour une pagination, les paramètres page et limite sont facultatifs. DefaultValuePipe remplace une valeur absente (undefined) par la valeur par défaut ; ParseIntPipe s'exécute ensuite. L'ordre est important : @Query('page', ParseIntPipe, new DefaultValuePipe(1)) refuserait la requête sans page, car ParseIntPipe recevrait undefined.

Piège de NestJS 11 : ParseDatePipe s'instancie. Contrairement à ParseIntPipe, si on le passe comme classe (@Query('du', ParseDatePipe)), l'application refuse de démarrer:

Nest can't resolve dependencies of the ParseDatePipe (?). Please make sure that the argument at index [0] is available in the current module.

Son constructeur attend un objet d'options que NestJS ne sait pas injecter. Écrivez toujours new ParseDatePipe(). En cas de doute, l'instanciation fonctionne pour tous les pipes natifs.

Les limites des pipes natifs

Ces pipes traitent une valeur simple. Pour un corps JSON avec dix champs et des règles (e-mail valide, longueur, valeur dans une liste), il faudrait un pipe par champ : c'est impossible avec @Body(), qui reçoit l'objet entier. La solution est le ValidationPipe associé aux décorateurs de class-validator, présenté dans la leçon suivante.

Activités

Activité 1 Prédire les réponses

Pour la route @Get('notes') liste(@Query('min', new DefaultValuePipe(0), ParseFloatPipe) min: number, @Query('avecAbsents', new ParseBoolPipe({ optional: true })) avec?: boolean), donnez le résultat de : (a) ?min=12.5; (b) ?avecAbsents=false; (c) ?min=douze; (d) ?avecAbsents=1.

Voir le corrigé

(a) min = 12.5, avec = undefined. (b) min = 0 (valeur par défaut), avec = false. (c) 400 « Validation failed (numeric string is expected) ». (d) 400 « Validation failed (boolean string is expected) ».

Activité 2 Des statistiques par période

Écrivez GET /api/absences/statistiques?du=…&au=…&groupes=DEV101,DEV102: du et au sont des dates obligatoires, groupes une liste facultative. Renvoyez le nombre de jours de la période et la liste des groupes.

Voir le corrigé
@Get('statistiques')
statistiques(
  @Query('du', new ParseDatePipe()) du: Date,
  @Query('au', new ParseDatePipe()) au: Date,
  @Query('groupes', new ParseArrayPipe({ items: String, separator: ',', optional: true })) groupes?: string[],
) {
  if (au < du) throw new BadRequestException('La date de fin précède la date de début');
  const jours = Math.round((au.getTime() - du.getTime()) / 86_400_000) + 1;
  return { jours, groupes: groupes ?? 'tous' };
}

La vérification « fin après début » concerne deux paramètres à la fois : un pipe, qui ne voit qu'un argument, ne peut pas la faire. Elle reste dans le handler ou le service.

Activité 3 Un message plus clair

Le message « Validation failed (numeric string is expected) » est peu parlant pour les utilisateurs de votre API. Utilisez exceptionFactory pour obtenir « L'identifiant du stagiaire doit être un nombre entier ». Comment éviter de répéter cette configuration dans chaque contrôleur ?

Voir le corrigé
// src/common/pipes/id.pipe.ts
export const IdPipe = new ParseIntPipe({
  exceptionFactory: () => new BadRequestException("L'identifiant doit être un nombre entier"),
});

// utilisation
@Get(':id')
findOne(@Param('id', IdPipe) id: number) { … }

On exporte une instance configurée, réutilisée partout. Autre solution : une classe IdPipe extends ParseIntPipe qui appelle super({ exceptionFactory: … }).

Activité 4 UUID

Dans api-todolist (TP 4), lancez l'API avec ID_MODE=uuid et protégez GET /api/v1/taches/:id avec ParseUUIDPipe. Que se passe-t-il ensuite avec ID_MODE séquentiel ? Comment rendre le pipe cohérent avec le mode choisi ?

Voir le corrigé

En mode séquentiel, les identifiants T-0001 sont refusés par ParseUUIDPipe (400). Le format de l'identifiant dépend de l'implémentation de GenerateurId: la validation doit donc lui être confiée. Ajoutez par exemple une méthode estValide(id) à la classe abstraite et un pipe personnalisé (leçon 8.6) qui l'utilise par injection.

À retenir

  • Pipes natifs : ParseInt, ParseFloat, ParseBool, ParseUUID, ParseEnum, ParseArray, ParseDate, DefaultValue.
  • Ils transforment le texte reçu dans le bon type, ou répondent 400 avec un message standard.
  • Options : optional, errorHttpStatusCode, exceptionFactory.
  • DefaultValuePipe se place avant le pipe de conversion.
  • NestJS 11 : écrire new ParseDatePipe(), sinon l'application ne démarre pas.
  • Pour valider un corps complet : ValidationPipe (leçon suivante).

Cet article vous a-t-il aidé ?