Typy unii w TypeScript: operator | z przykładami

Typ unii wymienia warianty rozdzielone przez |: wartość typu string | number to string albo liczba. Unie to sposób, w jaki TypeScript opisuje wartości, które mogą legalnie przyjmować więcej niż jedną postać, a kompilator każe ci sprawdzić, z którą postacią masz do czynienia, zanim użyjesz czegoś, co dotyczy tylko jej.

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

W każdej gałęzi sprawdzenia typeof zmienna id ma jeden typ. Ten krok to zawężanie i to on sprawia, że unie są praktyczne.

Dozwolone są tylko wspólne składowe

Przed zawężeniem możesz używać tylko tego, co obsługuje każdy element unii. toString() istnieje zarówno w stringach, jak i w liczbach, więc jest w porządku, a toUpperCase() istnieje tylko w stringach:

// 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'.

Druga linia nazywa element, któremu brakuje tej właściwości. Ta sama reguła działa w drugą stronę: wartości string | number nie da się przekazać do parametru typu string (TS2345), bo może to być liczba. Unia przyjmuje więcej wartości, a w zamian pozwala zrobić z nimi mniej, dopóki ich nie sprawdzisz.

Zawężanie unii

Zawężanie używa zwykłych sprawdzeń z JavaScriptu. TypeScript śledzi przepływ sterowania i usuwa elementy, gdy zostają wykluczone, więc po ostatnim sprawdzeniu zostaje tylko jeden:

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)

Pełną listę form zawężania znajdziesz na stronie o zawężaniu typów.

Unie typów literałów

Unia wartości literałów to zamknięty zbiór dozwolonych wartości. To najczęstsza unia w prawdziwym kodzie:

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'.

Porównanie z literałem zawęża: po if (current === "error") gałąź else wie, że current to jedna z pozostałych trzech wartości. W wielu projektach unie literałów zastępują enumy. O as const i o tym, jak wyprowadzić taką unię z tablicy, przeczytasz na stronie o typach literałów.

Unie typów obiektów

Gdy elementy są typami obiektów, właściwości wspólne dla wszystkich są dostępne od razu. Dla reszty sprawdź przez in, czy właściwość istnieje:

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

Przy uniach kilku kształtów obiektów czytelniejszy jest wzorzec ze wspólną właściwością-literałem, taką jak kind: "cat" / kind: "fish". Sprawdzenie tej jednej właściwości zawęża cały obiekt, a switch po niej można sprawdzić pod kątem pełnego pokrycia. Ten wzorzec to discriminated union.

Tablice i unie

To, gdzie stoją nawiasy, całkowicie zmienia znaczenie:

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

Przy iterowaniu po (string | number)[] każdy element ma typ unii i wymaga zawężenia, jak w callbacku reduce powyżej. Metody takie jak map i filter działają też na string[] | number[], a callback dostaje string | number.

Unie z null i undefined

Najczęstsza unia ze wszystkich to "wartość albo nic": string | null, User | undefined. To właśnie zwracają Array.prototype.find i Map.prototype.get, a właściwość opcjonalna name?: string przy odczycie ma typ string | undefined. Obsługa takich wartości przez ?., ?? i sprawdzanie null ma własną stronę: null i undefined.

Żeby usunąć elementy z istniejącej unii na poziomie typów, użyj wbudowanych typów narzędziowych: Exclude<"a" | "b" | "c", "a"> to "b" | "c", a NonNullable<string | null> to string.