TypeScript never: Vollständigkeitsprüfung und never vs void

never ist der Typ ohne Werte. Eine Funktion mit dem Rückgabetyp never kehrt nie normal zurück: Sie wirft oder läuft endlos. Eine Variable vom Typ never markiert Code, der nicht laufen kann, und genau das macht Vollständigkeitsprüfungen möglich.

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(...) kompiliert in einer Funktion, die number zurückgibt, weil never jedem Typ zuweisbar ist: Ein Wert vom Typ never kann nie tatsächlich ankommen.

Funktionen, die nie zurückkehren

Zwei Arten von Funktionen erreichen nie ihr Ende: eine, die immer wirft, und eine mit Endlosschleife. Der Compiler prüft die Behauptung. Eine als never annotierte Funktion, deren Ende erreichbar ist, ist der Fehler 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...
  }
}

Die Inferenz hängt von der Syntax ab. Eine Funktionsdeklaration, die nur wirft, wird mit Rückgabe void abgeleitet, während eine Arrow Function oder ein Funktionsausdruck, der nur wirft, als never abgeleitet wird:

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

Das Narrowing behandelt einen Aufruf nur dann als Sackgasse, wenn der aufgerufene Name einen ausdrücklichen Typ hat, der never zurückgibt: eine Funktionsdeklaration mit Annotation : never, wie fail oben, oder eine Variable mit Typannotation, const fail: (m: string) => never = (m) => { throw new Error(m); }. Ein abgeleitetes never zählt nicht, und ebenso wenig const fail = (m: string): never => ..., wo nur die Arrow Function annotiert ist, die Variable aber nicht.

never vs void

Der praktische Unterschied zeigt sich beim Narrowing. Nach if (!user) fail("no user") weiß der Compiler nur dann, dass user in der nächsten Zeile definiert ist, wenn fail never zurückgibt. Bei einer Rückgabe void nimmt er an, dass die Ausführung weitergehen kann.

Vollständigkeitsprüfung mit never

Jeder case eines switch über eine Union engt den Wert ein. Ist jeder Member behandelt, bleibt im default never übrig. Ihn einer never-Variablen zuzuweisen macht aus „ich habe jeden Fall behandelt“ etwas, das der Compiler prüft:

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

Füge der Union nun einen dritten Member hinzu, ohne einen case zu ergänzen:

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

Der Fehler nennt den vergessenen Member. Ergänze case "triangle": return (shape.base * shape.height) / 2;, dann kompiliert es wieder. Die Hilfsfunktion assertNever ist die wiederverwendbare Form derselben Prüfung, und ihr throw zählt zur Laufzeit weiterhin: Daten aus JSON oder von einem älteren Client können eine kind enthalten, die laut Typen unmöglich ist. Dieses Muster ist das Rückgrat von Discriminated Unions.

Bis zu never einengen

Dasselbe passiert bei jedem Narrowing, nicht nur bei switch. Sobald jede Möglichkeit ausgeschlossen ist, hat die Variable den 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

Erweiterst du den Parameter später auf string | number | boolean | bigint, wird die Zeile const nothing: never = x zum Fehler und zeigt auf die Funktion, die angepasst werden muss.

never verschwindet in Unions

never ist die leere Menge von Werten, es einer Union hinzuzufügen ändert also nichts: string | never ist einfach string. So filtern Conditional Types Unions. Ein Zweig, der never zurückgibt, entfernt diesen Member:

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

Die eingebauten Exclude<T, U> und Extract<T, U> funktionieren genau so. In einer Intersection ist es umgekehrt: string & never ist never.

Unmögliche Typen werden zu never

Eine Intersection, die kein Wert erfüllen kann, wird auf never reduziert:

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

Das Lesen einer Eigenschaft eines B-Werts meldet den Grund: Property 'kind' does not exist on type 'never'. The intersection 'B' was reduced to 'never' because property 'kind' has conflicting types in some constituents. Wenn ein Typ, den du gebaut hast, sich als never herausstellt, suche nach zwei Teilen, die sich widersprechen.

never, unknown und any

unknown ist die Spitze der Typhierarchie und never ihr Boden. any gehört gar nicht zur Hierarchie: Es schaltet die Prüfungen ab.