Kurs JavaScript i React · Moduł 12: React i TypeScript

Discriminated Unions - Warianty Komponentów

5 min czytania ·
W tej lekcji5

Komponent karty obiektu kosmicznego dostaje raz planetę, raz gwiazdę, raz asteroidę. Wrzucasz wszystkie pola do jednego typu, oznaczasz je jako opcjonalne i po miesiącu nikt nie pamięta, czy gwiazda może mieć księżyce. W kosmosie różne obiekty wymagają różnego traktowania - planeta, gwiazda i asteroida to różne byty z różnymi właściwościami. Discriminated unions pozwalają TypeScript rozróżnić warianty obiektu na podstawie jednego pola.

Problem - różne kształty danych

Wyobraź sobie komponent, który wyświetla różne typy obiektów kosmicznych. Każdy typ ma inne pola. Najprostsze rozwiązanie wygląda niewinnie:

// ŹLE - nie wiadomo które pola są dostępne
interface SpaceObject {
  type: string;
  name: string;
  radius?: number;
  temperature?: number;
  composition?: string[];
  orbitalPeriod?: number;
}

function SpaceInfo({ obj }: { obj: SpaceObject }) {
  // Musisz sprawdzać każde pole z osobna
  if (obj.radius) { /* ... */ }
  if (obj.temperature) { /* ... */ }
  // Łatwo o błędy!
}

Taki typ pozwala stworzyć "planetę" z temperaturą gwiazdy i bez promienia - kompilator nie ma jak tego wykryć, bo wszystko jest opcjonalne. Dodatkowo if (obj.radius) pominie planetę o promieniu 0, bo zero jest fałszywe.

Rozwiązanie - discriminated unions

Zamiast jednego interfejsu z opcjonalnymi polami tworzymy osobne interfejsy połączone wspólnym polem (dyskryminatorem). Kluczowe jest to, że dyskryminator ma typ literalny: nie dowolny string, tylko jeden konkretny napis, na przykład kind: "planet". To po tym napisie TypeScript rozpozna wariant.

// Każdy typ ma wspólne pole 'kind' o różnej wartości
interface PlanetData {
  kind: "planet";
  name: string;
  radius: number;
  habitable: boolean;
  moons: number;
}

interface StarData {
  kind: "star";
  name: string;
  temperature: number;
  luminosity: number;
  spectralClass: string;
}

interface AsteroidData {
  kind: "asteroid";
  name: string;
  composition: string[];
  diameter: number;
}

Teraz łączymy trzy interfejsy znakiem | w jeden union type. Wartość typu SpaceObject jest dokładnie jednym z trzech wariantów, nigdy mieszanką:

// Union type - obiekt może być jednym z trzech typów
type SpaceObject = PlanetData | StarData | AsteroidData;

Planeta bez radius albo gwiazda z polem moons nie przejdą już kompilacji. Wszystkie pola w wariantach są wymagane - opcjonalność zniknęła, bo każdy wariant opisuje tylko to, co naprawdę ma.

Zawężanie typów (type narrowing)

TypeScript automatycznie zawęża typ na podstawie pola dyskryminatora. Gdy sprawdzisz obj.kind w instrukcji switch, wewnątrz każdego case kompilator wie, z którym wariantem pracujesz:

function SpaceInfo({ obj }: { obj: SpaceObject }) {
  // Wspólne pole - dostępne dla wszystkich wariantów
  const header = <h2>{obj.name}</h2>;

  // Switch na dyskryminator
  switch (obj.kind) {
    case "planet":
      // TypeScript WIE że obj to PlanetData
      return (
        <div>
          {header}
          <p>Promień: {obj.radius} km</p>
          <p>Księżyce: {obj.moons}</p>
          <p>{obj.habitable ? "Zamieszkiwalna" : "Niezamieszkiwalna"}</p>
        </div>
      );
    case "star":
      // TypeScript WIE że obj to StarData
      return (
        <div>
          {header}
          <p>Temperatura: {obj.temperature}K</p>
          <p>Klasa: {obj.spectralClass}</p>
        </div>
      );
    case "asteroid":
      // TypeScript WIE że obj to AsteroidData
      return (
        <div>
          {header}
          <p>Średnica: {obj.diameter} km</p>
          <p>Skład: {obj.composition.join(", ")}</p>
        </div>
      );
  }
}

