Объединения и сужение типов

Объединяй типы через `|` и `&`, сужай их с помощью `typeof`, `in` и сравнений, строй размеченные объединения и пиши собственные защитники типов.

  • Средний
  • 18 мин
  • 10 вопросов
  • Урок 5 из 8

В этом уроке ты узнаешь

  • Записывать и различать объединения (A | B) и пересечения (A & B)
  • Сужать тип с помощью typeof, in, === и проверки на null
  • Строить размеченное объединение и проверять через never, что обработаны все случаи
  • Писать защитник типа вида value is T

В жизни значения часто бывают разной формы. Номер заказа может быть и 42, и 'AB-17'. Оплата — картой или наличными. Сервер возвращает либо данные, либо сообщение об ошибке. Одним типом такие случаи не описать — нужно «это или то». Для этого в TypeScript есть объединения типов, а чтобы безопасно с ними работать, — сужение.

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

Тип number | string означает «либо число, либо строка». С таким значением можно делать только то, что допустимо для всех членов объединения. У числа нет метода toUpperCase, поэтому этот код ошибочен:

TypeScript
function shout(id: number | string): string {
  return id.toUpperCase();
}
Text
ids.ts:2:13 - error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

2   return id.toUpperCase();
              ~~~~~~~~~~~

Сужение типаОпределение

Уточнение типа значения внутри ветки if или switch: компилятор следит за твоими проверками (typeof, in, ===, instanceof и т. д.). Внутри ветки от объединения остаётся только подходящий член.

TypeScript
function formatId(id: number | string): string {
  if (typeof id === 'number') {
    return `#${id.toString().padStart(4, '0')}`;
  }
  return id.toUpperCase();
}

console.log(formatId(42));
console.log(formatId('ab-17'));

Ожидаемый результат

#0042
AB-17
Внутри if id — это number, а после return остаётся только string.

Чтобы читать дальше, зарегистрируйся бесплатно

Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.

Инструменты сужения

ПроверкаКогда использовать
typeof x === 'string'примитивные типы: string, number, boolean и т. д.
x === nullотделить null или undefined
'cardNumber' in xобъекты с разными свойствами
x instanceof Dateэкземпляры классов
x.kind === 'circle'размеченные объединения (ниже)
TypeScript
type Card = { cardNumber: string };
type Cash = { amount: number };

function describePayment(p: Card | Cash): string {
  if ('cardNumber' in p) {
    return `Card ending in ${p.cardNumber.slice(-4)}`;
  }
  return `Cash: ${p.amount} AZN`;
}

function greet(name: string | null): string {
  if (name === null) {
    return 'Hello, guest!';
  }
  return `Hello, ${name}!`;
}

console.log(describePayment({ cardNumber: 'XXXX-XXXX-XXXX-4821' }));
console.log(describePayment({ amount: 20 }));
console.log(greet(null), greet('Leyla'));

Ожидаемый результат

Card ending in 4821
Cash: 20 AZN
Hello, guest! Hello, Leyla!

Размеченные объединения

Самый мощный приём — дать каждому члену объединения свойство с одним и тем же именем, но разными литеральными значениями, обычно kind или type. Такое свойство называют дискриминантом. В switch (shape.kind) внутри каждого case TypeScript знает точный вид фигуры и разрешает только её свойства.

TypeScript
type Shape =
  | { kind: 'circle'; radius: number }
  | { kind: 'square'; side: number }
  | { kind: 'rectangle'; width: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case 'circle':
      return Math.PI * shape.radius ** 2;
    case 'square':
      return shape.side ** 2;
    case 'rectangle':
      return shape.width * shape.height;
  }
}

const shapes: Shape[] = [
  { kind: 'circle', radius: 1 },
  { kind: 'square', side: 3 },
  { kind: 'rectangle', width: 2, height: 5 },
];

for (const s of shapes) {
  console.log(s.kind, area(s).toFixed(2));
}

Ожидаемый результат

circle 3.14
square 9.00
rectangle 10.00

Что будет, если завтра кто-то из команды добавит в объединение треугольник? Чтобы гарантировать обработку всех случаев, в ветке default значение присваивают переменной типа never. never означает «никакое значение»: если все случаи обработаны, туда ничего не попадает. Если какой-то случай забыт, компилятор сразу сообщит:

TypeScript
type Shape =
  | { kind: 'circle'; radius: number }
  | { kind: 'square'; side: number }
  | { kind: 'triangle'; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case 'circle':
      return Math.PI * shape.radius ** 2;
    case 'square':
      return shape.side ** 2;
    default: {
      const unhandled: never = shape;
      return unhandled;
    }
  }
}
Text
area.ts:13:13 - error TS2322: Type '{ kind: "triangle"; base: number; height: number; }' is not assignable to type 'never'.

13       const unhandled: never = shape;
               ~~~~~~~~~
Сообщение об ошибке точно показывает, какой случай забыт, — треугольник.

Собственные защитники типов

Если вынести проверку в отдельную функцию, простого boolean в качестве результата недостаточно: TypeScript не заглядывает внутрь функции, чтобы сделать вывод. Если же записать возвращаемый тип как value is string, функция становится защитником типа (type guard): когда она возвращает true, компилятор верит, что значение — string. Особенно удобно это с filter:

TypeScript
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

const inputs: unknown[] = ['Baku', 42, 'Ganja', null, 'Shaki'];
const cities = inputs.filter(isString);

console.log(cities.map((city) => city.toUpperCase()).join(', '));

Ожидаемый результат

BAKU, GANJA, SHAKI
Благодаря защитнику cities имеет тип string[], а не unknown[], и можно вызывать toUpperCase.

Пересечения типов

Если объединение означает «одно из», то пересечение A & B означает «всё сразу»: у значения должны быть все свойства обоих типов. С помощью пересечений удобно собирать большие типы из небольших переиспользуемых частей:

TypeScript
type HasId = { id: number };
type HasDate = { createdAt: string };
type Post = HasId & HasDate & { title: string };

const post: Post = { id: 1, createdAt: '2025-09-01', title: 'Hello, TypeScript' };
console.log(`${post.id}: ${post.title} (${post.createdAt})`);

Ожидаемый результат

1: Hello, TypeScript (2025-09-01)

Запомни

  • A | B — «либо A, либо B»; напрямую можно использовать только общие для всех членов свойства.
  • Проверки typeof, ===, in и instanceof сужают тип внутри ветки.
  • В размеченном объединении у каждого члена есть литеральное свойство вроде kind; switch идеально его сужает.
  • Присваивание переменной типа never в ветке default находит забытые случаи при компиляции.
  • Функция, возвращающая value is T, — защитник типа; A & B объединяет все свойства обоих типов.
Заметил ошибку или неточность в уроке?

Проверь себя

Вопросов: 10. Каждый правильный ответ приносит XP.

Вопрос 1 / 10

Вопрос 1 / 10. Какой тип у параметра id: number | string внутри блока if (typeof id === 'number') { ... }?