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

Pagination, tri et filtres dans une API

Cette leçon met en place la pagination, le tri et les filtres d'une liste dans une API NestJS, avec 23 stagiaires en base. Un DTO validé (chapitre 08) décrit les paramètres de la query string, et le s...

0 chapitres 0 QCM Accès gratuit
Pagination, tri et filtres dans une API

À propos de ce cours

Cette leçon met en place la pagination, le tri et les filtres d'une liste dans une API NestJS, avec 23 stagiaires en base. Un DTO validé (chapitre 08) décrit les paramètres de la query string, et le service construit une requête QueryBuilder qui n'ajoute une condition que si le critère est fourni : recherche textuelle, plusieurs groupes, date minimale. Le tri passe par une liste blanche. La réponse contient les données et des métadonnées (total, pages, précédente, suivante). Le SQL réel et l'optimisation du comptage par TypeORM sont analysés. Activités corrigées.

Objectifs de la leçon

  • Décrire pagination, tri et filtres dans un DTO validé.
  • Construire une requête dont les conditions dépendent des critères fournis.
  • Sécuriser le tri avec une liste blanche.
  • Renvoyer une page avec ses métadonnées.
Pourquoi paginer ?

Une table peut contenir des milliers de lignes. Tout renvoyer ralentit la base, le réseau et l'interface. On renvoie une page (par exemple 10 éléments) et les informations qui permettent au client d'afficher la navigation : nombre total, nombre de pages, page suivante.

Pagination, tri et filtres

De l'URL au SQL, en passant par un DTO validé.

Le DTO des paramètres

📄 src/stagiaires/filtre-stagiaires.dto.ts

import { Type } from 'class-transformer';
import { IsDateString, IsIn, IsInt, IsOptional, IsString, Max, Min, MinLength } from 'class-validator';

export const CHAMPS_TRI = ['nom', 'prenom', 'dateNaissance'] as const;

export class FiltreStagiairesDto {
  @IsOptional() @Type(() => Number) @IsInt() @Min(1)
  page: number = 1;

  @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(50)
  limite: number = 10;

  @IsOptional() @IsIn(CHAMPS_TRI)
  tri: (typeof CHAMPS_TRI)[number] = 'nom';

  @IsOptional() @IsIn(['asc', 'desc'])
  ordre: 'asc' | 'desc' = 'asc';

  @IsOptional() @IsString() @MinLength(2)
  q?: string;                                   // recherche dans nom et prénom

  @IsOptional() @IsString()
  groupe?: string;                              // code du groupe, ou plusieurs séparés par des virgules

  @IsOptional() @IsDateString()
  neApres?: string;                             // né(e) à partir de cette date
}
Le service

📄 src/stagiaires/stagiaires.service.ts

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { FiltreStagiairesDto } from './filtre-stagiaires.dto';
import { Stagiaire } from './stagiaire.entity';

export interface Page<T> {
  donnees: T[];
  meta: { total: number; page: number; limite: number; pages: number; precedente: number | null; suivante: number | null };
}

@Injectable()
export class StagiairesService {
  constructor(@InjectRepository(Stagiaire) private readonly depot: Repository<Stagiaire>) {}

  async rechercher(f: FiltreStagiairesDto): Promise<Page<Stagiaire>> {
    const qb = this.depot.createQueryBuilder('s').leftJoinAndSelect('s.groupe', 'g');

    // Filtres facultatifs : on n'ajoute une condition que si le critère est fourni
    if (f.q) {
      qb.andWhere('(s.nom LIKE :q OR s.prenom LIKE :q)', { q: `%${f.q}%` });
    }
    if (f.groupe) {
      qb.andWhere('g.code IN (:...codes)', { codes: f.groupe.split(',').map((c) => c.trim().toUpperCase()) });
    }
    if (f.neApres) {
      qb.andWhere('s.dateNaissance >= :date', { date: f.neApres });
    }

    // Tri : le champ vient d'une liste blanche (validée par le DTO), jamais directement du client
    qb.orderBy(`s.${f.tri}`, f.ordre === 'desc' ? 'DESC' : 'ASC').addOrderBy('s.id', 'ASC');

    // Pagination
    qb.skip((f.page - 1) * f.limite).take(f.limite);

    const [donnees, total] = await qb.getManyAndCount();
    const pages = Math.max(1, Math.ceil(total / f.limite));
    return {
      donnees,
      meta: {
        total, page: f.page, limite: f.limite, pages,
        precedente: f.page > 1 ? f.page - 1 : null,
        suivante: f.page < pages ? f.page + 1 : null,
      },
    };
  }
}

📄 src/stagiaires/stagiaires.controller.ts

import { Controller, Get, Query } from '@nestjs/common';
import { FiltreStagiairesDto } from './filtre-stagiaires.dto';
import { StagiairesService } from './stagiaires.service';

@Controller('stagiaires')
export class StagiairesController {
  constructor(private readonly stagiairesService: StagiairesService) {}

  @Get()
  async rechercher(@Query() filtre: FiltreStagiairesDto) {
    const page = await this.stagiairesService.rechercher(filtre);
    // affichage compact pour la démonstration
    return { ...page, donnees: page.donnees.map((s) => `${s.nom} ${s.prenom} (${s.groupe?.code ?? '—'}, ${s.dateNaissance})`) };
  }
}
  await appel('GET', `${b}?limite=4`);
  await appel('GET', `${b}?limite=4&page=6`);
  await appel('GET', `${b}?q=ben&groupe=dev101,dev102&tri=dateNaissance&ordre=desc`);
  await appel('GET', `${b}?neApres=2006-01-01&tri=prenom&limite=3`);
  await appel('GET', `${b}?tri=motDePasse`);
  await appel('GET', `${b}?limite=500&page=0`);

Résultat réellement obtenu :

GET /api/stagiaires?limite=4 → 200 {"donnees":["Ayari Salma (DEV102, 2007-06-15)","Ayari Lina (DEV102, 2007-09-18)","Ben Ali Sami (DEV101, 2002-01-10)","Ben Ali Omar (DEV101, 2002-04-13)"],"meta":{"total":23,"page":1,"limite":4,"pages":6,"precedente":null,"suivante":2}}
GET /api/stagiaires?limite=4&page=6 → 200 {"donnees":["Mansouri Amira (—, 2005-07-16)","Trabelsi Lina (DEV102, 2003-02-11)","Trabelsi Salma (DEV102, 2003-05-14)"],"meta":{"total":23,"page":6,"limite":4,"pages":6,"precedente":5,"suivante":null}}
  SQL> SELECT DISTINCT `distinctAlias`.`s_id` AS `ids_s_id`, `distinctAlias`.`s_date_naissance`, `distinctAlias`.`s_id` FROM (SELECT `s`.`id` AS `s_id`, `s`.`nom` AS `s_nom`, `s`.`prenom` AS `s_prenom`, `s`.`date_naissance` AS `s_date_naissance`, `s`.`groupe_id` AS `s_groupe_id`, `g`.`id` AS `g_id`, `g`.`code` AS `g_code` FROM `stagiaires` `s` LEFT JOIN `groupes` `g` ON `g`.`id`=`s`.`groupe_id` WHERE (`s`.`nom` LIKE ? OR `s`.`prenom` LIKE ?) AND `g`.`code` IN (?, ?)) `distinctAlias` ORDER BY `distinctAlias`.`s_date_naissance` DESC, `distinctAlias`.`s_id` ASC, `s_id` ASC LIMIT 10 OFFSET 0 -- ["%ben%","%ben%","DEV101","DEV102"]
  SQL> SELECT `s`.`id` AS `s_id`, `s`.`nom` AS `s_nom`, `s`.`prenom` AS `s_prenom`, `s`.`date_naissance` AS `s_date_naissance`, `s`.`groupe_id` AS `s_groupe_id`, `g`.`id` AS `g_id`, `g`.`code` AS `g_code` FROM `stagiaires` `s` LEFT JOIN `groupes` `g` ON `g`.`id`=`s`.`groupe_id` WHERE ( (`s`.`nom` LIKE ? OR `s`.`prenom` LIKE ?) AND `g`.`code` IN (?, ?) ) AND ( `s`.`id` IN (13, 1) ) ORDER BY `s`.`date_naissance` DESC, `s`.`id` ASC -- ["%ben%","%ben%","DEV101","DEV102"]
GET /api/stagiaires?q=ben&groupe=dev101,dev102&tri=dateNaissance&ordre=desc → 200 {"donnees":["Ben Ali Omar (DEV101, 2002-04-13)","Ben Ali Sami (DEV101, 2002-01-10)"],"meta":{"total":2,"page":1,"limite":10,"pages":1,"precedente":null,"suivante":null}}
GET /api/stagiaires?neApres=2006-01-01&tri=prenom&limite=3 → 200 {"donnees":["Karoui Ines (—, 2007-03-12)","Hammami Karim (RES201, 2006-02-11)","Ayari Lina (DEV102, 2007-09-18)"],"meta":{"total":7,"page":1,"limite":3,"pages":3,"precedente":null,"suivante":2}}
GET /api/stagiaires?tri=motDePasse → 400 {"message":["tri must be one of the following values: nom, prenom, dateNaissance"],"error":"Bad Request","statusCode":400}
GET /api/stagiaires?limite=500&page=0 → 400 {"message":["page must not be less than 1","limite must not be greater than 50"],"error":"Bad Request","statusCode":400}

Les lignes SQL> sont les requêtes réellement envoyées par TypeORM (option logging). Pour la lisibilité, elles ne sont affichées que pour certaines opérations.

