Typegoose pour TypeScript : Guide complet

Typegoose est une puissante bibliothèque d'encapsulation pour Mongoose qui permet de définir des modèles MongoDB à l'aide de classes et de décorateurs TypeScript. Elle résout un problème clé du développement Node.js : le décalage entre le typage strict de TypeScript et la nature dynamique de Mongoose. Au lieu de dupliquer manuellement les types et les schémas, Typegoose vous permet de décrire le modèle une seule fois — sous forme de classe TypeScript — et génère automatiquement un schéma Mongoose à partir de celle-ci.

Pourquoi l'utiliser ? Premièrement, cela réduit considérablement le code passe-partout. Vous n'avez plus besoin d'écrire une interface séparée et un schéma séparé : la classe TypeScript remplit les deux fonctions. Deuxièmement, Typegoose garantit une sécurité de type totale à toutes les étapes : de la création du document à l'exécution des requêtes. Votre IDE suggérera les champs, les méthodes et leurs types, ce qui élimine pratiquement les erreurs de frappe dans les noms de champs ou les types de données incorrects. Troisièmement, la bibliothèque prend en charge toutes les fonctionnalités de Mongoose : les champs virtuels, les hooks (pre/post), les index, populate et le middleware.

Typegoose est idéal pour les projets d'envergure où la maintenabilité du code est cruciale, ainsi que pour les équipes souhaitant tirer parti de tous les avantages de la POO en TypeScript. Il s'intègre facilement avec NestJS, Express et d'autres frameworks, offrant un standard unifié pour la description des données.

Installation

Pour installer Typegoose et ses dépendances, exécutez dans votre terminal :

npm install @typegoose/typegoose mongoose
npm install -D @types/mongoose

Si vous utilisez yarn :

yarn add @typegoose/typegoose mongoose
yarn add -D @types/mongoose

Typegoose nécessite TypeScript version 4.0 ou supérieure. Assurez-vous que votre fichier tsconfig.json inclut les options suivantes :

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2020",
    "module": "commonjs"
  }
}

Démarrage rapide

Créons un modèle utilisateur simple et enregistrons-le dans MongoDB.

import { prop, getModelForClass } from '@typegoose/typegoose';
import mongoose from 'mongoose';

// 1. Définir la classe du modèle
class User {
  @prop({ required: true })
  public name!: string;

  @prop({ required: true, unique: true })
  public email!: string;

  @prop({ default: 0 })
  public age!: number;
}

// 2. Obtenir le modèle Mongoose
const UserModel = getModelForClass(User);

// 3. Se connecter à la base de données et travailler
async function main() {
  await mongoose.connect('mongodb://localhost:27017/test');

  // Créer un utilisateur
  const user = await UserModel.create({
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
  });

  console.log('Créé :', user);

  // Trouver un utilisateur
  const found = await UserModel.findOne({ email: 'alice@example.com' });
  console.log('Trouvé :', found);
}

main().catch(console.error);

Cet exemple minimal illustre l'idée principale : la classe User avec le décorateur @prop décrit le schéma, et la fonction getModelForClass crée un modèle Mongoose prêt à l'emploi.

Méthodes et fonctions principales

1. @prop() — Décorateur de propriété

Signature : @prop(options?: PropOptions)

Description : Définit un champ dans le schéma Mongoose. Accepte un objet d'options similaire aux options de champ Mongoose (required, default, unique, ref, enum, etc.).

import { prop } from '@typegoose/typegoose';

class Product {
  @prop({ required: true, type: String })
  public title!: string;

  @prop({ default: 0, min: 0 })
  public price!: number;

  @prop({ enum: ['actif', 'inactif'], default: 'actif' })
  public status!: string;
}

2.