В жизни значения часто бывают разной формы. Номер заказа может быть и 42, и 'AB-17'. Оплата — картой или наличными. Сервер возвращает либо данные, либо сообщение об ошибке. Одним типом такие случаи не описать — нужно «это или то». Для этого в TypeScript есть объединения типов, а чтобы безопасно с ними работать, — сужение.
Объединения типов
Тип number | string означает «либо число, либо строка». С таким значением можно делать только то, что допустимо для всех членов объединения. У числа нет метода toUpperCase, поэтому этот код ошибочен:
function shout(id: number | string): string {
return id.toUpperCase();
}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 и т. д.). Внутри ветки от объединения остаётся только подходящий член.
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' | размеченные объединения (ниже) |
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 знает точный вид фигуры и разрешает только её свойства.
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 означает «никакое значение»: если все случаи обработаны, туда ничего не попадает. Если какой-то случай забыт, компилятор сразу сообщит:
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;
}
}
}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:
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 означает «всё сразу»: у значения должны быть все свойства обоих типов. С помощью пересечений удобно собирать большие типы из небольших переиспользуемых частей:
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объединяет все свойства обоих типов.