Typegoose für TypeScript: Das vollständige Handbuch

Typegoose ist eine leistungsstarke Wrapper-Bibliothek für Mongoose, mit der Sie MongoDB-Modelle mithilfe von TypeScript-Klassen und -Dekorateuren definieren können. Sie löst ein zentrales Problem der Node.js-Entwicklung: die Diskrepanz zwischen der strengen Typisierung von TypeScript und der dynamischen Natur von Mongoose. Anstatt Typen und Schemata manuell zu duplizieren, können Sie mit Typegoose das Modell einmal als TypeScript-Klasse beschreiben – die Mongoose-Schemata werden daraus automatisch generiert.

Warum ist das sinnvoll? Erstens reduziert es die Menge an Boilerplate-Code erheblich. Sie müssen kein separates Interface und kein separates Schema mehr schreiben – die TypeScript-Klasse übernimmt beide Aufgaben. Zweitens gewährleistet Typegoose vollständige Typsicherheit in allen Phasen: von der Dokumenterstellung bis zur Ausführung von Abfragen. Ihre IDE schlägt Felder, Methoden und deren Typen vor, was Fehler durch Tippfehler in Feldnamen oder falsche Datentypen praktisch ausschließt. Drittens unterstützt die Bibliothek alle Mongoose-Funktionen: virtuelle Felder, Hooks (pre/post), Indizes, Populate und Middleware.

Typegoose ist ideal für große Projekte, bei denen die Wartbarkeit des Codes wichtig ist, sowie für Teams, die alle Vorteile der objektorientierten Programmierung in TypeScript nutzen möchten. Es lässt sich problemlos in NestJS, Express und andere Frameworks integrieren und bietet einen einheitlichen Standard für die Datenbeschreibung.

Installation

Führen Sie zur Installation von Typegoose und seinen Abhängigkeiten im Terminal aus:

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

Wenn Sie yarn verwenden:

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

Für Typegoose wird TypeScript Version 4.0 oder höher benötigt. Stellen Sie sicher, dass in Ihrer tsconfig.json die folgenden Optionen aktiviert sind:

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

Schnellstart

Erstellen wir ein einfaches Benutzermodell und speichern es in MongoDB.

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

// 1. Modellklasse definieren
class User {
  @prop({ required: true })
  public name!: string;

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

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

// 2. Mongoose-Modell generieren
const UserModel = getModelForClass(User);

// 3. Mit der Datenbank verbinden und arbeiten
async function main() {
  await mongoose.connect('mongodb://localhost:27017/test');

  // Benutzer erstellen
  const user = await UserModel.create({
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
  });

  console.log('Erstellt:', user);

  // Benutzer finden
  const found = await UserModel.findOne({ email: 'alice@example.com' });
  console.log('Gefunden:', found);
}

main().catch(console.error);

Dieses minimale Beispiel zeigt die grundlegende Idee: Die Klasse User mit dem Dekorateur @prop beschreibt das Schema, und die Funktion getModelForClass erstellt ein einsatzbereites Mongoose-Modell.

Wichtige Methoden und Funktionen

1. `@prop()` — Der Eigenschafts-Dekorateur

Signatur: @prop(options?: PropOptions)

Beschreibung: Definiert ein Feld im Mongoose-Schema. Akzeptiert ein Optionsobjekt, das den Feldoptionen in Mongoose ähnelt (required, default, unique, ref, enum usw.).

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: ['active', 'inactive'], default: 'active' })
  public status!: string;
}