TypeScript Union Types: der Operator | mit Beispielen

Ein Union-Typ listet Alternativen mit | auf: Ein Wert vom Typ string | number ist entweder ein String oder eine Zahl. Mit Unions beschreibt TypeScript Werte, die berechtigterweise mehr als eine Form annehmen können, und der Compiler zwingt dich zu prüfen, welche Form du hast, bevor du etwas Formspezifisches verwendest.

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

In jedem Zweig der Prüfung mit typeof hat id einen einzigen Typ. Dieser Schritt heißt Narrowing, und er macht Unions praktisch nutzbar.

Nur gemeinsame Member sind erlaubt

Vor dem Einengen kannst du nur verwenden, was jeder Member der Union unterstützt. toString() gibt es auf Strings und Zahlen, das ist also in Ordnung; toUpperCase() gibt es nur auf Strings:

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

Die zweite Zeile nennt den Member, dem die Eigenschaft fehlt. Dieselbe Regel gilt in die andere Richtung: Ein Wert vom Typ string | number kann nicht an einen als string typisierten Parameter übergeben werden (TS2345), weil er eine Zahl sein könnte. Eine Union akzeptiert mehr Werte und lässt dich dafür weniger mit ihnen tun, bis du prüfst.

Eine Union einengen

Narrowing nutzt gewöhnliche JavaScript-Prüfungen. TypeScript folgt dem Kontrollfluss und entfernt Member, sobald sie ausgeschlossen sind, sodass nach der letzten Prüfung nur ein Member übrig bleibt:

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

Die vollständige Liste der Formen des Narrowing steht auf der Seite zu Type Narrowing.

Unions aus Literaltypen

Eine Union aus Literalwerten ist eine geschlossene Menge erlaubter Werte. Sie ist die häufigste Union in echtem Code:

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

Der Vergleich mit einem Literal engt ein: Nach if (current === "error") weiß der else-Zweig, dass current einer der anderen drei ist. Literal-Unions ersetzen in vielen Codebasen Enums; unter Literaltypen stehen as const und wie man eine solche Union aus einem Array ableitet.

Unions aus Objekttypen

Sind die Member Objekttypen, sind Eigenschaften, die alle teilen, direkt verfügbar. Für den Rest prüfst du mit in, ob die Eigenschaft existiert:

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

Bei Unions aus mehreren Objektformen ist ein gemeinsames Literal-Feld wie kind: "cat" / kind: "fish" das sauberere Muster. Die Prüfung dieser einen Eigenschaft engt das ganze Objekt ein, und ein switch darüber lässt sich auf Vollständigkeit prüfen. Dieses Muster ist eine Discriminated Union.

Arrays und Unions

Wo die Klammern stehen, ändert die Bedeutung komplett:

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

Beim Durchlaufen eines (string | number)[] ist jedes Element die Union und muss eingeengt werden, wie im Callback von reduce oben. Methoden wie map und filter funktionieren auch auf einem string[] | number[], wobei der Callback string | number bekommt.

Unions mit null und undefined

Die häufigste Union überhaupt ist „ein Wert oder nichts“: string | null, User | undefined. Das geben Array.prototype.find und Map.prototype.get zurück, und eine optionale Eigenschaft name?: string liest sich als string | undefined. Wie du sie mit ?., ?? und Null-Prüfungen behandelst, steht auf einer eigenen Seite: null und undefined.

Um Member auf Typebene aus einer vorhandenen Union zu entfernen, nimm die eingebauten Utilities: Exclude<"a" | "b" | "c", "a"> ist "b" | "c", und NonNullable<string | null> ist string.