Type narrowing: что это, когда происходит и control flow analysis
На этой странице
Сужение типа (narrowing) — уточнение типа переменной внутри блока кода на основе проверок. Если value: string | number и вы проверили typeof value === "string", внутри if TypeScript считает value строкой. Анализ потока управления (control flow analysis) отслеживает проверки, return, throw и присваивания и вычисляет тип в каждой точке кода. Сужение позволяет безопасно работать с union, unknown и null без as.
Вопрос
Что такое type narrowing? Когда происходит сужение типов, зачем оно нужно и что такое control flow based narrowing?
Зачем нужно сужение
function format(value: string | number | null) {
value.toUpperCase(); // ошибка: метод есть не у всех вариантов union
if (value === null) return "—";
if (typeof value === "string") return value.toUpperCase(); // string
return value.toFixed(2); // number
}Без сужения пришлось бы использовать as и терять безопасность.
Способы сужения
| Проверка | Пример | Сужает до |
|---|---|---|
typeof | typeof x === "string" | примитивный тип |
| Равенство | x === null, x === "admin" | конкретное значение |
| Truthiness | if (user) | без null, undefined, "", 0 |
instanceof | error instanceof TypeError | класс |
in | "email" in contact | вариант с этим полем |
Array.isArray | Array.isArray(input) | массив |
| Дискриминатор | state.status === "success" | вариант discriminated union |
| Type guard | isUser(x) (x is User) | указанный тип |
| Assertion function | assertDefined(x) (asserts x) | тип после вызова |
Control flow analysis
TypeScript анализирует поток выполнения, а не только блоки if:
function getUser(id?: string) {
if (!id) {
throw new Error("Нет id"); // дальше id: string
}
const user = users.get(id); // User | undefined
if (!user) return null; // дальше user: User
return user.name;
}
function process(input: string | string[]) {
let items = input; // string | string[]
if (typeof items === "string") {
items = [items]; // после присваивания: string[]
}
return items.map((s) => s.trim()); // string[]
}Учитываются return, throw, break, continue, присваивания, логические операторы (user && user.name), ??, optional chaining и never-функции.
Когда сужение сбрасывается
type Box = { value: string | null };
function check(box: Box) {
if (box.value !== null) {
setTimeout(() => {
box.value.length; // в колбэке сужение не гарантировано — box.value мог измениться
});
doSomething(); // вызов функции тоже может изменить box.value, но TS доверяет сужению свойств
}
}- в колбэках и замыканиях сужение
let-переменных и свойств может не сохраняться; - сохраните значение в
const:const value = box.value; if (value) { ... }— дляconstсужение надежно; - с TS 5.4 сужение сохраняется в замыканиях после последнего присваивания.
Безопасность кода
- нет
as— компилятор проверяет, что вы действительно обработали варианты; - exhaustive check — после всех проверок остается
never, и добавление нового варианта подсветит места обработки; - нет лишних проверок — внутри ветки не нужно повторять проверку типа.
Что важно помнить
- Truthiness-проверка отсекает и
0, и""— для чисел и строк проверяйте!== undefinedили!= null. typeof null === "object"— проверкаtypeof x === "object"не исключаетnull.- Деструктуризация до проверки дискриминатора мешает сужению (кроме
const-деструктуризации в TS 4.6+). - Своя функция-проверка сужает тип, только если у нее предикат
x is T.
Мини-шпаргалка
- Narrowing — уточнение типа по проверкам.
- Способы:
typeof,===, truthiness,instanceof,in,Array.isArray, дискриминатор, type guard. - Control flow analysis учитывает
return,throw, присваивания. - В колбэках сужение
letи свойств может сбрасываться — используйтеconst. - Сужение заменяет небезопасный
as.
Документация
TypeScript Handbook: Narrowing, TypeScript Handbook: Control flow analysis.