Функции-утверждения

Две формы сигнатуры, обе через asserts

Прежде чем тянуться к if (!x) throw или рассыпать ! по файлу, спросите себя: ложный случай — это баг или законный вариант? Если это баг, функция-утверждение выражает именно это намерение — а компилятор закрепляет его на весь остаток области.

В TypeScript 3.7 появились сигнатуры-утверждения: возвращающая void функция, чей тип возврата — asserts …. Есть две формы.

// Форма 1 — утверждает, что условие истинно
function assert(condition: unknown, msg?: string): asserts condition {
  if (!condition) throw new Error(msg ?? "Assertion failed");
}

// Форма 2 — утверждает, что значение имеет конкретный тип
function assertIsString(x: unknown): asserts x is string {
  if (typeof x !== "string") throw new TypeError("not a string");
}

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

function load(raw: unknown) {
  assertIsString(raw);
  raw;
  // ^? string   — сужён на остаток области, ветка не нужна
  return raw.toUpperCase();
}

Предикат против утверждения: сужение ветки против сужения области

В этом и состоит senior-различие. Type-предикат (x is T) возвращает boolean и сужает только внутри ветки, где boolean истинен. Функция-утверждение (asserts x is T) возвращает void и сужает остаток области после вызова, потому что ложный случай уже выбросил исключение.

// Предикат: сужает только внутри ветки if
function isStr(x: unknown): x is string {
  return typeof x === "string";
}
function a(x: unknown) {
  if (isStr(x)) {
    x; // ^? string  (только здесь)
  }
  x;   // ^? unknown (вне ветки снова широкий)
}

// Утверждение: сужает всё после вызова
function b(x: unknown) {
  assertIsString(x);
  x; // ^? string  (на весь оставшийся scope)
}

Берите предикат, когда хотите обработать оба случая; берите утверждение, когда ложный случай — это баг, на котором надо упасть громко.

Аннотация обязательна — и не проверяется

Сигнатура-утверждение никогда не выводится. Если опустить явный тип возврата : asserts …, TypeScript типизирует функцию как возвращающую void, и вызов ничего не сужает — молча.

// Аннотация asserts отсутствует:
function assertNum(x: unknown) {     // выведенный возврат: void
  if (typeof x !== "number") throw new Error();
}
function c(x: unknown) {
  assertNum(x);
  x; // ^? unknown   — НЕ сужён; эффект assert молча потерян
}

Тут нет ошибки — лишь отсутствующее сужение, а это опасный вид бага. Хуже того, тело не проверяется против утверждения. TypeScript доверяет сигнатуре; он не проверяет, что функция действительно выбрасывает, когда утверждение ложно.

function brokenAssert(x: unknown): asserts x is string {
  // забыли выбросить! ничего не делает
}
function d(x: unknown) {
  brokenAssert(x);
  x.toUpperCase(); // для компилятора x — `string`, но в рантайме чем угодно → краш
}

В этом центральная ненадёжность: функция-утверждение — это несущее заявление, которое тайп-чекер принимает на веру. Тело должно действительно выбрасывать в ложном случае, иначе вы солгали компилятору. Держите функции-утверждения крошечными и очевидно-выбрасывающими, а генерацию доверяйте библиотекам валидации (Zod и др.), чтобы выброс не разъезжался с типом.

Утверждения и определённое присваивание

Функции-утверждения также взаимодействуют с анализом определённого присваивания. Частый паттерн — утверждать, что значение присвоено до использования, что позволяет компилятору считать let определённо-присвоенным после — но заметьте, это работает только через механизм asserts, а не через обычный поток управления, так что та же дисциплина «должна действительно выбросить» сохраняется. При надёжном использовании assertDefined(config) заменяет лес non-null-утверждений ! одной проверяемой точкой-перехватом.