Типы объединения в TypeScript: оператор | с примерами

Тип объединения перечисляет варианты через |: значение типа string | number это либо строка, либо число. Через объединения TypeScript описывает значения, которые законно могут принимать больше одной формы, и компилятор заставляет проверить, какая форма перед вами, прежде чем использовать что-то специфичное для неё.

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

Внутри каждой ветки проверки typeof у id один тип. Этот шаг называется сужением, и именно он делает объединения практичными.

Разрешены только общие члены

До сужения можно использовать только то, что поддерживает каждый член объединения. toString() есть и у строк, и у чисел, поэтому он допустим; toUpperCase() есть только у строк:

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

Вторая строка называет член, у которого нет свойства. То же правило действует и в обратную сторону: значение string | number нельзя передать в параметр с типом string (TS2345), потому что оно может оказаться числом. Объединение принимает больше значений, а взамен позволяет делать с ними меньше, пока вы не проверите.

Сужение объединения

Сужение использует обычные проверки JavaScript. TypeScript следит за потоком управления и убирает члены по мере их исключения, так что после последней проверки остаётся один член:

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)

Полный список форм сужения есть на странице о сужении типов.

Объединения литеральных типов

Объединение литеральных значений это закрытый набор допустимых значений. Это самое распространённое объединение в реальном коде:

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

Сравнение с литералом сужает тип: после if (current === "error") ветка else знает, что current это один из трёх оставшихся вариантов. Во многих кодовых базах литеральные объединения заменяют enum; про as const и о том, как вывести такое объединение из массива, см. литеральные типы.

Объединения объектных типов

Если члены это объектные типы, свойства, общие для всех, доступны сразу. Для остальных проверьте наличие свойства через in:

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

Для объединений нескольких структур объектов более чистый приём это общее литеральное свойство вроде kind: "cat" / kind: "fish". Проверка этого одного свойства сужает весь объект, а switch по нему можно проверить на исчерпывающую обработку. Такой приём называется размеченным объединением.

Массивы и объединения

От того, где стоят скобки, смысл меняется полностью:

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

При переборе (string | number)[] каждый элемент имеет тип объединения, и его нужно сужать, как в колбэке reduce выше. Методы вроде map и filter работают и на string[] | number[], причём колбэк получает string | number.

Объединения с null и undefined

Самое распространённое объединение это «значение или ничего»: string | null, User | undefined. Именно это возвращают Array.prototype.find и Map.prototype.get, а необязательное свойство name?: string читается как string | undefined. Обработке таких значений через ?., ?? и проверки на null посвящена отдельная страница: null и undefined.

Чтобы убрать члены из существующего объединения на уровне типов, используйте встроенные утилиты: Exclude<"a" | "b" | "c", "a"> это "b" | "c", а NonNullable<string | null> это string.