Typescript: Refinamento de Tipos (Type Guards / Narrowing)

Introdução

• Type guards → provam o tipo explicitamente
• Narrowing → é o processo mais amplo, que inclui type guards e outras formas de afunilar

Narrowing
├── Type Guards
│   ├── typeof
│   ├── instanceof
│   ├── in
│
├── Equality Narrowing
│   ├── === / !==
│   └── == / != (loose, menos comum)
│
└── Truthiness Narrowing
    ├── if (x)
    ├── x && ...
    └── !!x

Type Guards

Um type guard é qualquer expressão que, quando avaliada como true, garante ao TypeScript qual é o tipo dentro daquele bloco.

O problema que eles resolvem

type Resultado = { dados: string[] } | { mensagem: string };

function tratar(r: Resultado) {
  console.log(r.dados); // ❌ erro — TypeScript não sabe qual dos dois é
}

Você precisa provar ao compilador qual tipo está lidando. Type guards fazem isso.

Typeof

O typeof é um operador do próprio JavaScript, o TypeScript apenas o observa e usa o resultado para afunilar o tipo.

O typeof funciona para estruturas primitivas como: string, number, boolean, undefined, symbol, bigint

O que acontece no exemplo passo a passo

function formatar(valor: string | number) {
  // aqui: valor é  string | number

  if (typeof valor === "string") {
    // aqui: TypeScript SABE que é string
    // métodos de string disponíveis ✅
    return valor.toUpperCase();
  }

  // aqui: TypeScript ELIMINOU string da union
  // só sobrou number ✅
  return valor.toFixed(2);
}

Esse "sobrar" é o narrowing acontecendo. O TypeScript rastreia o fluxo e descarta o que foi provado impossível. Por isso o nome traduzido é “estreitamento”, os tipos das variáveis vão se estreitando a medida que o typescript vai elimitando os tipos.

O typeof não distingue objetos entre si:

type NFe  = { chaveAcesso: string };
type NFSe = { codigoVerificacao: string };

function processar(nota: NFe | NFSe) {
  if (typeof nota === "object") {
    // TS ainda não sabe se é NFe ou NFSe ❌
    // typeof não ajuda aqui
  }
}

Para objetos você precisa do in, instanceof, ou um user-defined guard — que são os outros type guards que veremos em seguida.

Instanceof

O instanceof verifica se um objeto foi criado por uma determinada classe — tecnicamente, se o prototype da classe aparece na cadeia de prototypes do objeto.

Sintaxe básica:

objeto instanceof Classe

Retorna true ou false, e o TypeScript usa isso para afunilar o tipo.

Exemplo simples

class ErroDeRede extends Error {
  statusCode: number;
  constructor(msg: string, code: number) {
    super(msg);
    this.statusCode = code;
  }
}

class ErroDeValidacao extends Error {
  campo: string;
  constructor(msg: string, campo: string) {
    super(msg);
    this.campo = campo;
  }
}

function tratar(err: Error) {
  if (err instanceof ErroDeRede) {
    console.log(err.statusCode); // ✅ TypeScript sabe que é ErroDeRede
  }

  if (err instanceof ErroDeValidacao) {
    console.log(err.campo); // ✅ TypeScript sabe que é ErroDeValidacao
  }
}

Passo a passo do Narrowing

function tratar(err: ErroDeRede | ErroDeValidacao) {
  // aqui: err é ErroDeRede | ErroDeValidacao

  if (err instanceof ErroDeRede) {
    // aqui: err é ErroDeRede ✅
    return;
  }

  // aqui: TypeScript eliminou ErroDeRede
  // só sobrou ErroDeValidacao ✅
  console.log(err.campo);
}

Só funciona com classes — não funciona com type ou interface:

type NFe = { chaveAcesso: string };

const nota = { chaveAcesso: "123" };

nota instanceof NFe // ❌ erro de compilação — NFe não é uma classe

Para objetos simples tipados com type ou interface, você usa in ou um user-defined guard com is.

IN

O in verifica se uma propriedade existe em um objeto. É o tipo guard ideal para distinguir entre tipos que são objetos literais (type ou interface), onde instanceof não funciona.

Sintaxe básica

"propriedade" in objeto

Retorna true se a propriedade existe no objeto ou em seu prototype.

Exemplo simples

type Sucesso = { dados: string[] };
type Erro    = { mensagem: string };

function tratar(r: Sucesso | Erro) {
  if ("dados" in r) {
    console.log(r.dados); // ✅ TypeScript sabe que é Sucesso
  } else {
    console.log(r.mensagem); // ✅ TypeScript sabe que é Erro
  }
}

Passo a passo do narrowing

function tratar(r: Sucesso | Erro) {
  // aqui: r é Sucesso | Erro

  if ("dados" in r) {
    // aqui: r é Sucesso ✅
    return;
  }

  // aqui: TypeScript eliminou Sucesso
  // só sobrou Erro ✅
  console.log(r.mensagem);
}

