TypeBox TypeScript: Methoden, Beispiele, Installation |…

Was ist TypeBox und warum braucht man es?

TypeBox ist eine leistungsstarke Bibliothek für TypeScript, mit der Sie Datenschemata definieren können, die mit dem JSON Schema Standard kompatibel sind. Gleichzeitig leitet sie daraus korrekte statische TypeScript-Typen ab. Einfach gesagt: Es ist die Brücke zwischen der Runtime-Validierung (wenn Ihre Anwendung läuft und Daten in Echtzeit prüft) und den Compile-Time-Typen (wenn TypeScript die Code-Korrektheit vor der Ausführung prüft).

Warum ist das wichtig? In der modernen Webentwicklung kommen Daten oft aus unsicheren Quellen: API-Anfragen, Webformulare, Konfigurationsdateien. Ohne Validierung riskieren Sie schwer zu findende Laufzeitfehler. TypeBox löst dieses Problem elegant: Sie beschreiben das Schema einmal und erhalten:

Runtime-Validator — prüft, ob ein Objekt dem Schema während der Programmausführung entspricht.
Statischen Typ — TypeScript leitet automatisch den Typ ab, den Sie für Annotationen nutzen können.
JSON Schema — das Schema kann in JSON serialisiert und in anderen Tools verwendet werden (z. B. zur Generierung von UI-Formularen oder Dokumentation).

TypeBox ist ideal für: API-Endpunkte mit Request-Body-Validierung, Konfigurationsdateien, komplexe Formulare mit Feldprüfung und jedes Szenario, bei dem Typsicherheit auf allen Ebenen wichtig ist.

TypeBox installieren

TypeBox ist eine Bibliothek für Node.js/TypeScript und wird daher über npm (oder yarn/pnpm) installiert.

npm install @sinclair/typebox

Nach der Installation können Sie sie in Ihr Projekt importieren:

import { Type } from '@sinclair/typebox';

Für die Validierung benötigen Sie zusätzlich einen Validator. TypeBox enthält standardmäßig keinen, um Ihnen die Wahl zu lassen. Empfohlen werden @sinclair/typebox/compiler (der integrierte Compiler) oder ajv (ein beliebter JSON-Schema-Validator). Installieren wir den Compiler:

npm install @sinclair/typebox-compiler

Oder, falls Sie AJV bevorzugen:

npm install ajv ajv-formats

Wichtig: Die Bibliothek heißt @sinclair/typebox, nicht nur typebox. Das ist für die korrekte Installation entscheidend.

Schnellstart mit einem Codebeispiel

Erstellen wir ein einfaches Schema für einen Benutzer und prüfen es.

import { Type } from '@sinclair/typebox';
import { TypeCompiler } from '@sinclair/typebox/compiler';

// 1. Benutzerschema definieren
const UserSchema = Type.Object({
    id: Type.Number(),
    name: Type.String({ minLength: 2 }),
    email: Type.String({ format: 'email' }),
    age: Type.Optional(Type.Number({ minimum: 0, maximum: 120 })),
});

// 2. Compiler für die Validierung erstellen
const validator = TypeCompiler.Compile(UserSchema);

// 3. Testdaten
const validUser = {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
};

const invalidUser = {
    id: 'not-a-number',
    name: 'A',
    email: 'invalid-email',
};

// 4. Validierung
console.log(validator.Check(validUser));   // true
console.log(validator.Check(invalidUser)); // false

// 5. Statischen Typ abrufen
type UserType = Static<typeof UserSchema>;
// UserType ist jetzt { id: number; name: string; email: string; age?: number; }

In diesem Beispiel haben wir ein Schema definiert, es in einen Validator kompiliert und zwei Objekte geprüft. Beachten Sie die Verwendung von Type.Optional für das Feld age – es kann fehlen. Außerdem haben wir format: 'email' zur Prüfung des E-Mail-Formats genutzt.