Narrowing no TypeScript: unions, unknown e any

O que é

Um tipo union como string | number indica que um valor é de um entre vários tipos. Narrowing (estreitamento de tipos) é a análise de fluxo de controle do compilador: depois de uma verificação, o tipo dentro daquele ramo é reduzido. O handbook lista as verificações que o compilador entende: typeof x === "string", truthiness, igualdade com um literal, "kind" in x, x instanceof Date, atribuições e type predicates definidos pelo usuário (function isFish(p: Pet): p is Fish). Uma união discriminada dá a cada membro uma propriedade literal (kind: "circle" | "square"); um switch sobre ela estreita o tipo para um único membro e, quando todos os casos são tratados, o tipo restante é never, que é como funcionam as verificações de exaustividade. any desliga a verificação para aquele valor e para tudo o que deriva dele. unknown também aceita qualquer valor, mas "não é permitido fazer nada com um valor unknown" até que ele tenha sido estreitado.

Por que importa

any se espalha silenciosamente: um único tipo de retorno any deixa sem verificação todas as expressões seguintes, sem nenhum aviso. unknown nas fronteiras (JSON já interpretado, payloads de mensagens, erros capturados) força a verificação a acontecer no ponto em que os dados entram. Uniões discriminadas transformam o "esqueci de tratar a nova variante" em um erro de compilação, em vez de uma surpresa em tempo de execução.

Como aplicar

• Ative strict, que inclui noImplicitAny; trate cada any explícito restante como uma exceção documentada, com um comentário explicando o motivo.
• Declare os dados de fronteira com o tipo unknown e estreite-os com um validador ou verificações explícitas; encapsule JSON.parse, que retorna any, em uma função que retorne unknown.
• Modele estados como uma união discriminada ({ status: "loading" } | { status: "ok"; data: T } | { status: "error"; error: Error }) em vez de campos opcionais que podem se contradizer.
• Termine todo switch sobre uma união com um ramo default que atribua o valor a uma variável do tipo never; assim, ao adicionar uma variante, a compilação falha em cada switch que não a trata.
• Escreva um type predicate apenas quando a verificação em tempo de execução garantir o tipo; um predicate errado é um any disfarçado.
• Em catch (e), trate e como unknown e verifique e instanceof Error antes de ler .message.

Armadilhas

O narrowing não se mantém dentro de callbacks nem entre chamadas de função: if (x.a) list.forEach(() => x.a.b) não compila, porque o callback pode ser executado depois, quando x.a já mudou. O narrowing de uma propriedade é reiniciado por uma atribuição a ela, mas não por uma chamada de função que possa modificar o objeto: o compilador assume que o objeto não mudou, um trade-off deliberado na sua análise de fluxo de controle. Uma type assertion (as Foo) não é narrowing; ela se sobrepõe ao verificador e deveria ser tão rara quanto any.