Superstruct für TypeScript: Komplettguide mit Beispielen

Einführung in Superstruct

Superstruct ist eine leichte, aber leistungsstarke Bibliothek zur Validierung und Analyse von Datenstrukturen in TypeScript und JavaScript. Sie ermöglicht es Ihnen, die erwartete Form von Daten (Objekte, Arrays, Strings, Zahlen usw.) mit einfachen und ausdrucksstarken "Schemas" (Structs) zu beschreiben und anschließend zu prüfen, ob die tatsächlichen Daten diesen Schemas entsprechen.

Im Gegensatz zu anderen Validierungsbibliotheken wie Zod oder Yup konzentriert sich Superstruct auf Einfachheit, Leistung und Minimalismus. Es generiert nicht automatisch komplexe TypeScript-Typen (obwohl es gut mit ihnen zusammenarbeitet), sondern bietet eine flexible und intuitive API zur Beschreibung von Strukturen.

Wofür wird Superstruct verwendet?

• Validierung von Daten aus externen Quellen: API-Antworten, Formulardaten, Konfigurationsdateien, localStorage – überall dort, wo Daten in einem unerwarteten Format ankommen können.
• Erstellung sicherer DTOs (Data Transfer Objects): Stellt sicher, dass Daten, die zwischen Anwendungsschichten ausgetauscht werden, der erwarteten Struktur entsprechen.
• Parsen und Transformation: Superstruct kann Daten nicht nur prüfen, sondern auch umwandeln (z. B. Strings in Zahlen konvertieren).
• Lesbare Dokumentation: Superstruct-Schemas dienen gleichzeitig als hervorragende Dokumentation der Datenstruktur.

Installation

Superstruct ist ein npm-Paket und wird über den Node.js-Paketmanager installiert:

npm install superstruct

Oder, falls Sie Yarn verwenden:

yarn add superstruct

Nach der Installation können Sie die Bibliothek in Ihre TypeScript-Datei importieren:

import { struct, string, number, object, array, optional, union, literal, enums, size, refine, assert, is, validate } from 'superstruct';

Schnellstart

Erstellen wir ein einfaches Schema für einen Benutzer und validieren die Daten.

import { object, string, number, assert } from 'superstruct';

// 1. Schema (Struct) definieren
const User = object({
    id: number(),
    name: string(),
    email: string(),
});

// 2. Zu validierende Daten
const userData = {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
};

// 3. Validierung
try {
    assert(userData, User);
    console.log('Daten sind gültig!');
} catch (e) {
    console.error('Validierungsfehler:', e.message);
}

// 4. Bei ungültigen Daten wirft assert eine Exception
const badData = { id: 'keine Zahl', name: 'Bob' };
try {
    assert(badData, User);
} catch (e) {
    console.error('Fehler:', e.message);
    // Ausgabe: Expected a number for `id`, but received: "keine Zahl"
}

Wichtige Methoden und Funktionen

Superstruct bietet eine Reihe von Factory-Funktionen zur Erstellung von Schemas. Hier sind die 10 wichtigsten:

1. string()

Beschreibung: Erstellt ein Schema, das prüft, ob der Wert ein String ist.

Parameter: Keine.

import { string, assert } from 'superstruct';

const NameSchema = string();
assert('Hallo', NameSchema); // OK
// assert(123, NameSchema); // Fehler: Expected a string, but received: 123

2. number()

Beschreibung: Prüft, ob der Wert eine Zahl ist (einschließlich NaN, sofern nicht anders angegeben).

Parameter: Keine.

import { number, assert } from 'superstruct';

const AgeSchema = number();
assert(30, AgeSchema); // OK
// assert('30', AgeSchema); // Fehler

3. boolean()

Beschreibung: Prüft, ob der Wert ein Boolean ist (true oder false).

Parameter: Keine.

import { boolean, assert } from 'superstruct';

const IsActiveSchema = boolean();
assert(true, IsActiveSchema); // OK

4. object(schem