Тип never в TypeScript: исчерпывающие проверки и void

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

function fail(message: string): never {
  throw new Error(message);
}

function parsePort(text: string): number {
  const n = Number(text);
  if (Number.isInteger(n) && n > 0 && n < 65536) return n;
  return fail(`invalid port: ${text}`); // never is assignable to number
}

console.log(parsePort("8080")); // 8080

try {
  parsePort("http");
} catch (e) {
  console.log((e as Error).message); // invalid port: http
}

return fail(...) компилируется в функции, которая возвращает number, потому что never присваивается любому типу: значение типа never на самом деле никогда не появится.

Функции, которые никогда не возвращают управление

Два вида функций никогда не доходят до конца: та, что всегда выбрасывает ошибку, и та, что содержит бесконечный цикл. Компилятор проверяет это утверждение. Функция с аннотацией never, конец которой достижим, это ошибка TS2534, A function returning 'never' cannot have a reachable end point.

function fail(message: string): never {
  throw new Error(message);
}

function runForever(): never {
  while (true) {
    // poll, serve requests...
  }
}

Вывод типа зависит от синтаксиса. Для объявления функции, которое только выбрасывает ошибку, выводится возврат void, а для стрелочной функции или функционального выражения, которые только выбрасывают ошибку, выводится never:

function f1() { throw new Error("x"); }       // () => void
const f2 = () => { throw new Error("x"); };   // () => never

Сужение считает вызов тупиком, только если у вызываемого имени есть явный тип, возвращающий never: объявление функции с аннотацией : never, как fail выше, или переменная с аннотацией типа, const fail: (m: string) => never = (m) => { throw new Error(m); }. Выведенный never не считается, как и const fail = (m: string): never => ..., где аннотирована только стрелочная функция, а не переменная.

never и void

Практическая разница видна при сужении. После if (!user) fail("no user") компилятор знает, что user определён на следующей строке, только если fail возвращает never. С возвратом void он предполагает, что выполнение может продолжиться.

Исчерпывающие проверки через never

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

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.side ** 2;
    default: {
      const unhandled: never = shape; // shape is never here
      throw new Error(`unknown shape: ${JSON.stringify(unhandled)}`);
    }
  }
}

console.log(area({ kind: "square", side: 3 })); // 9
console.log(area({ kind: "circle", radius: 1 }).toFixed(4)); // 3.1416

Теперь добавьте в объединение третий член, не добавляя case:

// This does not compile: "triangle" is not handled
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "triangle"; base: number; height: number };

function assertNever(value: never): never {
  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.side ** 2;
    default:
      return assertNever(shape);
  }
}

console.log(area({ kind: "square", side: 3 }));

index.ts(18,26): error TS2345: Argument of type '{ kind: "triangle"; base: number; height: number; }' is not assignable to parameter of type 'never'.

Ошибка называет член, который вы забыли. Добавьте case "triangle": return (shape.base * shape.height) / 2;, и код снова компилируется. Вспомогательная функция assertNever это многоразовая форма той же проверки, и её throw важен и во время выполнения: данные из JSON или от старого клиента могут содержать kind, который по типам невозможен. Этот приём лежит в основе размеченных объединений.

Сужение до never

То же самое происходит при любом сужении, а не только в switch. Когда все варианты исключены, переменная получает тип never:

function describe(x: string | number | boolean): string {
  if (typeof x === "string") return `string "${x}"`;
  if (typeof x === "number") return `number ${x}`;
  if (typeof x === "boolean") return `boolean ${x}`;
  const nothing: never = x; // every option handled
  return nothing;
}

console.log(describe("a")); // string "a"
console.log(describe(2));   // number 2
console.log(describe(true)); // boolean true

Если позже расширить параметр до string | number | boolean | bigint, строка const nothing: never = x станет ошибкой и укажет на функцию, которую нужно обновить.

never исчезает в объединениях

never это пустое множество значений, поэтому его добавление в объединение ничего не меняет: string | never это просто string. Так условные типы фильтруют объединения. Ветка, которая возвращает never, удаляет этот член:

type OnlyStrings<T> = T extends string ? T : never;

type Mixed = "a" | "b" | 1 | 2 | true;
type Letters = OnlyStrings<Mixed>; // "a" | "b"

const ok: Letters = "a";
// @ts-expect-error: Type '1' is not assignable to type 'Letters'.
const bad: Letters = 1;

console.log(ok);

Встроенные Exclude<T, U> и Extract<T, U> работают именно так. В пересечении наоборот: string & never это never.

Невозможные типы становятся never

Пересечение, которому не может соответствовать ни одно значение, сводится к never:

type A = string & number;                   // never
type B = { kind: "a" } & { kind: "b" };     // never

Чтение свойства значения типа B сообщает причину: Property 'kind' does not exist on type 'never'. The intersection 'B' was reduced to 'never' because property 'kind' has conflicting types in some constituents. Если построенный вами тип оказался never, ищите две части, которые противоречат друг другу.

never, unknown и any

unknown это вершина иерархии типов, а never её дно. any вообще не входит в иерархию: он отключает проверки.