class-transformer TypeScript: Methoden, Beispiele…

Einführung in class-transformer: Was ist das und warum braucht man es?

class-transformer ist eine leistungsstarke Bibliothek für TypeScript und JavaScript, die es ermöglicht, einfache (plain) JavaScript-Objekte in Klasseninstanzen umzuwandeln und umgekehrt. Sie löst ein grundlegendes Problem: Bei der Arbeit mit Daten aus APIs, Datenbanken oder JSON-Dateien erhält man einfache Objekte ohne Methoden und Typen. class-transformer „belebt“ diese Daten, indem es sie in vollwertige Klassenobjekte mit Validierung, Transformation und Serialisierung verwandelt.

Die wichtigsten Anwendungsfälle:

Umwandlung von JSON aus APIs in typisierte Klassenobjekte – nach dem Erhalt einer Antwort von einer REST-API können Sie JSON automatisch in Instanzen Ihrer Modelle umwandeln.
Datenvalidierung und -transformation – mit Decorators können Sie festlegen, welche Felder erforderlich sind und welche transformiert werden müssen (z. B. String in Zahl oder Datum).
Serialisierung von Objekten in JSON – die Rückumwandlung von Klasseninstanzen in einfache Objekte zum Senden an den Client oder zum Speichern.
Arbeit mit verschachtelten Objekten und Arrays – die Bibliothek kann verschachtelte Datenstrukturen rekursiv transformieren.

class-transformer wird häufig zusammen mit class-validator (für die Validierung) und beliebten Frameworks wie NestJS, TypeORM und MikroORM verwendet.

Installation

Die Installation der Bibliothek erfolgt über npm oder yarn:

npm install class-transformer --save

Oder, wenn Sie yarn verwenden:

yarn add class-transformer

Um Decorators in TypeScript zu nutzen, müssen Sie die Unterstützung für experimentelle Decorators in Ihrer tsconfig.json aktivieren:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Es wird außerdem empfohlen, reflect-metadata zu installieren, damit die Decorators korrekt funktionieren:

npm install reflect-metadata --save

Und importieren Sie es ganz am Anfang Ihrer Anwendung (normalerweise in der Hauptdatei index.ts oder main.ts):

import 'reflect-metadata';

Schnellstart mit einem Codebeispiel

Erstellen wir ein einfaches Benutzermodell und wandeln JSON-Daten in eine Klasseninstanz um.

import { plainToClass, Expose, Type } from 'class-transformer';
import 'reflect-metadata';

// Definiere die User-Klasse
class User {
    @Expose()
    id: number;

    @Expose()
    firstName: string;

    @Expose()
    lastName: string;

    @Expose()
    @Type(() => Date)
    createdAt: Date;

    // Klassenmethode – nur nach der Transformation verfügbar
    getFullName(): string {
        return `${this.firstName} ${this.lastName}`;
    }
}

// Beispiel-Daten aus einer API (plain object)
const plainUser = {
    id: 1,
    firstName: 'Max',
    lastName: 'Mustermann',
    createdAt: '2024-01-15T10:30:00Z'
};

// Wandele das plain object in eine Instanz der User-Klasse um
const userInstance = plainToClass(User, plainUser);

console.log(userInstance instanceof User); // true
console.log(userInstance.getFullName());   // "Max Mustermann"
console.log(userInstance.createdAt);       // Date-Objekt: Tue Jan 15 2024 11:30:00 GMT+0100

Wie Sie sehen, erhalten wir ein vollwertiges Klassenobjekt mit Methoden und korrekt transformierten Typen (der Datums-String wurde zu einem Date-Objekt).

Wichtige Methoden und Funktionen von class-transformer

1. plainToClass

Was es tut: Wandelt ein oder mehrere einfache (plain) Objekte in Instanzen der angegebenen Klasse um. Dies ist die am häufigsten verwendete Methode.

Parameter: