← React / TypeScript

React / TypeScript · 19 / 24

TypeScript: Generics und unterscheidbare Union-Typen

Du modellierst Ladezustände ohne widersprüchliche Kombinationen und prüfst vollständige Fallunterscheidungen.

  • Groß
  • Anspruchsvoll
  • 90 min

Voraussetzungen: TypeScript-Typen und Module

In diesem Tutorial
  1. Das Zustandsmodell verstehen
  2. Das Projekt starten
  3. Den Vertrag mit einem Test prüfen
  4. Fehler und technische Grenzen beobachten
  5. Die Übung umsetzen
  6. Die Musterlösung überprüfen
  7. Übung und Lösung
  8. Projektbezug und Quellen

Lernpaket herunterladen

Einrichtung und Prüfstand

Node.js ab 22.23 mit npm. Zusätzlich Python 3 für den gemeinsamen Prüfstart. Entpacke das Lernpaket in einen neuen Ordner und führe dort python3 run_checks.py aus. Das Skript kopiert die enthaltenen Dateien in einen temporären Lernordner. Dort prüft es zuerst das Beispiel und danach die mitgelieferte Lösung. Die Ausgangsdateien bleiben erhalten. Benötigte Pakete werden beim ersten Lauf aus dem Netz geladen.

Geprüft am 20.10.2026 unter Linux x86_64. Prüfe gültige und leere Daten. Die Lösung ergänzt einen weiteren Zustand. Sowohl der Compiler als auch die Oberfläche müssen diesen Zustand behandeln. Ein Type-Cast würde die fehlende Behandlung nur verdecken.

Mehrere unabhängige boolesche Flags erlauben widersprüchliche Zustände. Eine Union beschreibt dagegen genau eine Variante. Der generische Parameter hält den Nutzdatentyp offen. Der Compiler prüft den eigenen Code, aber fremde JSON-Antworten brauchen weiterhin eine Laufzeitvalidierung.

Paketinhalt und einzelne Dateien

01Das Zustandsmodell verstehen

Ein generischer Typ erhält die Beziehung zwischen Eingabe und Ergebnis. Eine diskriminierte Union nutzt ein gemeinsames kind-Feld, um Zustände zu unterscheiden. Der vollständige switch macht neue Zustände beim Kompilieren sichtbar.

src/App.tsx · typescriptDatei öffnen
import { useState } from "react";
export type Load<T> =
  | { kind: "idle" }
  | { kind: "loading" }
  | { kind: "ready"; data: T }
  | { kind: "error"; message: string };
function unreachable(value: never): never {
  throw new Error(`Unexpected state: ${JSON.stringify(value)}`);
}
export function describe<T>(
  state: Load<T>,
  render: (data: T) => string,
): string {
  switch (state.kind) {
    case "idle":
      return "Not loaded";
    case "loading":
      return "Loading";
    case "ready":
      return render(state.data);
    case "error":
      return state.message;
    default:
      return unreachable(state);
  }
}
export default function App() {
  const [state, setState] = useState<Load<string[]>>({ kind: "idle" });
  return (
    <main>
      <h1>Vehicle states</h1>
      <p role="status">{describe(state, (rows) => rows.join(", "))}</p>
      <button onClick={() => setState({ kind: "ready", data: ["Family car"] })}>
        Load example
      </button>
    </main>
  );
}

02Das Projekt starten

Installiere die fest angegebenen Abhängigkeiten und starte npm run dev. Die Daten sind künstliche Lernwerte. Öffne die lokale Adresse und löse die Aktion einmal selbst aus.

package.json · jsonDatei öffnen
{
  "name": "appfabrik-learning",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "tsc --noEmit && vite build",
    "test": "vitest run src"
  },
  "dependencies": {
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "react-router-dom": "7.18.4",
    "@tanstack/react-query": "5.104.5"
  },
  "devDependencies": {
    "vite": "8.1.5",
    "typescript": "6.0.3",
    "@types/react": "19.2.14",
    "@types/react-dom": "19.2.3",
    "@types/node": "22.19.15",
    "vitest": "4.1.10",
    "@testing-library/react": "16.3.2",
    "@testing-library/user-event": "14.6.1",
    "jsdom": "29.1.1",
    "@playwright/test": "1.64.1"
  }
}

03Den Vertrag mit einem Test prüfen

Prüfe gültige und leere Daten. Die Lösung ergänzt einen weiteren Zustand. Sowohl der Compiler als auch die Oberfläche müssen diesen Zustand behandeln. Ein Type-Cast würde die fehlende Behandlung nur verdecken.

