re:re:actable
Урок 013 минуты чтения

Union-типы: как объединить несколько типов

На этой странице
Кратко

Union-тип A | B означает «значение типа A или типа B». Union объединяет примитивы (string | number), литералы ("idle" | "loading"), объекты и null. Использовать можно только то, что есть у всех вариантов; чтобы обратиться к специфичным свойствам, тип сужают проверками (typeof, in, дискриминатор). С точки зрения множеств union — объединение множеств значений.

Вопрос

Что такое union-типы? Как объединить несколько типов, в том числе примитивы и объекты, и как работать со значением union-типа?

Объединение типов

type Id = string | number;
type Status = "idle" | "loading" | "success" | "error";
type MaybeUser = User | null;
type Input = string | string[];
 
function printId(id: Id) {
  console.log(id);
}
 
printId(42);
printId("abc");
printId(true); // ошибка

Доступны только общие члены

function format(id: string | number) {
  id.toUpperCase(); // ошибка: Property 'toUpperCase' does not exist on type 'number'
  id.toString();    // OK — есть у обоих
}

Сужение

function format(id: string | number) {
  if (typeof id === "string") {
    return id.toUpperCase();     // string
  }
  return id.toFixed(2);           // number
}
 
function wrap(input: string | string[]) {
  return Array.isArray(input) ? input : [input];
}

Union примитивов и объектов

type Price = number | { amount: number; currency: string };
 
function formatPrice(price: Price) {
  if (typeof price === "number") {
    return `${price} ₽`;
  }
  return `${price.amount} ${price.currency}`;
}

Union объектов

type Cat = { meow(): void; name: string };
type Dog = { bark(): void; name: string };
 
function speak(pet: Cat | Dog) {
  pet.name;                        // OK — общее поле
  if ("meow" in pet) pet.meow();   // сужение через in
  else pet.bark();
}

Удобнее всего union объектов с общим полем-дискриминатором — discriminated union:

type Result =
  | { ok: true; data: User }
  | { ok: false; error: string };

Union литералов вместо enum

type Size = "s" | "m" | "l";
 
function setSize(size: Size) {}
setSize("m");   // автодополнение и проверка
setSize("xl");  // ошибка

Union как множества

Union — объединение множеств значений: string | number содержит все строки и все числа. Поэтому:

type A = string | never;    // string — пустое множество ничего не добавляет
type B = string | unknown;  // unknown — поглощает
type C = "a" | string;      // string — литерал уже входит в string

Что важно помнить

  • Скобки важны: (string | number)[] — массив смешанных значений, string | number[] — строка или массив чисел.
  • Union в параметре функции делает функцию гибкой, union в возвращаемом значении заставляет вызывающий код проверять тип.
  • Слишком широкие union (string | number | boolean | object) — признак плохо продуманной модели.
  • Условные типы распределяются по union (distributive conditional types).

Мини-шпаргалка

  • A | B — значение одного из типов.
  • Доступны только общие члены.
  • Специфичное — после сужения: typeof, Array.isArray, in, дискриминатор.
  • Union литералов — замена enum.
  • Union — объединение множеств значений.

Документация

TypeScript Handbook: Union Types, TypeScript Handbook: Narrowing.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам