À propos de ce cours
Objectifs de la leçon
- Connecter NestJS à MongoDB avec @nestjs/mongoose.
- Décrire un schéma avec @Schema, @Prop et SchemaFactory.
- Utiliser sous-documents, références, index et virtuels.
- Écrire un service CRUD avec le Model injecté.
- Valider les identifiants et traiter les doublons.
Mongoose et @nestjs/mongoose
MongoDB n'impose aucun schéma. Mongoose (ODM, Object Document Mapper) en ajoute un côté application : types, valeurs par défaut, validations, conversions, relations. @nestjs/mongoose permet de décrire ce schéma avec des classes et des décorateurs, et d'injecter les modèles.
npm install @nestjs/mongoose mongoose
Versions utilisées : Mongoose 9 et @nestjs/mongoose 12. La validation, la conversion des documents et ParseObjectIdPipe ont été exécutées ; les requêtes vers la base, qui nécessitent un serveur MongoDB, sont données pour être exécutées sur votre poste.
Le schéma décrit les documents, le Model les lit et les écrit.
Le schéma
📄 src/stagiaires/stagiaire.schema.ts
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import mongoose, { HydratedDocument, Types } from 'mongoose';
export type StagiaireDocument = HydratedDocument<Stagiaire>;
@Schema({ _id: false }) // sous-document intégré, sans _id propre
export class Adresse {
@Prop({ required: true, trim: true })
ville: string;
@Prop({ match: /^\d{4}$/ })
codePostal: string;
}
export const AdresseSchema = SchemaFactory.createForClass(Adresse);
@Schema({ _id: false })
export class Note {
@Prop({ required: true, enum: ['SQL', 'JS', 'PHP', 'Anglais'] })
matiere: string;
@Prop({ required: true, min: 0, max: 20 })
valeur: number;
}
export const NoteSchema = SchemaFactory.createForClass(Note);
@Schema({ collection: 'stagiaires', timestamps: { createdAt: 'creeLe', updatedAt: 'modifieLe' } })
export class Stagiaire {
@Prop({ required: true, trim: true, minlength: 2, maxlength: 50 })
nom: string;
@Prop({ required: true, trim: true })
prenom: string;
@Prop({ required: true, unique: true, lowercase: true, trim: true })
email: string;
@Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'Groupe' }) // RÉFÉRENCE vers un document d'une autre collection
groupe?: Types.ObjectId;
@Prop({ type: AdresseSchema }) // document INTÉGRÉ
adresse?: Adresse;
@Prop({ type: [NoteSchema], default: [] }) // tableau de sous-documents
notes: Note[];
@Prop({ type: [String], default: [] })
competences: string[];
@Prop({ default: true })
actif: boolean;
}
export const StagiaireSchema = SchemaFactory.createForClass(Stagiaire);
StagiaireSchema.index({ nom: 1, prenom: 1 });
StagiaireSchema.virtual('moyenne').get(function (this: Stagiaire) {
return this.notes.length ? Math.round((this.notes.reduce((s, n) => s + n.valeur, 0) / this.notes.length) * 100) / 100 : null;
});
StagiaireSchema.set('toJSON', { virtuals: true, versionKey: false });
| Élément | Rôle |
|---|---|
@Schema({ collection, timestamps }) | nom de la collection ; ajout automatique des dates de création et de modification |
@Prop({ required, minlength, maxlength, min, max, enum, match }) | règles de validation |
trim, lowercase | conversions appliquées à l'enregistrement |
unique: true | crée un index unique (ce n'est pas une validation : l'erreur vient de MongoDB) |
type: AdresseSchema, type: [NoteSchema] | sous-document et tableau de sous-documents intégrés |
type: mongoose.Schema.Types.ObjectId, ref: 'Groupe' | référence vers un document d'une autre collection |
virtual('moyenne') | champ calculé, non stocké |
HydratedDocument<Stagiaire> | type d'un document Mongoose (avec _id, save()…) |
Validation et conversion, exécutées
La validation de Mongoose se fait dans Node.js, avant l'envoi à MongoDB. On peut donc l'observer sans serveur :
📄 src/essai-validation.ts
import 'reflect-metadata';
import mongoose, { isValidObjectId } from 'mongoose';
import { Stagiaire, StagiaireSchema } from './stagiaire.schema';
// Modèle créé sans connexion : la validation et la conversion se font côté Node.js
const StagiaireModel = mongoose.model(Stagiaire.name, StagiaireSchema);
const valide = new StagiaireModel({
nom: ' Ben Ali ', prenom: 'Sami', email: 'Sami@Exemple.TN',
groupe: '6745f1a2b3c4d5e6f7a8b9c0',
adresse: { ville: 'Tunis', codePostal: '1000' },
notes: [{ matiere: 'SQL', valeur: '15' }, { matiere: 'JS', valeur: 12.5 }],
competences: ['HTML', 'CSS'],
champInconnu: 'ignoré',
});
async function main() {
const essayer = (doc: InstanceType<typeof StagiaireModel>) => doc.validate().then(() => null, (e: mongoose.Error.ValidationError) => e);
console.log('1. erreurs :', (await essayer(valide)) ?? 'aucune');
console.log(' document :', JSON.stringify(valide.toJSON()));
console.log(' _id est un ObjectId ?', valide._id instanceof mongoose.Types.ObjectId, '| créé le', valide._id.getTimestamp().toISOString().slice(0, 10));
const invalide = new StagiaireModel({
nom: 'B', email: 'x@y.tn', groupe: '42',
adresse: { codePostal: '30' },
notes: [{ matiere: 'Chimie', valeur: 25 }],
});
const erreurs = await essayer(invalide);
console.log('2. erreurs :');
for (const [chemin, err] of Object.entries(erreurs?.errors ?? {})) console.log(` - ${chemin} : ${err.message}`);
console.log(' valeur de groupe après conversion :', invalide.groupe);
console.log('3. isValidObjectId :', ['6745f1a2b3c4d5e6f7a8b9c0', '42', 'abc'].map((v) => `${v} → ${isValidObjectId(v)}`).join(' | '));
}
main();
Résultat réellement obtenu :
1. erreurs : aucune
document : {"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupe":"6745f1a2b3c4d5e6f7a8b9c0","adresse":{"ville":"Tunis","codePostal":"1000"},"notes":[{"matiere":"SQL","valeur":15},{"matiere":"JS","valeur":12.5}],"competences":["HTML","CSS"],"actif":true,"_id":"6af9682cd1eb61b17182e577","moyenne":13.75,"id":"6af9682cd1eb61b17182e577"}
_id est un ObjectId ? true | créé le 2026-11-15
2. erreurs :
- groupe : Cast to ObjectId failed for value "42" (type string) at path "groupe" for model "Stagiaire"
- adresse.ville : Path `ville` is required.
- adresse.codePostal : Path `codePostal` is invalid (30).
- notes.0.matiere : `Chimie` is not a valid enum value for path `matiere`.
- notes.0.valeur : Path `valeur` (25) is more than maximum allowed value (20).
- prenom : Path `prenom` is required.
- nom : Path `nom` (`B`, length 1) is shorter than the minimum allowed length (2).
valeur de groupe après conversion : undefined
3. isValidObjectId : 6745f1a2b3c4d5e6f7a8b9c0 → true | 42 → false | abc → false
- Document valide :
noma été nettoyé, l'e-mail mis en minuscules, la note'15'convertie en nombre, le champ inconnu ignoré (mode strict par défaut),actifa reçu sa valeur par défaut._ida été généré par le client, avant toute écriture, et contient sa date de création. Le virtuelmoyenneet l'aliasidapparaissent dans le JSON. - Document invalide : toutes les erreurs sont signalées, avec leur chemin, y compris dans les sous-documents (
adresse.ville,notes.0.valeur), et l'identifiant42est refusé (« Cast to ObjectId failed »).
Un piège vérifié : Types.ObjectId
import 'reflect-metadata';
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import mongoose, { Types } from 'mongoose';
@Schema()
class Inscription {
@Prop({ type: Types.ObjectId, ref: 'Groupe' }) // ✗ la classe ObjectId du pilote
groupeA: Types.ObjectId;
@Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'Groupe' }) // ✓ le type de schéma Mongoose
groupeB: Types.ObjectId;
}
Résultat réellement obtenu :
erreurs sur : [ 'groupeB' ]
groupeA vaut : "42" | type : Mixed
groupeB vaut : undefined | type : ObjectId
Déclarer la référence avec Types.ObjectId (la classe du pilote, celle qu'on utilise pour typer la propriété) donne un champ de type Mixed: n'importe quelle valeur est acceptée, sans conversion. Pour le schéma, il faut mongoose.Schema.Types.ObjectId. Le type TypeScript, lui, reste Types.ObjectId.
Connexion et module
📄 .env
MONGODB_URI=mongodb://localhost:27017/formation
📄 src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { MongooseModule } from '@nestjs/mongoose';
import { StagiairesModule } from './stagiaires/stagiaires.module';
@Module({
imports: [
ConfigModule.forRoot({ isGlobal: true }),
MongooseModule.forRootAsync({
inject: [ConfigService],
useFactory: (config: ConfigService) => ({ uri: config.getOrThrow<string>('MONGODB_URI') }),
}),
StagiairesModule,
],
})
export class AppModule {}
📄 src/stagiaires/stagiaires.module.ts
import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { Stagiaire, StagiaireSchema } from './stagiaire.schema';
import { StagiairesController } from './stagiaires.controller';
import { StagiairesService } from './stagiaires.service';
@Module({
imports: [MongooseModule.forFeature([{ name: Stagiaire.name, schema: StagiaireSchema }])],
controllers: [StagiairesController],
providers: [StagiairesService],
})
export class StagiairesModule {}
Le service
📄 src/stagiaires/stagiaires.service.ts
import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model, Types } from 'mongoose';
import { CreerStagiaireDto, ModifierStagiaireDto } from './stagiaire.dto';
import { Stagiaire } from './stagiaire.schema';
@Injectable()
export class StagiairesService {
constructor(@InjectModel(Stagiaire.name) private readonly modele: Model<Stagiaire>) {}
async findAll(ville?: string, page = 1, limite = 10) {
const filtre = ville ? { 'adresse.ville': ville } : {};
const [donnees, total] = await Promise.all([
this.modele.find(filtre).sort({ nom: 1 }).skip((page - 1) * limite).limit(limite).lean(), // lean : objets simples, plus rapides
this.modele.countDocuments(filtre),
]);
return { donnees, meta: { total, page, limite } };
}
async findOne(id: Types.ObjectId) {
const stagiaire = await this.modele.findById(id).populate('groupe', 'code intitule'); // remplace l'ObjectId par le document
if (!stagiaire) throw new NotFoundException(`Stagiaire ${id} introuvable`);
return stagiaire;
}
async create(dto: CreerStagiaireDto) {
try {
return await this.modele.create(dto); // validation du schéma, puis insertOne
} catch (e) {
if ((e as { code?: number }).code === 11000) throw new ConflictException(`L'e-mail ${dto.email} est déjà utilisé`);
throw e;
}
}
async update(id: Types.ObjectId, dto: ModifierStagiaireDto) {
const stagiaire = await this.modele.findByIdAndUpdate(id, { $set: dto }, { new: true, runValidators: true });
if (!stagiaire) throw new NotFoundException(`Stagiaire ${id} introuvable`);
return stagiaire;
}
async ajouterNote(id: Types.ObjectId, note: { matiere: string; valeur: number }) {
const stagiaire = await this.modele.findByIdAndUpdate(id, { $push: { notes: note } }, { new: true, runValidators: true });
if (!stagiaire) throw new NotFoundException(`Stagiaire ${id} introuvable`);
return stagiaire;
}
async remove(id: Types.ObjectId) {
const { deletedCount } = await this.modele.deleteOne({ _id: id });
if (!deletedCount) throw new NotFoundException(`Stagiaire ${id} introuvable`);
}
moyennesParVille() {
return this.modele.aggregate([
{ $unwind: '$notes' },
{ $group: { _id: '$adresse.ville', moyenne: { $avg: '$notes.valeur' }, notes: { $sum: 1 } } },
{ $sort: { moyenne: -1 } },
]);
}
}
📄 src/stagiaires/stagiaires.controller.ts
import { Body, Controller, Delete, Get, HttpCode, Param, Patch, Post, Query } from '@nestjs/common';
import { ParseObjectIdPipe } from '@nestjs/mongoose';
import { Types } from 'mongoose';
import { CreerStagiaireDto, ModifierStagiaireDto } from './stagiaire.dto';
import { StagiairesService } from './stagiaires.service';
@Controller('stagiaires')
export class StagiairesController {
constructor(private readonly stagiairesService: StagiairesService) {}
@Get('moyennes')
moyennes() {
return this.stagiairesService.moyennesParVille();
}
@Get()
findAll(@Query('ville') ville?: string) {
return this.stagiairesService.findAll(ville);
}
@Get(':id')
findOne(@Param('id', ParseObjectIdPipe) id: Types.ObjectId) {
return this.stagiairesService.findOne(id);
}
@Post()
create(@Body() dto: CreerStagiaireDto) {
return this.stagiairesService.create(dto);
}
@Patch(':id')
update(@Param('id', ParseObjectIdPipe) id: Types.ObjectId, @Body() dto: ModifierStagiaireDto) {
return this.stagiairesService.update(id, dto);
}
@Delete(':id')
@HttpCode(204)
remove(@Param('id', ParseObjectIdPipe) id: Types.ObjectId) {
return this.stagiairesService.remove(id);
}
}
| Méthode | Rôle |
|---|---|
find(filtre).sort().skip().limit() | liste ; le filtre utilise la syntaxe MongoDB ('adresse.ville') |
.lean() | renvoie des objets simples au lieu de documents Mongoose : plus rapide pour la lecture seule (mais sans virtuels) |
findById(id).populate('groupe', 'code intitule') | remplace la référence par le document du groupe (requête supplémentaire) |
create(dto) | valide puis insère |
findByIdAndUpdate(id, maj, { new: true, runValidators: true }) | modifie et renvoie la version après modification ; sans runValidators, les règles du schéma ne sont pas vérifiées lors des mises à jour |
deleteOne, countDocuments, aggregate | suppression, comptage, pipeline d'agrégation (leçon 12.2) |
Valider les identifiants : ParseObjectIdPipe
@nestjs/mongoose fournit un pipe qui vérifie et convertit l'identifiant de l'URL :
Résultat réellement obtenu :
GET /api/stagiaires/6745f1a2b3c4d5e6f7a8b9c0 → 200 {"id":"6745f1a2b3c4d5e6f7a8b9c0","estUnObjectId":true}
GET /api/stagiaires/42 → 400 {"message":"Invalid ObjectId: '42' is not a valid MongoDB ObjectId","error":"Bad Request","statusCode":400}
Sans ce pipe, findById('42') lèverait une CastError, transformée en 500 par le filtre par défaut. Pour les doublons, MongoDB renvoie une erreur de code 11000, traduite en 409 dans le service (ou dans un filtre global, comme au TP 7).
Les DTO et le ValidationPipe (chapitre 08) restent indispensables : ils valident la requête HTTP et produisent des messages clairs. La validation Mongoose est une seconde barrière, au niveau des données.
Activités
Activité 1 Le schéma Groupe et populate
Écrivez le schéma Groupe (code unique en majuscules, intitulé, capacité de 1 à 40, 20 par défaut), son module, et une route qui renvoie un stagiaire avec son groupe. Que contient groupe sans populate?
Voir le corrigé
@Schema({ collection: 'groupes', timestamps: true })
export class Groupe {
@Prop({ required: true, unique: true, uppercase: true, trim: true })
code: string;
@Prop({ required: true })
intitule: string;
@Prop({ min: 1, max: 40, default: 20 })
capacite: number;
}
export const GroupeSchema = SchemaFactory.createForClass(Groupe);
Sans populate, groupe contient seulement l'ObjectId. Attention : ref: 'Groupe' doit correspondre au name déclaré dans forFeature (Groupe.name).
Activité 2 Mettre à jour un sous-document
Écrivez modifierNote(id, matiere, valeur) qui modifie la note d'une matière dans le tableau notes, sans relire tout le document. Indice : l'opérateur positionnel $.
Voir le corrigé
const r = await this.modele.updateOne(
{ _id: id, 'notes.matiere': matiere }, // trouve le stagiaire ET l'élément du tableau
{ $set: { 'notes.$.valeur': valeur } }, // $ = l'élément trouvé
{ runValidators: true },
);
if (!r.matchedCount) throw new NotFoundException('Stagiaire ou matière introuvable');
Activité 3 Mettre la validation à l'épreuve
Dans votre projet, envoyez PATCH /api/stagiaires/:id avec { "nom": "B" }, d'abord avec runValidators: true, puis sans. Que constatez-vous ? Et si le DTO de modification valide déjà la longueur ?
Voir le corrigé
Avec runValidators, Mongoose refuse (ValidationError, à traduire en 400). Sans, le nom « B » est enregistré : les validateurs du schéma ne s'appliquent par défaut qu'à create() et save(). Si le DTO valide déjà, la requête est refusée avant (400 du ValidationPipe) ; mais une autre partie du code (script, tâche planifiée) pourrait encore écrire une valeur invalide : gardez runValidators: true.
Activité 4 Porter le TP 4 sur MongoDB
Dans une branche mongodb de votre dépôt api-todolist (TP 4), remplacez le stockage en mémoire par MongoDB : schéma Tache (titre, statut, priorité, échéance, créée par), ParseObjectIdPipe pour les identifiants, et les statistiques avec aggregate. Faites une pull request et décrivez dans le README comment lancer MongoDB avec Docker.
Voir le corrigé
Le générateur d'identifiants du TP 4 devient inutile (MongoDB génère les _id). Les statistiques par statut s'écrivent this.modele.aggregate([{ $group: { _id: '$statut', total: { $sum: 1 } } }]). Les tâches en retard : find({ statut: { $ne: 'terminee' }, echeance: { $lt: aujourdHui } }). Le docker-compose.yml du README peut lancer à la fois MongoDB et l'API.
À retenir
- npm install @nestjs/mongoose mongoose ; MongooseModule.forRootAsync({ uri }) et forFeature([{ name, schema }]).
- @Schema + @Prop + SchemaFactory.createForClass : validations, sous-documents, index, virtuels, timestamps.
- Référence : type: mongoose.Schema.Types.ObjectId (pas Types.ObjectId, qui donne Mixed) + ref + populate.
- @InjectModel(X.name) Model
: find, findById, create, findByIdAndUpdate (new, runValidators), deleteOne, aggregate. - ParseObjectIdPipe pour les identifiants ; erreur 11000 → 409.
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 !