Ce qu'il faut observer
  • Page 1 et page 6: 23 stagiaires, 4 par page, donc 6 pages ; la dernière contient 3 éléments, suivante vaut null.
  • Filtres combinés: chaque critère fourni ajoute un AND; les codes de groupe ont été mis en majuscules ; le tri par date est décroissant, avec un second tri par id pour que l'ordre soit stable (deux stagiaires de même date gardent toujours le même ordre d'une page à l'autre).
  • Le SQL: avec une jointure, TypeORM utilise deux requêtes : la première sélectionne les identifiants de la page (SELECT DISTINCT … LIMIT 10 OFFSET 0), la seconde charge ces lignes complètes (WHERE s.id IN (13, 1)). Sans cela, la jointure fausserait la pagination quand une ligne principale a plusieurs lignes liées.
  • Pas de requête COUNT ici : la première page contient moins d'éléments que la limite, TypeORM en déduit le total sans interroger la base. Pour une page pleine, il exécute un SELECT COUNT(DISTINCT s.id).
  • Sécurité: tri=motDePasse est refusé par le DTO (liste blanche), limite=500 aussi : un client ne peut pas demander toute la table d'un coup.

Pagination par décalage ou par curseur ? skip/take (OFFSET) est simple et permet d'aller directement à la page 7. Sur de très grandes tables, OFFSET 100000 devient lent, et si des lignes sont ajoutées entre deux pages, des éléments peuvent être vus deux fois. La pagination par curseur (« les 10 suivants après l'id 1520 » : WHERE id > :apres ORDER BY id LIMIT 10) résout ces deux problèmes, au prix de la navigation directe vers une page.

Version simple avec find

Sans jointure ni condition complexe, findAndCount suffit :

const [donnees, total] = await this.depot.findAndCount({
  where: {
    ...(f.groupe ? { groupe: { code: In(f.groupe.split(',')) } } : {}),
    ...(f.neApres ? { dateNaissance: MoreThanOrEqual(f.neApres) } : {}),
  },
  relations: { groupe: true },
  order: { [f.tri]: f.ordre.toUpperCase() as 'ASC' | 'DESC', id: 'ASC' },
  skip: (f.page - 1) * f.limite,
  take: f.limite,
});
Activités

Activité 1 Une classe Page réutilisable

Créez dans src/common/ un PaginationDto (page, limite) et une fonction paginer<T>(qb: SelectQueryBuilder<T>, p: PaginationDto) qui applique skip/take et renvoie { donnees, meta }. Utilisez-la pour les stagiaires et les groupes.

Voir le corrigé
export async function paginer<T extends ObjectLiteral>(qb: SelectQueryBuilder<T>, p: PaginationDto): Promise<Page<T>> {
  const [donnees, total] = await qb.skip((p.page - 1) * p.limite).take(p.limite).getManyAndCount();
  const pages = Math.max(1, Math.ceil(total / p.limite));
  return {
    donnees,
    meta: { total, page: p.page, limite: p.limite, pages,
            precedente: p.page > 1 ? p.page - 1 : null, suivante: p.page < pages ? p.page + 1 : null },
  };
}

// FiltreStagiairesDto extends PaginationDto { … critères propres … }

Activité 2 Liens de navigation

Ajoutez à la réponse des liens suivante et precedente sous forme d'URL complètes, qui conservent les filtres et le tri (par exemple /api/stagiaires?groupe=DEV101&page=3&limite=10). Ajoutez aussi l'en-tête X-Total-Count.

Voir le corrigé

Dans le contrôleur, récupérez la requête (@Req()) et la réponse en mode passthrough (leçon 6.4). Construisez l'URL avec new URL(req.originalUrl, 'http://x'), modifiez searchParams.set('page', …), puis gardez pathname + search. res.setHeader('X-Total-Count', String(page.meta.total)), sans oublier de l'exposer dans la configuration CORS.

Activité 3 Filtre par intervalle

Ajoutez les filtres neAvant et ageMin / ageMax (calculés à partir de la date de naissance). Où calculer les dates limites : dans le DTO, le service ou la requête SQL ?

Voir le corrigé

Dans le service : ageMin = 18 signifie « né au plus tard il y a 18 ans », soit dateNaissance <= :limite avec limite calculée en JavaScript. On garde ainsi une condition simple sur la colonne, qui peut utiliser un index ; un calcul SQL sur chaque ligne (TIMESTAMPDIFF(YEAR, date_naissance, CURDATE())) l'empêcherait.

Activité 4 Pagination par curseur

Écrivez GET /api/stagiaires/flux?apres=120&limite=20 qui renvoie les 20 stagiaires d'identifiant supérieur à 120, et le curseur suivant.

Voir le corrigé
async flux(apres = 0, limite = 20) {
  const donnees = await this.depot.find({
    where: { id: MoreThan(apres) },
    order: { id: 'ASC' },
    take: limite + 1,                                  // un de plus pour savoir s'il en reste
  });
  const encore = donnees.length > limite;
  const page = donnees.slice(0, limite);
  return { donnees: page, curseurSuivant: encore ? page[page.length - 1].id : null };
}

À retenir

  • Un DTO validé décrit page, limite (avec un maximum), tri, ordre et filtres.
  • Conditions ajoutées seulement si le critère est fourni (andWhere) ; valeurs toujours en paramètres.
  • Tri : champ issu d'une liste blanche, plus un second tri stable (id).
  • skip = (page − 1) × limite, take = limite ; getManyAndCount donne la page et le total.
  • Réponse : { donnees, meta: { total, page, limite, pages, precedente, suivante } }.

Cet article vous a-t-il aidé ?