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

Сужение типов это когда TypeScript определяет более конкретный тип значения в определённой точке кода на основе проверок, которые код уже сделал. Параметр string | number становится string внутри if (typeof x === "string") и number в else.

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

Вызов value.toFixed(2) до проверки был бы ошибкой компиляции, потому что у string нет toFixed. Проверка это обычный JavaScript, который выполняется во время работы программы; сужение это компилятор, который её читает и подстраивает тип. Ничего лишнего не генерируется.

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

TypeScript проходит по каждому пути через функцию: if/else, ранние return и throw, switch, циклы и операторы с коротким замыканием &&, ||, ?? и ?:. В каждой точке тип переменной это то, что там ещё возможно.

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

Стиль с ранним возвратом («guard clauses») самый читаемый способ сужать: сначала обработайте особые случаи, и остальная функция работает с чистым типом.

Все способы сужения

Последние три разобраны на страницах о защитниках типов и размеченных объединениях. Остальные ниже.

Сужение по истинности

if (x) убирает null и undefined (а также литеральные типы false, 0, ""). Это коротко, но есть классическая ловушка: 0 и "" ложны, поэтому корректные значения принимаются за отсутствующие.

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

Для чисел и строк сравнивайте с undefined или null явно (или используйте ??). Для объектов, массивов и функций, которые никогда не бывают ложными, проверка истинности подходит.

Сужение через равенство

===, !==, == и != сужают обе стороны. Сравнение с литералом сужает до этого литерала; == null (нестрогое равенство) одной проверкой совпадает и с null, и с undefined, и это единственное место, где нестрогое равенство считается идиоматичным.

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

Сравнение двух переменных сужает обе до того, что у них может быть общего: если a: string | number и b: string | boolean проходят a === b, внутри if обе имеют тип string.

Оператор in

"key" in obj сужает объединение объектных типов до членов, у которых это свойство есть (или может быть).

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

in работает и с unknown, когда известно, что это объект: после typeof v === "object" && v !== null && "id" in v TypeScript знает, что у v есть свойство id типа unknown. Для объединений, которые вы проектируете сами, общее свойство-метка (kind: "fish") понятнее, чем проверка наличия методов; такой приём называется размеченным объединением.

Сужение при присваивании

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

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

Где сужение теряется

Сужение локально и консервативно. Несколько ситуаций его сбрасывают:

• Другое выражение. Проверка obj.name сужает obj.name (и obj["name"]), но не obj[key], когда key это переменная типа string, а не литерал, и не копию, сделанную до проверки.
• Колбэки и переприсваивание. Внутри колбэка суженная let сохраняет сужение, только если ей ничего не присваивается после создания колбэка. const или параметр, который никогда не переприсваивается, остаются суженными.
• Проверки, спрятанные во вспомогательных функциях. Функция isString(x: unknown): boolean ничего не сообщает компилятору. Дайте ей возвращаемый тип-предикат, x is string, и её вызовы будут сужать так же, как typeof.

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

Компилятор сообщает index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. Колбэк может выполниться позже, после x = undefined. Удалите это последнее присваивание (или скопируйте значение в const внутри if), и код скомпилируется и дважды напечатает 5.

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

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

Начиная с TypeScript 5.5 компилятор выводит такие предикаты для простых стрелочных функций, поэтому list.filter((x) => x !== undefined) теперь возвращает массив без undefined.