Сужение и анализ потока управления

Проверяющий отслеживает тип в каждой точке программы

У переменной-объединения нет одного типа на всю область видимости. Проверяющий обходит граф потока управления и в каждой точке держит самый узкий тип, всё ещё совместимый с проверками, через которые туда пришли. Проверка расщепляет поток: ветка true несёт одно сужение, ветка false — дополнение.

function format(x: string | number) {
  // x: string | number
  if (typeof x === "string") {
    x;
    // ^? (parameter) x: string
    return x.toUpperCase();
  }
  x;
  // ^? (parameter) x: number   — дополнение к строковой ветке
  return x.toFixed(2);
}

else (здесь — проход после return) получает number бесплатно: проверяющий вычитает string из объединения, ведь эта ветка уже обработана. Поэтому ранний return внутри проверки сужает остаток функции.

Пять повседневных операторов сужения

type Val = string | number | boolean | null | string[];

function inspect(v: Val) {
  if (typeof v === "number") v;        // ^? number  (проверка typeof)
  if (v === null) return;              // проверка равенства → ниже v без null
  if (Array.isArray(v)) v;             // ^? string[]  (встроенная проверка)
  if (v) v;                            // ^? string | number | boolean | string[] (истинность убирает null)
}

Повседневные инструменты, каждый сужает чуть по-своему:

• typeof — расщепляет по рантайм-тегам JS ("string", "number", "boolean", "object", "function", "undefined", "symbol", "bigint"). Учтите: typeof null === "object" — причуда JS, которую проверяющий уважает.
• Истинность — if (v) убирает из типа null, undefined, 0, "", false, NaN. Отлично для string | null, опасно для number | undefined (заодно отбрасывает 0).
• Равенство — ===/!== против литерала или null/undefined сужает обе ветки.
• in — if ("radius" in shape) сужает до членов объединения, объявляющих это свойство. Структурно, а не номинально.
• instanceof — сужает до класса (и подклассов) по цепочке прототипов в рантайме.

Сужение присваиванием и разница let/const

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

let s: string | number;
s = "hello";
s;
// ^? string   — присваивание сузило
s.toUpperCase();   // здесь OK

declare function rand(): string | number;
s = rand();
s;
// ^? string | number   — расширено обратно до объявленного типа

const отличается от let для вывода литерала, который питает сужение. Привязка const к литералу получает литеральный тип; привязка let расширяется до базового типа:

const dir = "up";
//    ^? "up"      — литеральный тип, годится как дискриминант
let dir2 = "up";
//    ^? string    — расширен, больше не дискриминант

Это колоссально важно для размеченных объединений (через урок): дискриминант, прочитанный в const, сохраняет литеральный тип; скопированный в let, он расширяется, и сужение молча перестаёт работать.

Исчерпывание через never

Когда вы сузили объединение, убрав каждый его член, оставшийся тип — never. Присваивание его переменной типа never превращает «я забыл случай» в ошибку компиляции:

function area(s: { kind: "circle"; r: number } | { kind: "square"; side: number }): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "square": return s.side ** 2;
    default: {
      const _exhaustive: never = s;
      // Если добавить новый вариант, s здесь уже не never →
      // Error: Type '{ kind: "triangle"; ... }' is not assignable to type 'never'.
      return _exhaustive;
    }
  }
}

Это сеньорский паттерн безопасного рефакторинга: добавляешь вариант — и каждый необработанный switch загорается красным. Далее вы его формализуете.

Сужение теряется через границы функций

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

function handle(id: string | number) {
  if (typeof id === "string") {
    id;
    // ^? string
    setTimeout(() => {
      id;
      // ^? string | number   — расширено обратно внутри замыкания!
      // id.toUpperCase();  // Error: Property 'toUpperCase' does not exist on type 'number'.
    });
  }
}

Замыкание может выполниться позже, когда id (в принципе) уже могли переприсвоить, поэтому проверяющий консервативно расширяет его до объявленного типа. То же происходит после await, ведь управление покинуло функцию и вернулось. Решения: скопировать суженное значение в const до границы (const sid = id;, пока id — string), или сделать захватываемую привязку const, чтобы проверяющий знал о невозможности переприсваивания.

function handle(id: string | number) {
  if (typeof id === "string") {
    const sid = id;        // const захватывает суженную строку
    setTimeout(() => sid.toUpperCase());  // OK — sid это string
  }
}