À propos de ce cours
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.
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,
suivantevautnull. - 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 paridpour 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=motDePasseest refusé par le DTO (liste blanche),limite=500aussi : 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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !