io-ts für TypeScript: Vollständiges Handbuch mit Beispielen

Was ist io-ts und warum wird es benötigt?

\nio-ts ist eine Bibliothek für TypeScript, die eines der schmerzhaftesten Probleme bei der Entwicklung mit dieser Sprache löst: die Diskrepanz zwischen statischen Typen (zur Kompilierzeit) und tatsächlichen Daten (zur Laufzeit). TypeScript ist ein hervorragendes Werkzeug, aber sein Typsystem funktioniert nur während der Entwicklung. Wenn Ihre Anwendung gestartet wird, werden alle Typen gelöscht. Wenn Sie Daten von einer externen API, aus einem Formular auf einer Website, aus localStorage oder einer anderen Quelle erhalten, die nicht von Ihrem Compiler kontrolliert wird, können Sie nicht sicher sein, dass die Daten den deklarierten Typen entsprechen.\n

\nHier kommt die Laufzeitvalidierung ins Spiel. io-ts ermöglicht es Ihnen, ein Datenschema einmal zu definieren und es dann für zwei Zwecke zu verwenden:\n

\n
• Statische Typisierung (Compile-Zeit): TypeScript leitet Typen basierend auf Ihrem Schema ab und gewährleistet so die Codesicherheit während der Entwicklung.
\n
• Validierung zur Laufzeit (Runtime): io-ts prüft, ob die tatsächlichen Daten Ihrem Schema entsprechen, und gibt entweder ein erfolgreiches Ergebnis oder einen detaillierten Fehler zurück.
\n

\nDie Bibliothek basiert auf dem Konzept der Codecs. Ein Codec ist ein Objekt, das weiß, wie man Rohdaten dekodiert (prüft und umwandelt) in einen TypeScript-Typ und wie man diesen Typ zurück kodiert (serialisiert). Dies macht io-ts zu einem leistungsstarken Werkzeug nicht nur für die Validierung, sondern auch für die sichere Serialisierung/Deserialisierung von Daten.\n

Installation

\nio-ts ist eine Bibliothek für das Node.js-Ökosystem und Browser, daher wird sie über npm (oder yarn) installiert. Beachten Sie, dass io-ts fp-ts als Peer-Abhängigkeit benötigt, da es funktionale Konzepte wie Either und Option verwendet.\n

npm install io-ts fp-ts

\nOder, wenn Sie yarn verwenden:\n

yarn add io-ts fp-ts

\nNach der Installation können Sie die Bibliothek in Ihr Projekt importieren:\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';

Schnellstart: Erstes Beispiel

\nBeginnen wir mit einem einfachen Beispiel. Angenommen, wir erwarten ein Benutzerobjekt mit den Feldern name (String) und age (Zahl). Definieren wir ein Schema mit io-ts und versuchen wir, einige Daten zu validieren.\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';\n\n// 1. Schema (Codec) definieren\nconst User = t.type({\n    name: t.string,\n    age: t.number,\n});\n\n// 2. Funktion zum sicheren Abrufen des Typs\ntype User = t.TypeOf<typeof User>;\n\n// 3. Zu prüfende Daten\nconst validData = { name: 'Alice', age: 30 };\nconst invalidData = { name: 'Bob', age: 'zwanzig' }; // age - String, keine Zahl\n\n// 4. Validierung\nconst result1 = User.decode(validData);\nconst result2 = User.decode(invalidData);\n\nconsole.log(isRight(result1)); // true\nconsole.log(isLeft(result2));  // true\n\n// 5. Daten extrahieren (wenn Validierung erfolgreich war)\nif (isRight(result1)) {\n    const user: User = result1.right;\n    console.log(user.name); // Alice\n}\n\n// 6. Fehler behandeln\nif (isLeft(result2)) {\n    console.error('Validierungsfehler:', result2.left);\n    // Gibt eine Liste von Fehlern aus, z.B.:\n    // [ { value: 'zwanzig', context: [...], message: 'Ungültiger Wert "zwanzig" bereitgestellt für : { name: string, age: number }/age: number' } ]\n}\n

\nIn diesem Beispiel sehen wir das Schlüsselmuster: decode gibt ein Either<Errors, A> aus der Bibliothek fp-ts zurück. Either ist ein Container, der entweder einen Fehler (linker Typ) oder einen erfolgreichen Wert (rechter Typ) enthalten kann. Wir überprüfen das Ergebnis mit den Funktionen isRight und isLeft.\n

Grundlegende Methoden und Funktionen von io-ts

\nio-ts bietet