Narrowing

Narrowing é o processo pelo qual o TypeScript reduz um tipo amplo para um mais específico conforme analisa o fluxo do código. Ele não é uma feature isolada — é um comportamento contínuo do compilador.

Alguns desenvolvedores confudem O Type Guard com o Narrow. Podemos dizer que o Type Guard é uma ferramenta que dispara o narrowing

function processar(valor: string | number) {
  // aqui: string | number

  if (typeof valor === "string") {
    // aqui: string
  }

  // aqui: number
}

O TypeScript rastreia o que é possível em cada ponto do código e descarta o que foi provado impossível.

Todas as formas de narrowing juntas

Narrowing
├── typeof          → primitivos
├── instanceof      → classes
├── in              → objetos literais
├── User-defined    → lógica customizada (is)
├── Equality        → === / !== / == null
├── Truthiness      → if (x) / !!x
└── Exhaustiveness  → assertNever

, isCada uma é só uma ferramenta diferente para provar ao compilador qual tipo está presente.

O compilador acumula evidências

O narrowing é cumulativo, cada verificação elimina possibilidades:

function processar(valor: string | number | null | undefined) {
  if (valor == null) return;
  // eliminou null e undefined → string | number

  if (typeof valor === "string") return;
  // eliminou string → number

  // aqui: só number ✅
  console.log(valor.toFixed(2));
}

Equality

O TypeScript observa comparações de igualdade e usa o resultado para afunilar o tipo. Existem dois operadores: o estrito (=== / !==) e o loose (== / !=).

=== estrito

Compara valor e tipo — o mais comum:

function processar(x: string | number) {
  if (x === "pendente") {
    // ✅ x é string — e especificamente "pendente"
    return x.toUpperCase();
  }
  // aqui: number
}

!== para exclusão

function processar(valor: string | null) {
  if (valor !== null) {
    // ✅ null foi eliminado — só string
    console.log(valor.toUpperCase());
  }
}

== loose — o único caso útil

Normalmente evitamos == em TypeScript, mas há um caso onde ele é genuinamente melhor: eliminar null e undefined ao mesmo tempo.

function processar(valor: string | null | undefined) {
  // === exigiria duas verificações:
  if (valor !== null && valor !== undefined) { ... }

  // == faz os dois de uma vez:
  if (valor != null) {
    // ✅ null e undefined eliminados — só string
    console.log(valor.toUpperCase());
  }
}

Isso funciona porque null == undefined é true em JavaScript — os dois se cancelam mutuamente com ==.

Truthiness

Truthiness narrowing acontece quando o TypeScript observa se um valor é truthy ou falsy dentro de uma condição e afunila o tipo com base nisso.

Valores falsy em JavaScript

Esses são os únicos valores que avaliam como false num if:

false
0
-0
0n        // bigint zero
""        // string vazia
null
undefined
NaN

Tudo o mais é truthy — incluindo [], {}, "false", -1.

Exemplo básico

function processar(valor: string | null) {
  if (valor) {
    // ✅ null foi eliminado — só string
    console.log(valor.toUpperCase());
  }
}

Type Predicates — guards customizados

Quando nenhum guard nativo basta, você cria o seu com a sintaxe param is Tipo. O TypeScript confia na sua implementação e estreita o tipo em todo lugar que a função for chamada.

// Sintaxe: retorno "param is Tipo" em vez de boolean
function isString(v: unknown): v is string {
  return typeof v === "string";
}

// Caso real: validar shape de objeto externo
type NotaFiscal = { chave: string; valor: number; cnpj: string };

function isNotaFiscal(obj: unknown): obj is NotaFiscal {
  return (
    typeof obj === "object" && obj !== null &&
    "chave" in obj && typeof (obj as any).chave === "string" &&
    "valor" in obj && typeof (obj as any).valor === "number" &&
    "cnpj"  in obj && typeof (obj as any).cnpj  === "string"
  );
}

// Uso — TypeScript estreita o tipo automaticamente
function processarPayload(raw: unknown) {
  if (!isNotaFiscal(raw)) throw new Error("Payload inválido");
  // ✅ raw é NotaFiscal aqui — .chave, .valor, .cnpj disponíveis
  console.log(raw.chave, raw.valor);
}

// Filtrando arrays com predicate (remove undefined do tipo)
const ids: (string | undefined)[] = ["a", undefined, "b"];
const validos: string[] = ids.filter(
  (x): x is string => x !== undefined
); // ✅ tipo inferido como string[]

No fundo, tudo que vimos — typeof, instanceof, in, is, equality, truthiness — são apenas formas diferentes de fornecer evidências para o compilador afunilar o tipo com segurança.