Il tipo never in TypeScript: controlli esaustivi e never vs void

never è il tipo senza valori. Una funzione il cui tipo di ritorno è never non ritorna mai normalmente: lancia un errore o gira per sempre. Una variabile di tipo never indica codice che non può essere eseguito, ed è questo che rende possibili i controlli esaustivi.

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(...) compila in una funzione che restituisce number perché never è assegnabile a ogni tipo: un valore di tipo never non può mai arrivare davvero.

Funzioni che non ritornano mai

Due tipi di funzione non arrivano mai alla fine: quella che lancia sempre un errore e quella con un ciclo infinito. Il compilatore verifica l'affermazione. Una funzione annotata never la cui fine è raggiungibile dà l'errore 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'inferenza dipende dalla sintassi. Una dichiarazione di funzione che si limita a lanciare un errore viene inferita come se restituisse void, mentre una arrow function o un'espressione di funzione che si limita a lanciare viene inferita come never:

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

Il narrowing tratta una chiamata come un vicolo cieco solo quando il nome chiamato ha un tipo esplicito che restituisce never: una dichiarazione di funzione annotata : never, come fail qui sopra, oppure una variabile con un'annotazione di tipo, const fail: (m: string) => never = (m) => { throw new Error(m); }. Un never inferito non conta, e nemmeno const fail = (m: string): never => ..., dove è annotata solo la arrow function e non la variabile.

never vs void

La differenza pratica si vede nel narrowing. Dopo if (!user) fail("no user"), il compilatore sa che user è definito nella riga successiva solo se fail restituisce never. Con un ritorno void presume che l'esecuzione possa continuare.

Controlli esaustivi con never

Ogni case di uno switch su un'unione restringe il valore. Quando ogni membro è stato gestito, ciò che resta in default è never. Assegnarlo a una variabile never trasforma "ho gestito ogni caso" in qualcosa che il compilatore verifica:

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

Ora aggiungi un terzo membro all'unione senza aggiungere un caso:

// 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'errore nomina il membro che hai dimenticato. Aggiungi case "triangle": return (shape.base * shape.height) / 2; e compila di nuovo. L'helper assertNever è la forma riutilizzabile dello stesso controllo, e il suo throw conta ancora a runtime: i dati da JSON o da un client più vecchio possono contenere un kind che secondo i tipi è impossibile. Questo schema è la spina dorsale delle discriminated unions.

Narrowing fino a never

La stessa cosa succede con qualsiasi narrowing, non solo con switch. Una volta esclusa ogni possibilità, la variabile ha tipo 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

Se in seguito allarghi il parametro a string | number | boolean | bigint, la riga const nothing: never = x diventa un errore, che indica la funzione da aggiornare.

never sparisce nelle unioni

never è l'insieme vuoto di valori, quindi aggiungerlo a un'unione non cambia nulla: string | never è semplicemente string. È così che i conditional types filtrano le unioni. Un ramo che restituisce never rimuove quel membro:

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

I tipi integrati Exclude<T, U> ed Extract<T, U> funzionano esattamente così. In un'intersezione è il contrario: string & never è never.

I tipi impossibili diventano never

Un'intersezione che nessun valore può soddisfare si riduce a never:

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

Leggere una proprietà di un valore B riporta il motivo: Property 'kind' does not exist on type 'never'. The intersection 'B' was reduced to 'never' because property 'kind' has conflicting types in some constituents. Quando un tipo che hai costruito risulta never, cerca due parti che si contraddicono.

never, unknown e any

unknown è la cima della gerarchia dei tipi e never è il fondo. any non fa affatto parte della gerarchia: disattiva i controlli.