typia für TypeScript: Komplettguide mit Praxisbeispielen

Was ist typia und warum braucht man es?

typia ist eine leistungsstarke Bibliothek für TypeScript, die Runtime-Typenprüfung (Runtime Type Validation) mit einer einzigartigen Eigenschaft bietet: Sie generiert den Prüfcode bereits zur Kompilierzeit (Compile-Time), nicht erst zur Laufzeit. Das macht sie zu einer der schnellsten Validierungsbibliotheken im TypeScript-Ökosystem.

Die Hauptprobleme, die typia löst:

• Leistung: Im Gegensatz zu beliebten Bibliotheken (zod, yup, io-ts) verwendet typia weder Reflection noch Decorators. Stattdessen generiert sie optimierten Prüfcode während des Build-Prozesses, was zu einer 10- bis 100-fachen Geschwindigkeitssteigerung führt.
• Typsicherheit: Sie erhalten die Garantie, dass Daten aus externen Quellen (APIs, Datenbanken, Formulare) Ihren TypeScript-Interfaces entsprechen.
• Minimaler Boilerplate-Code: Sie müssen keine separaten Validierungsschemata schreiben – typia verwendet Ihre vorhandenen TypeScript-Typen.
• Unterstützung komplexer Typen: Union, Intersection, Conditional Types, Mapped Types – alles funktioniert "out of the box".

Die Bibliothek ist besonders nützlich für:

• Backend-Entwicklung mit Node.js und TypeScript
• Frontend-Anwendungen, die Formularvalidierung oder API-Response-Prüfung benötigen
• Microservice-Architekturen, bei denen Serialisierungs-/Deserialisierungsgeschwindigkeit wichtig ist
• Projekte, bei denen Leistung und Typsicherheit kritisch sind

Installation

Die Installation von typia besteht aus zwei Schritten: der Bibliothek selbst und dem TypeScript-Transformer (Compiler).

Schritt 1: Installation via npm

npm install typia
# oder
yarn add typia
# oder
pnpm add typia

Schritt 2: Installation des Transformers

npm install --save-dev typia-transform
# oder
yarn add -D typia-transform
# oder
pnpm add -D typia-transform

Schritt 3: tsconfig.json konfigurieren

Fügen Sie das Plugin in Ihre tsconfig.json ein:

{
  "compilerOptions": {
    "plugins": [
      {
        "transform": "typia-transform"
      }
    ]
  }
}

Schritt 4: Verwendung mit ttypescript (empfohlen)

Installieren Sie ttypescript für die automatische Transformation:

npm install --save-dev ttypescript

Ersetzen Sie dann tsc durch ttsc in Ihren package.json-Skripten:

{
  "scripts": {
    "build": "ttsc",
    "start": "node dist/index.js"
  }
}

Wichtig: typia benötigt TypeScript Version 4.4 oder höher. Ohne den Transformer funktioniert die Bibliothek nicht.

Schnellstart mit Codebeispiel

Lassen Sie uns ein einfaches Beispiel zur Validierung von Benutzerdaten erstellen.

import typia from "typia";

// Interface definieren
interface IUser {
  id: number;
  name: string;
  email: string;
  age: number;
  isActive: boolean;
}

// Validierungsfunktion erstellen
const validateUser = typia.createValidate<IUser>();

// Testdaten
const testData = {
  id: 1,
  name: "Max Mustermann",
  email: "max@example.com",
  age: 30,
  isActive: true,
};

// Validierung
const result = validateUser(testData);

if (result.success) {
  console.log("Daten gültig:", result.data);
} else {
  console.log("Validierungsfehler:", result.errors);
}

// Beispiel mit ungültigen Daten
const badData = {
  id: "keine Zahl", // Sollte number sein
  name: "Max",
  email: "keine E-Mail",
  age: -5,
  isActive: "ja", // Sollte boolean sein
};

const badResult = validateUser(badData);
console.log("Fehler:", badResult.errors);

Dieses Beispiel zeigt, wie einfach Daten nur mit einem TypeScript-Interface validiert werden können. Keine zusätzlichen Schemata oder Decorators nötig!

Wichtige Methoden und Funktionen

1. typia.createValidate<T>()

Funktion: Erstellt eine Validierungsfunktion für den Typ T. Gibt ein Objekt mit den Eigenschaften success, data und errors zurück.