Le type never en TypeScript : vérification exhaustive et void

never est le type sans aucune valeur. Une fonction dont le type de retour est never ne se termine jamais normalement : elle lève une exception ou tourne indéfiniment. Une variable de type never marque du code qui ne peut pas s'exécuter, et c'est ce qui rend possibles les vérifications exhaustives.

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(...) compile dans une fonction qui renvoie number, car never est assignable à tous les types : une valeur de type never ne peut jamais réellement arriver.

Les fonctions qui ne se terminent jamais

Deux sortes de fonctions n'atteignent jamais leur fin : celle qui lève toujours une exception, et celle qui contient une boucle infinie. Le compilateur vérifie l'affirmation. Une fonction annotée never dont la fin est atteignable provoque l'erreur 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...
  }
}

L'inférence dépend de la syntaxe. Une déclaration de fonction qui ne fait que lever une exception est inférée comme renvoyant void, alors qu'une fonction fléchée ou une expression de fonction qui ne fait que lever une exception est inférée comme never :

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

Le narrowing ne considère un appel comme une impasse que lorsque le nom appelé a un type explicite qui renvoie never : une déclaration de fonction annotée : never, comme fail plus haut, ou une variable avec une annotation de type, const fail: (m: string) => never = (m) => { throw new Error(m); }. Un never inféré ne compte pas, pas plus que const fail = (m: string): never => ..., où seule la fonction fléchée est annotée et pas la variable.

never ou void

La différence pratique se voit dans le narrowing. Après if (!user) fail("no user"), le compilateur sait que user est défini à la ligne suivante uniquement si fail renvoie never. Avec un retour void, il suppose que l'exécution peut continuer.

Vérifications exhaustives avec never

Chaque case d'un switch sur une union affine la valeur. Quand tous les membres ont été traités, ce qui reste dans default est never. L'assigner à une variable never transforme « j'ai traité tous les cas » en quelque chose que le compilateur vérifie :

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

Ajoutez maintenant un troisième membre à l'union sans ajouter de cas :

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

L'erreur nomme le membre oublié. Ajoutez case "triangle": return (shape.base * shape.height) / 2; et le code compile à nouveau. Le helper assertNever est la forme réutilisable de la même vérification, et son throw compte toujours à l'exécution : des données venues de JSON ou d'un client plus ancien peuvent contenir un kind que les types déclarent impossible. Ce motif est la colonne vertébrale des unions discriminées.

Affiner jusqu'à never

La même chose se produit avec n'importe quel narrowing, pas seulement switch. Une fois toutes les possibilités écartées, la variable a le type 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

Si vous élargissez plus tard le paramètre à string | number | boolean | bigint, la ligne const nothing: never = x devient une erreur et désigne la fonction à mettre à jour.

never disparaît dans les unions

never est l'ensemble vide de valeurs, l'ajouter à une union ne change donc rien : string | never est simplement string. C'est ainsi que les types conditionnels filtrent les unions. Une branche qui renvoie never retire ce membre :

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

Les types intégrés Exclude<T, U> et Extract<T, U> fonctionnent exactement ainsi. Dans une intersection, c'est l'inverse : string & never vaut never.

Les types impossibles deviennent never

Une intersection qu'aucune valeur ne peut satisfaire se réduit à never :

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

Lire une propriété d'une valeur B indique la raison : Property 'kind' does not exist on type 'never'. The intersection 'B' was reduced to 'never' because property 'kind' has conflicting types in some constituents. Quand un type que vous avez construit se révèle être never, cherchez deux parties qui se contredisent.

never, unknown et any

unknown est le sommet de la hiérarchie des types et never sa base. any ne fait pas du tout partie de la hiérarchie : il désactive les vérifications.