Tipo never em TypeScript: verificação exaustiva e never vs void

never é o tipo sem nenhum valor. Uma função cujo tipo de retorno é never nunca retorna normalmente: ela lança um erro ou roda para sempre. Uma variável do tipo never marca código que não pode rodar, e é isso que torna possíveis as verificações exaustivas.

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 em uma função que retorna number porque never pode ser atribuído a qualquer tipo: um valor do tipo never nunca chega de fato.

Funções que nunca retornam

Dois tipos de função nunca chegam ao fim: uma que sempre lança erro e uma com loop infinito. O compilador confere a afirmação. Uma função anotada como never cujo final pode ser alcançado gera o erro 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...
  }
}

A inferência muda conforme a sintaxe. Uma function declaration que só lança erro é inferida como retornando void, enquanto uma arrow function ou function expression que só lança erro é inferida como never:

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

O narrowing só trata uma chamada como beco sem saída quando o nome chamado tem um tipo explícito que retorna never: uma function declaration anotada com : never, como fail acima, ou uma variável com anotação de tipo, const fail: (m: string) => never = (m) => { throw new Error(m); }. Um never inferido não conta, nem const fail = (m: string): never => ..., em que só a arrow function é anotada e a variável não.

never vs void

A diferença prática aparece no narrowing. Depois de if (!user) fail("no user"), o compilador sabe que user está definido na linha seguinte só se fail retornar never. Com retorno void, ele assume que a execução pode continuar.

Verificações exaustivas com never

Cada case de um switch sobre uma union estreita o valor. Quando todos os membros foram tratados, o que sobra no default é never. Atribuí-lo a uma variável never transforma "tratei todos os casos" em algo que o compilador 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

Agora adicione um terceiro membro à union sem adicionar um 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'.

O erro indica o membro que você esqueceu. Adicione case "triangle": return (shape.base * shape.height) / 2; e ele volta a compilar. O helper assertNever é a forma reutilizável da mesma verificação, e o throw dele continua importando em tempo de execução: dados vindos de JSON ou de um cliente antigo podem conter um kind que os tipos dizem ser impossível. Esse padrão é a base das discriminated unions.

Narrowing até never

O mesmo acontece com qualquer narrowing, não só com switch. Depois que todas as possibilidades são descartadas, a variável tem o 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 mais tarde você ampliar o parâmetro para string | number | boolean | bigint, a linha const nothing: never = x vira um erro, apontando para a função que precisa ser atualizada.

never desaparece em unions

never é o conjunto vazio de valores, então adicioná-lo a uma union não muda nada: string | never é só string. É assim que os conditional types filtram unions. Um ramo que retorna never remove aquele 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);

Os tipos nativos Exclude<T, U> e Extract<T, U> funcionam exatamente assim. Em uma intersection é o contrário: string & never é never.

Tipos impossíveis viram never

Uma intersection que nenhum valor consegue satisfazer se reduz a never:

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

Ler uma propriedade de um valor B mostra o 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 um tipo que você montou acaba sendo never, procure duas partes que se contradizem.

never, unknown e any

unknown é o topo da hierarquia de tipos e never é a base. O any nem faz parte da hierarquia: ele desliga as verificações.