Typ never w TypeScript: exhaustive check i never a void

never to typ bez żadnych wartości. Funkcja, której typem zwracanym jest never, nigdy nie kończy się normalnie: rzuca wyjątek albo działa w nieskończoność. Zmienna typu never oznacza kod, który nie może się wykonać, i to właśnie umożliwia wyczerpujące sprawdzanie przypadków.

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(...) kompiluje się w funkcji zwracającej number, bo never jest przypisywalny do każdego typu: wartość typu never nigdy tak naprawdę nie nadejdzie.

Funkcje, które nigdy nie zwracają

Są dwa rodzaje funkcji, które nigdy nie docierają do końca: taka, która zawsze rzuca wyjątek, i taka z nieskończoną pętlą. Kompilator sprawdza tę deklarację. Funkcja z adnotacją never, której koniec jest osiągalny, to błąd 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...
  }
}

Wnioskowanie zależy od składni. Deklaracja funkcji, która tylko rzuca wyjątek, jest wnioskowana jako zwracająca void, a funkcja strzałkowa lub wyrażenie funkcyjne, które tylko rzuca, są wnioskowane jako never:

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

Zawężanie traktuje wywołanie jako ślepy zaułek tylko wtedy, gdy wywoływana nazwa ma jawny typ zwracający never: deklarację funkcji z adnotacją : never, jak fail wyżej, albo zmienną z adnotacją typu, const fail: (m: string) => never = (m) => { throw new Error(m); }. Wywnioskowany never się nie liczy, podobnie jak const fail = (m: string): never => ..., gdzie adnotację ma tylko funkcja strzałkowa, a zmienna nie.

never a void

Praktyczną różnicę widać przy zawężaniu. Po if (!user) fail("no user") kompilator wie, że user jest zdefiniowany w następnej linii, tylko jeśli fail zwraca never. Przy typie zwracanym void zakłada, że wykonanie może być kontynuowane.

Exhaustive check z never

Każdy case instrukcji switch po unii zawęża wartość. Gdy każdy element zostanie obsłużony, w default zostaje never. Przypisanie tej wartości do zmiennej never zamienia "każdy przypadek jest obsłużony" w coś, co weryfikuje kompilator:

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

Teraz dodaj trzeci element do unii bez dodawania przypadku:

// 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'.

Błąd wskazuje zapomniany element. Dodaj case "triangle": return (shape.base * shape.height) / 2;, a kod znów się skompiluje. Funkcja pomocnicza assertNever to wielokrotnego użytku wersja tego samego sprawdzenia, a jej throw nadal ma znaczenie w czasie działania: dane z JSON albo ze starszego klienta mogą zawierać kind, który według typów jest niemożliwy. Ten wzorzec to podstawa discriminated unions.

Zawężanie aż do never

To samo dzieje się przy każdym zawężaniu, nie tylko w switch. Gdy każda możliwość zostanie wykluczona, zmienna ma typ 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

Jeśli później rozszerzysz parametr do string | number | boolean | bigint, linia const nothing: never = x stanie się błędem i wskaże funkcję, którą trzeba zaktualizować.

never znika w uniach

never to pusty zbiór wartości, więc dodanie go do unii niczego nie zmienia: string | never to po prostu string. W ten sposób conditional types filtrują unie. Gałąź zwracająca never usuwa dany element:

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);

Wbudowane Exclude<T, U> i Extract<T, U> działają dokładnie tak. W przecięciu jest odwrotnie: string & never to never.

Niemożliwe typy stają się never

Przecięcie, którego nie może spełnić żadna wartość, redukuje się do never:

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

Odczyt właściwości wartości typu B zgłasza przyczynę: Property 'kind' does not exist on type 'never'. The intersection 'B' was reduced to 'never' because property 'kind' has conflicting types in some constituents. Gdy zbudowany typ okazuje się never, szukaj dwóch części, które sobie przeczą.

never, unknown i any

unknown to szczyt hierarchii typów, a never jej dno. any w ogóle nie należy do hierarchii: wyłącza sprawdzanie.