Przed switch dostępne jest tylko wspólne pole name. W gałęzi "star" próba odczytu obj.moons zakończy się błędem, bo gwiazdy nie mają księżyców. Co się NIE zmieniło: w działającym kodzie to zwykły switch na tekście - cała magia dzieje się w kompilatorze.

Warianty komponentów UI

Discriminated unions są idealne do tworzenia wariantów komponentów UI. Alert sukcesu potrzebuje tylko wiadomości, ale alert błędu musi dostać akcję ponowienia. Typ może to wymusić:

// Warianty alertów
type AlertProps =
  | { variant: "success"; message: string }
  | { variant: "error"; message: string; retryAction: () => void }
  | { variant: "warning"; message: string; dismissable: boolean }
  | { variant: "info"; message: string; link?: string };

Tym razem warianty są zapisane w miejscu, bez osobnych interfejsów, a dyskryminatorem jest variant. Komponent przyjmuje całe props bez destrukturyzacji, bo destrukturyzacja przed sprawdzeniem wariantu utrudnia zawężanie. Klasy CSS składamy szablonem tekstowym:

function Alert(props: AlertProps) {
  const baseClass = "alert";

  switch (props.variant) {
    case "success":
      return <div className={`${baseClass} success`}>{props.message}</div>;
    case "error":
      return (
        <div className={`${baseClass} error`}>
          {props.message}
          <button onClick={props.retryAction}>Ponów</button>
        </div>
      );
    case "warning":
      return (
        <div className={`${baseClass} warning`}>
          {props.message}
          {props.dismissable && <button>Zamknij</button>}
        </div>
      );
    case "info":
      return (
        <div className={`${baseClass} info`}>
          {props.message}
          {props.link && <a href={props.link}>Więcej</a>}
        </div>
      );
  }
}

Wywołanie <Alert variant="error" message="Awaria" /> bez retryAction zostanie odrzucone - komponent nie pozwoli zbudować alertu błędu bez przycisku ratunkowego.

Exhaustive checking - nigdy nie przegap wariantu

Co jeśli za rok ktoś doda wariant "comet" i zapomni go obsłużyć? Pomoże typ never, oznaczający wartość, która nie może istnieć. Gdy switch obsłuży wszystkie warianty, w gałęzi default zmienna ma typ never. Funkcja assertNever przyjmuje wyłącznie never, więc każdy nieobsłużony wariant staje się błędem kompilacji:

// Funkcja pomocnicza - TypeScript zgłosi błąd jeśli nie obsłużysz wszystkich wariantów
function assertNever(value: never): never {
  throw new Error(`Nieobsłużony wariant: ${value}`);
}

function getLabel(obj: SpaceObject): string {
  switch (obj.kind) {
    case "planet": return "Planeta";
    case "star": return "Gwiazda";
    case "asteroid": return "Asteroida";
    default: return assertNever(obj); // błąd jeśli dodasz nowy typ i nie obsłużysz go
  }
}

Po dodaniu CometData do unii TypeScript wskaże linię z assertNever, zanim kod trafi do załogi. throw zadziała tylko wtedy, gdyby niepoprawne dane przyszły z zewnątrz w trakcie działania. Moja rada: dodawaj assertNever w każdym switch po dyskryminatorze - to tania polisa. W następnej lekcji discriminated union opisze akcje w useReducer.

Kod do tej lekcji: App.tsx
import React, { useState } from 'react';

// Discriminated union - rozne obiekty kosmiczne
interface PlanetData {
  kind: "planet";
  name: string;
  radius: number;
  habitable: boolean;
  moons: number;
}

interface StarData {
  kind: "star";
  name: string;
  temperature: number;
  luminosity: number;
  spectralClass: "O" | "B" | "A" | "F" | "G" | "K" | "M";
}

interface AsteroidData {
  kind: "asteroid";
  name: string;
  diameter: number;
  composition: string[];
  dangerLevel: 1 | 2 | 3 | 4 | 5;
}

type SpaceObject = PlanetData | StarData | AsteroidData;

