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

Utiliser Mongoose avec NestJS (@Schema, @Prop, Model)

Cette leçon intègre MongoDB dans NestJS avec Mongoose 9 et @nestjs/mongoose. Elle décrit un schéma de stagiaire avec @Schema et @Prop : validations, sous-documents intégrés (adresse, notes), référence...

0 chapitres 0 QCM Accès gratuit
Utiliser Mongoose avec NestJS (@Schema, @Prop, Model)

À propos de ce cours

Cette leçon intègre MongoDB dans NestJS avec Mongoose 9 et @nestjs/mongoose. Elle décrit un schéma de stagiaire avec @Schema et @Prop : validations, sous-documents intégrés (adresse, notes), référence vers un groupe, index, champ virtuel et horodatage. La validation et la conversion des documents sont exécutées et leurs messages réels montrés, ainsi qu'un piège vérifié : une référence déclarée avec Types.ObjectId devient de type Mixed et n'est plus contrôlée. La leçon présente ensuite la connexion, le Model injecté, un service CRUD complet avec populate et lean, ParseObjectIdPipe et la gestion des doublons. Activités corrigées.

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.

Mongoose dans NestJS

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émentRô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, lowercaseconversions appliquées à l'enregistrement
unique: truecré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 : nom a été nettoyé, l'e-mail mis en minuscules, la note '15' convertie en nombre, le champ inconnu ignoré (mode strict par défaut), actif a reçu sa valeur par défaut. _id a été généré par le client, avant toute écriture, et contient sa date de création. Le virtuel moyenne et l'alias id apparaissent 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'identifiant 42 est 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éthodeRô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, aggregatesuppression, 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é ?