src/App.test.tsx · typescriptDatei öffnen
import { test, expect } from "vitest";
import { describe, type Load } from "./App";
test("all variants have a meaningful representation", () => {
  expect(describe({ kind: "idle" }, String)).toBe("Not loaded");
  expect(describe({ kind: "loading" }, String)).toBe("Loading");
  expect(
    describe({ kind: "ready", data: [1, 2] }, (rows) => rows.join(",")),
  ).toBe("1,2");
  expect(describe({ kind: "error", message: "Offline" }, String)).toBe(
    "Offline",
  );
});
// @ts-expect-error A ready state requires data.
const missing: Load<string> = { kind: "ready" };
void missing;

Starten / prüfen

npm install
npm test
npm run build
Erwartetes Ergebnis

Prüfe gültige und leere Daten. Die Lösung ergänzt einen weiteren Zustand. Sowohl der Compiler als auch die Oberfläche müssen diesen Zustand behandeln. Ein Type-Cast würde die fehlende Behandlung nur verdecken.

04Fehler und technische Grenzen beobachten

Ändere die erwartete Ausgabe und beobachte einen fehlgeschlagenen Test. Ein TypeScript-Build schützt Typverträge, ein Browsertest schützt Interaktionen. Beide Prüfarten erfüllen unterschiedliche Aufgaben.

05Die Übung umsetzen

Ergänze eine Variante empty und behandle sie ausdrücklich.

06Die Musterlösung überprüfen

Die Lösung ergänzt den Typ und den switch gemeinsam. Entferne den neuen case versuchsweise. tsc muss am never-Vertrag scheitern. So schützt die Prüfung auch künftige Erweiterungen. Kopiere die Lösungsdateien an die entsprechenden Stellen im Lernprojekt und starte Tests und Build erneut.

Erwartetes Ergebnis

Tests und Typprüfung bestehen. Das beobachtete Ergebnis entspricht dem Lernziel.

Deine Übung

Ergänze eine Variante empty und behandle sie ausdrücklich.

Lösung mit Erklärung anzeigen

Die Lösung ergänzt den Typ und den switch gemeinsam. Entferne den neuen case versuchsweise. tsc muss am never-Vertrag scheitern. So schützt die Prüfung auch künftige Erweiterungen.

solution/App.tsx · typescriptDatei öffnen
import { useState } from "react";
export type Load<T> =
  | { kind: "empty" }
  | { kind: "idle" }
  | { kind: "loading" }
  | { kind: "ready"; data: T }
  | { kind: "error"; message: string };
function unreachable(value: never): never {
  throw new Error(`Unexpected state: ${JSON.stringify(value)}`);
}
export function describe<T>(
  state: Load<T>,
  render: (data: T) => string,
): string {
  switch (state.kind) {
    case "empty":
      return "No vehicles";
    case "idle":
      return "Not loaded";
    case "loading":
      return "Loading";
    case "ready":
      return render(state.data);
    case "error":
      return state.message;
    default:
      return unreachable(state);
  }
}
export default function App() {
  const [state, setState] = useState<Load<string[]>>({ kind: "idle" });
  return (
    <main>
      <h1>Vehicle states</h1>
      <p role="status">{describe(state, (rows) => rows.join(", "))}</p>
      <button onClick={() => setState({ kind: "ready", data: ["Family car"] })}>
        Load example
      </button>
    </main>
  );
}
solution/App.test.tsx · typescriptDatei öffnen
import { test, expect } from "vitest";
import { describe, type Load } from "./App";
test("all variants have a meaningful representation", () => {
  expect(describe({ kind: "empty" }, String)).toBe("No vehicles");
  expect(describe({ kind: "idle" }, String)).toBe("Not loaded");
  expect(describe({ kind: "loading" }, String)).toBe("Loading");
  expect(
    describe({ kind: "ready", data: [1, 2] }, (rows) => rows.join(",")),
  ).toBe("1,2");
  expect(describe({ kind: "error", message: "Offline" }, String)).toBe(
    "Offline",
  );
});
// @ts-expect-error A ready state requires data.
const missing: Load<string> = { kind: "ready" };
void missing;

Projektbezug und Quellen

Das eigenständige Lernprojekt vertieft ein Thema aus diesem Technologiebereich. Die Projektverweise zeigen einen festgehaltenen Quellstand als Architekturkontext. Sie sind kein Beleg dafür, dass jede hier neu eingeführte Bibliothek oder Funktion bereits in dieser App verwendet wird.