Объединения: значение одного из нескольких типов

Объединение собирается вертикальной чертой: слева и справа от неё — типы, любой из которых допустим. Черта тут не «или-или» из логики, а перечисление: string | number — это множество значений, в котором есть все строки и все числа, и ничего больше.

// на складе артикул хранят то числом, то строкой — настоящие оба варианта
let sku: string | number = 1024;
sku = "A-1024";
console.log(sku);
sku = true;

Диагностика знакомая по главе про базовые типы: Тип "boolean" не может быть назначен для типа "string | number". Обратите внимание, как компилятор пишет само объединение — той же чертой, что и вы. Этот текст ещё не раз встретится в сообщениях, и читать его нужно как «список допустимого».

В параметрах функции объединение работает так же: внутрь пускают любой из вариантов и не пускают всё остальное.

function describe(id: string | number) {
  console.log("артикул: " + String(id));
}
describe(1024);
describe("A-1024");
describe([1024]);

Третий вызов — тот самый случай, ради которого типы и нужны. Компилятор сказал Аргумент типа "number[]" нельзя назначить параметру типа "string | number", а движок отработал молча и напечатал артикул: 1024: String([1024]) честно даёт "1024". Ошибка есть, а внешне всё в порядке — до того дня, когда в массиве окажется два элемента.

Писать объединение руками приходится не всегда: чаще компилятор собирает его сам, когда ветки кода возвращают разное. Это тот же вывод типов, что и в статье про наведение, просто результат теперь составной.

const answer = Math.random() > 0.5 ? 1 : "нет";
const n: number = answer;
console.log(typeof answer);

Объединение читается как «одно из», а не «и то и другое сразу». Значение всегда одного конкретного типа — просто в тексте программы не написано, какого именно.

Раз значение может оказаться любым из вариантов, компилятор разрешает с ним лишь то, что безопасно для каждого. Свойство, которое есть у строки, но отсутствует у числа, под запретом — иначе половина вызовов упала бы на исполнении.

function badge(id: string | number) {
  console.log(id.toUpperCase());
}
badge("a-1024");
badge(1024);

Диагностика приходит с вложенной причиной, ровно как разбиралось в статье про чтение сообщений: Свойство "toUpperCase" не существует в типе "string | number", а строкой ниже — Свойство "toUpperCase" не существует в типе "number". Первая строка называет проблему, вторая — виновника: конкретный вариант, на котором обещание ломается.

А дальше пример показывает, зачем всё это затевалось. Первый вызов печатает A-1024, второй падает с TypeError: id.toUpperCase is not a function. Предупреждение прозвучало ещё до запуска и показывало пальцем ровно на числовой вариант — тот, что и сломался.

Что же тогда разрешено? Всё, что есть у каждого варианта. toString объявлен и у строки, и у числа — значит, он есть и у объединения, и такой код проходит без единой диагностики.

function label(id: string | number) {
  console.log(id.toString().padStart(8, "0"));
}
label(1024);
label("A-1024");

«Общее» считается по свойствам, а не по родству типов. Варианты могут быть сколь угодно разными: если нужное имя есть у обоих — доступ открыт, и тип результата тоже станет объединением.

function size(value: string | string[]) {
  console.log(value.length);
  console.log(value.concat("!"));
  console.log(value.toUpperCase());
}
size("да");

Запуск, кстати, напечатает и ДА: передали-то мы строку, а у неё toUpperCase есть. Компилятор отвечает не за конкретный вызов, а за все возможные — и запрещает то, что сломается хотя бы на одном варианте.

С объектами правило то же самое, только выглядит нагляднее: доступны поля, объявленные во всех вариантах.

type Cat = { name: string; meow: () => void };
type Dog = { name: string; bark: () => void };

function speak(pet: Cat | Dog) {
  console.log(pet.name);
  pet.bark();
}
speak({ name: "Мурка", meow: () => console.log("мяу") });

Вложенная причина здесь сообщает Свойство "bark" не существует в типе "Cat" — назван первый вариант, который не подошёл. И снова предупреждение сбылось буквально: Мурка напечаталась, а следующая строка дала TypeError: pet.bark is not a function.

Объединение — не объект, в котором есть все поля сразу. Это выбор из вариантов, и до проверки видна только их общая часть.

let id: string | number = 1024;
console.log(id.toUpperCase());

function plus(value: string | number) {
  console.log(value + 1);
}
plus(1024);
plus("A-");

Самое частое объединение в реальном коде состоит не из string и number, а из литеральных типов — тех самых, где «круг» был типом. Перечислили допустимые значения через черту — получили тип, в который больше ничего не влезет.

type Status =
  | "новая"
  | "в работе"
  | "готова";

function setStatus(next: Status) {
  console.log("статус: " + next);
}
setStatus("готова");
setStatus("готово");