// Komponent z type narrowing
function SpaceCard({ obj }: { obj: SpaceObject }) {
  const getIcon = (): string => {
    switch (obj.kind) {
      case "planet": return "●";
      case "star": return "*";
      case "asteroid": return "•";
    }
  };

  const renderDetails = (): React.ReactNode => {
    switch (obj.kind) {
      case "planet":
        return (
          <>
            <p>Promien: {obj.radius} km</p>
            <p>Ksiezyce: {obj.moons}</p>
            <span className={"badge " + (obj.habitable ? "green" : "red")}>
              {obj.habitable ? "Zamieszkiwalna" : "Niezamieszkiwalna"}
            </span>
          </>
        );
      case "star":
        return (
          <>
            <p>Temperatura: {obj.temperature}K</p>
            <p>Jasnosc: {obj.luminosity}x Slonce</p>
            <span className="badge blue">Klasa {obj.spectralClass}</span>
          </>
        );
      case "asteroid":
        return (
          <>
            <p>Srednica: {obj.diameter} km</p>
            <p>Sklad: {obj.composition.join(", ")}</p>
            <span className="badge orange">
              Zagrozenie: {"!".repeat(obj.dangerLevel)}
            </span>
          </>
        );
    }
  };

  return (
    <div className={"space-card " + obj.kind}>
      <div className="card-header">
        <span className="icon">{getIcon()}</span>
        <h3>{obj.name}</h3>
        <span className="kind">{obj.kind}</span>
      </div>
      <div className="card-body">{renderDetails()}</div>
    </div>
  );
}

function App() {
  const [objects] = useState<SpaceObject[]>([
    { kind: "planet", name: "Kepler-442b", radius: 8200, habitable: true, moons: 2 },
    { kind: "star", name: "Betelgeuse", temperature: 3500, luminosity: 126000, spectralClass: "M" },
    { kind: "asteroid", name: "Apophis", diameter: 370, composition: ["zelazo", "nikiel", "krzem"], dangerLevel: 4 },
    { kind: "planet", name: "HD 209458 b", radius: 94000, habitable: false, moons: 0 },
    { kind: "star", name: "Sirius", temperature: 9940, luminosity: 25, spectralClass: "A" },
    { kind: "asteroid", name: "Ceres", diameter: 939, composition: ["lod", "skala", "mineraly"], dangerLevel: 1 },
  ]);

  const [filter, setFilter] = useState<SpaceObject["kind"] | "all">("all");

  const filtered = filter === "all"
    ? objects
    : objects.filter(obj => obj.kind === filter);

  return (
    <div className="app">
      <h1>Katalog Obiektow Kosmicznych</h1>
      <div className="filters">
        {(["all", "planet", "star", "asteroid"] as const).map(f => (
          <button
            key={f}
            className={"filter-btn " + (filter === f ? "active" : "")}
            onClick={() => setFilter(f)}
          >
            {f === "all" ? "Wszystkie" : f === "planet" ? "Planety" : f === "star" ? "Gwiazdy" : "Asteroidy"}
          </button>
        ))}
      </div>
      <div className="cards">
        {filtered.map((obj, i) => <SpaceCard key={i} obj={obj} />)}
      </div>
    </div>
  );
}

export default App;

Pamiętaj: dyskryminator to sygnał rozpoznawczy obiektu - odczytaj go, a TypeScript sam przełączy czujniki na właściwy wariant.

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jakiego typu musi być pole dyskryminatora (np. kind) w discriminated union aby TypeScript mógł automatycznie zawężać typy?

  2. 2. Co to jest discriminated union w TypeScript?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w pionie

    Ułóż kolejność kroków tworzenia i używania discriminated union:

  • Edytor kodu

    Discriminated union dla wariantów komponentu

  • Klikanie w kolejności

    Ułóż składnię funkcji assertNever do sprawdzania wyczerpującego (exhaustive checking):

  • Układanie w poziomie

    Ułóż składnię definicji union type z trzech interfejsów:

  • Edytor kodu

    Generyczny discriminated union dla stanów asynchronicznych

  1. PytaniePole dyskryminatora w union type
  2. PytanieDiscriminated union w TypeScript
  3. Ułóż w kolejnościType narrowing z discriminated union
  4. Zadanie z kodemPraktyka: Komponent z discriminated unions
  5. PytanieGeneryki vs konkretne typy
  6. Kliknij w kolejnościFunkcja assertNever
  7. Ułóż w kolejnościDefinicja union type
  8. Zadanie z kodemPraktyka: Stany ładowania z discriminated union

Przydatne artykuły