Частые ловушки: то, что компилируется чисто и кусает позже

Сводная таблица

Каждая строка — ловушка, проходящая компилятор. Читайте как: симптом, почему проскакивает и рефлекторный фикс.

Брендинг: намеренная победа над структурной типизацией

Раздел 01 учил, что TypeScript структурен — два типа одной формы взаимозаменяемы. Обычно это фича; здесь — опасность. type UserId = string и type OrderId = string — это один и тот же тип, так что передача одного туда, где ждут другой, компилируется. Брендинг добавляет фантомное свойство, существующее только в типе:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function getUser(id: UserId) { /* ... */ }
const order = "ord_1" as OrderId;

// getUser(order); // Error: 'OrderId' is not assignable to 'UserId'
//   __brand различает их, хотя оба — string в рантайме
const user = "usr_1" as UserId;
getUser(user); // ok

__brand никогда не существует в рантайме (под ним string), но тип теперь различает два, так что перепутанный ID — ошибка компиляции. Это стандартный фикс для «структурная типизация пропустила не тот примитив».

Ковариантность массивов: каноническая несостоятельность

TypeScript намеренно делает массивы ковариантными — Dog[] присваивается Animal[] — ради эргономики. Но массивы изменяемы, что делает это несостоятельным:

const dogs: Dog[] = [new Dog()];
const animals: Animal[] = dogs; // разрешено — ковариантность
animals.push(new Cat());        // компилируется! Animal[] принимает Cat
dogs[1].bark();                 // падение в рантайме — это Cat, нет bark()

Компилятор принял каждую строку, а dogs теперь содержит Cat. Фикс в дизайне API: принимайте readonly Animal[], когда только читаете, чтобы вызывающий не мог протащить Cat в чужой Dog[].

Мутация ломает сужение

Сужение (раздел 02) валидно лишь пока значение не может измениться. Изменяемая привязка или свойство, суженные в if, могут быть сброшены любым промежуточным вызовом, сквозь который компилятор не видит:

function f(box: { v: string | null }) {
  if (box.v !== null) {
    sideEffect();        // мог сделать box.v = null — компилятор считает, что нет
    box.v.toUpperCase(); // ^? string  — но может упасть в рантайме
  }
}

Компилятор сужает box.v до string внутри if и сохраняет это допущение сквозь sideEffect(), потому что не может доказать, что вызов не тронул box.v. Фикс: скопируйте в const-локальную сразу после проверки (const v = box.v;), чтобы суженное значение не вымутировали из-под вас.