Черта перед первым вариантом — не опечатка, а привычное оформление длинных объединений: так строки выравниваются и любой вариант удаляется целой строкой. Компилятор к ведущей черте относится спокойно.

Ценность видна по выводу: движок напечатал статус: готово и глазом не моргнул. Ровно так эта опечатка и жила бы, будь параметр объявлен как string, — уехала бы в хранилище, в отчёт, в чужой код. Объединение литералов ловит её на сборке, а иногда компилятор ещё и подсказывает правильный вариант.

type Status = "новая" | "в работе" | "готова";
type Task = { title: string; status: Status };

const tasks: Task[] = [
  { title: "Написать статью", status: "в работе" },
  { title: "Проверить примеры", status: "готово" }
];
console.log(tasks.length);

Здесь код не TS2345, а TS2820, и текст с продолжением: Тип ""готово"" невозможно присвоить типу "Status". Вы имели в виду ""готова""? Компилятор сравнил строку с вариантами, нашёл близкий и предложил замену. Отдельный код нужен как раз для того, чтобы редактор смог показать быстрое исправление.

Смешивать литералы с обычными типами тоже можно — так описывают значения вида «число или ключевое слово». В CSS такого добра много.

// ширина — это либо число пикселей, либо слово auto
type Width = number | "auto";

function setWidth(value: Width) {
  console.log(typeof value === "number" ? value + "px" : value);
}
setWidth(320);
setWidth("auto");
setWidth("100%");

Объединение литералов — это список допустимых значений, записанный в типе. Тип string разрешает миллион строк, из которых верны три.

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

function need(text: string) {
  return text.length;
}
function pass(value: string | number) {
  console.log(need(value));
}
pass("абв");
pass(1024);

Вложенная причина опять называет виновника: Тип "number" не может быть назначен для типа "string". И опять диагностика сбывается — второй вызов печатает undefined, потому что у числа нет свойства length. Не падение, а тихая чепуха в логах: такие ошибки ищут дольше всего.

Отдельная ловушка — скобки. Запись (string | number)[] и запись string[] | number[] выглядят похоже, а означают разное: первая — один массив со смешанным содержимым, вторая — выбор между двумя однородными массивами.

const mixed: (string | number)[] = ["A-1", 1024];
mixed.push(2048);
mixed.push("A-2");
console.log(mixed.join(", "));

function fill(list: string[] | number[]) {
  list.push("A-3");
  console.log(list.length);
}
fill(["A-1"]);

Сообщение Аргумент типа ""A-3"" нельзя назначить параметру типа "never" сначала обескураживает. Логика такая: push у массива строк принимает строки, у массива чисел — числа, а какой из двух перед нами, неизвестно. Значит, добавить можно лишь то, что подходит обоим сразу, — а таких значений не существует. Пустой набор компилятор и называет never; отдельная статья главы посвящена ему целиком.

Скобки в типах значат ровно то же, что в арифметике. (string | number)[] — массив из «одного из», string[] | number[] — «один из» массивов.

Ограничение «только общее» не тупик, а требование определённости: хотите методы строки — сначала покажите, что перед вами строка. Доказательством служит обычная проверка, которая работала бы и в чистом JavaScript.

function printId(id: string | number) {
  if (typeof id === "string") {
    console.log(id.toUpperCase());
  } else {
    console.log(id.toFixed(2));
  }
}
printId("a-1024");
printId(1024);

Ни одной диагностики, хотя обе строки по отдельности запрещены. Компилятор проследил поток выполнения и понял, в какую ветку какие значения попадают. Приём называется сужением типа, и ему посвящена почти вся эта глава — от typeof до собственных проверок.

Второй честный выход — не выбирать вариант, а привести значение к общему знаменателю. Часто это проще проверки: функции вроде String принимают что угодно.

function badge(id: string | number) {
  console.log(String(id).toUpperCase());
}
badge("a-1024");
badge(1024);

А есть выход ложный, и встретите вы его в чужом коде обязательно. Оператор as ничего не проверяет — он утверждает. Компилятор соглашается смотреть на значение как на строку, потому что строка входит в объединение, и замолкает.

function textLength(value: string | number) {
  return (value as string).length;
}
console.log(textLength("A-1024"));
console.log(textLength(1024));

Диагностик ноль, а второй вызов врёт. В отличие от примера с toUpperCase, здесь даже не будет TypeError: у числа просто нет свойства length, и вместо ошибки в логах появляется undefined. Разница с проверкой принципиальная — typeof живёт до запуска и после него, as исчезает при компиляции и не оставляет после себя ни одной инструкции.

Проверка спрашивает у значения. as сообщает компилятору. Первое можно перепроверить на исполнении, второе — только на словах.