TypeScript: tipos que protegem

Descrever a forma dos dados para que o editor aponte erros antes de você abrir o navegador.

Cerca de 15 min · Revisado em

Ao final, você vai conseguir

  • Anotar tipos em variáveis, parâmetros e retornos
  • Descrever objetos com type e interface
  • Usar unions e narrowing para tratar cada caso
  • Explicar por que tipos não validam dados vindos da rede

O carrinho mostra “Total: R$ 2510” para um pastel de 25 reais com frete de 10. Ninguém percebeu, porque o código rodou sem erro nenhum. Bugs assim chegam até o cliente porque o JavaScript só descobre o problema na hora de executar. O TypeScript aponta esse tipo de erro enquanto você ainda está digitando.

O erro que só aparece na frente do cliente

Lembra que campo.value é sempre texto? Veja o que acontece quando esse texto encontra uma conta. O JavaScript não reclama: ele dá um jeito, e o jeito dele nem sempre é o que você queria.

O campo de preço tem 25 digitado. O que aparece no console?

function somarFrete(preco, frete) {
  return preco + frete;
}

const preco = campoPreco.value; // o campo mostra 25
console.log(somarFrete(preco, 10));
  • 2510
  • 35
  • Um erro dizendo que texto não pode ser somado
  • NaN
  • Escrever produto.prco no lugar de produto.preco devolve undefined, e a conta vira NaN.
  • Chamar usuario.endereco.cidade quando o cadastro não tem endereço quebra a página com “Cannot read properties of undefined”.
  • Mudar o nome de um campo num arquivo e esquecer outros três lugares que o usavam.

Todos esses erros têm algo em comum: dava para saber que estavam errados sem rodar o código, só olhando que tipo de valor cada coisa guarda. É essa leitura que o TypeScript faz por você.

Em JavaScript puro, como você corrigiria somarFrete? E qual é o problema dessa correção num projeto grande?

Convertendo o texto em número: somarFrete(Number(campoPreco.value), 10). O problema é que você precisa lembrar disso em cada lugar que chama a função, para sempre, e nada avisa quando alguém esquece. O TypeScript transforma esse “lembrar” numa regra que o editor confere.

JavaScript com etiquetas

TypeScript é JavaScript com tipos. Todo JavaScript válido continua valendo; você só acrescenta etiquetas. Um programa chamado compilador confere as etiquetas e depois as remove, gerando JavaScript comum, que é o que o navegador entende.

Do arquivo .ts até a tela

  1. Você → TypeScript: carrinho.ts. Você escreve o código com tipos num arquivo .ts. O editor já consulta o TypeScript enquanto você digita.
  2. TypeScript → Você: Erro na linha 12. O compilador encontrou um texto onde deveria haver número e sublinha a linha em vermelho. Nada chegou ao navegador ainda.
  3. Você → TypeScript: código corrigido. Você converte o valor com Number(...) e salva. Agora as etiquetas combinam.
  4. TypeScript → TypeScript: remove os tipos. O compilador (o tsc, ou o Vite no projeto) apaga as anotações e gera JavaScript comum.
  5. TypeScript → Navegador: carrinho.js. O navegador recebe JavaScript puro e executa. Ele nunca vê um tipo sequer.

Depois de compilado, o que sobra dos tipos no arquivo que roda no navegador?

  • Nada: os tipos são apagados
  • Eles continuam lá e o navegador confere cada valor
  • Viram mensagens de erro no console

Anotar tipos e deixar o TypeScript deduzir

Uma função com parâmetros e retorno anotados.

function total(preco: number, quantidade: number): number {
  return preco * quantidade;
}

const valor = total(25, 2);
  • Parâmetro anotado: Os dois-pontos colocam a etiqueta: preco só aceita números. Chamar total("25", 2) vira erro no editor.
  • Outro parâmetro: Cada parâmetro tem a própria etiqueta. Os tipos básicos são os que você já conhece: number, string, boolean.
  • Tipo do retorno: Depois dos parênteses, o que a função devolve. Se alguém mudar o corpo e ela passar a devolver texto, o erro aparece aqui.
  • Inferência: Sem anotação nenhuma, o TypeScript deduz que valor é number, porque sabe o que total devolve. Isso se chama inferência.

Você não precisa anotar tudo. Em const nome = "Ana", o TypeScript já sabe que é texto. A regra prática: anote parâmetros de função, e deixe a inferência cuidar das variáveis.

Onde o TypeScript aponta erro neste código?

function total(preco: number, quantidade: number): number {
  return preco * quantidade;
}

function aoMudar(campo: HTMLInputElement) {
  total(campo.value, 2);
}
  • Em campo.value: texto não pode entrar onde se espera number
  • Em preco * quantidade, porque a multiplicação é arriscada
  • Em lugar nenhum; o erro só apareceria ao rodar

Complete as anotações: a função recebe um nome e uma idade e devolve se a pessoa pode tirar habilitação.

function podeDirigir(nome: ____, idade: ____): ____ {
  return idade >= 18;
}

Descrever a forma dos objetos

Na vida real, você trabalha mais com objetos do que com números soltos. Com type (ou interface), você descreve a forma de um objeto uma vez e reaproveita em todo o projeto.

O mesmo carrinho em JavaScript e em TypeScript.

JavaScript

// Que campos um produto tem? Só lendo o resto do código para saber.
function subtotal(itens) {
  let soma = 0;
  for (const item of itens) {
    soma = soma + item.prco * item.quantidade; // erro de digitação: vira NaN
  }
  return soma;
}

TypeScript

type ItemCarrinho = {
  nome: string;
  preco: number;
  quantidade: number;
  observacao?: string; // o ? quer dizer: pode não existir
};

function subtotal(itens: ItemCarrinho[]): number {
  let soma = 0;
  for (const item of itens) {
    soma = soma + item.prco * item.quantidade;
    //                 ~~~~ Property 'prco' does not exist.
    //                      Did you mean 'preco'?
  }
  return soma;
}
type Produto = { ... }
Dá um nome a uma forma de objeto. Cada campo tem nome e tipo, separados por ;.
interface Produto { ... }
Outra forma de descrever objetos, quase igual. Escolha uma e seja consistente; muitos times usam type para tudo.
Campo opcional ?
desconto?: number quer dizer que o campo pode faltar. O TypeScript obriga você a tratar o caso em que ele é undefined.
Produto[]
Um array de produtos. Também pode ser escrito Array<Produto>.

O que o TypeScript diz sobre a última linha?

type Produto = {
  nome: string;
  preco: number;
  desconto?: number;
};

function precoFinal(produto: Produto) {
  return produto.preco - produto.desconto;
}
  • Aponta erro: desconto pode ser undefined
  • Nenhum erro: desconto é number
  • Aponta erro: a função não tem tipo de retorno

Descreva um produto do catálogo e um array deles. A avaliação é opcional.

type Produto = {
  nome: ____;
  preco: ____;
  avaliacao____: number;
};

const catalogo: ____ = [];

Um valor, vários casos possíveis

Às vezes um valor pode ser uma coisa ou outra. Uma union (união) usa a barra vertical para listar as possibilidades. Com textos exatos, ela impede valores inventados.

Só três valores são aceitos. Um erro de digitação vira erro no editor.

type Situacao = 'carregando' | 'sucesso' | 'erro';

let situacao: Situacao = 'carregando';
situacao = 'sucesso';   // ok
situacao = 'sucesos';   // erro: não é uma das opções

Melhor ainda: lembra dos quatro estados de uma tela? Cada estado carrega dados diferentes. Uma union discriminada junta objetos que compartilham um campo, como tipo, que diz qual caso é qual.

Acompanhe o que o TypeScript sabe sobre estado em cada linha. Nada roda aqui: é o editor raciocinando.

type Estado =
  | { tipo: 'carregando' }
  | { tipo: 'sucesso'; produtos: Produto[] }
  | { tipo: 'erro'; mensagem: string };

function descrever(estado: Estado): string {
  if (estado.tipo === 'carregando') {
    return 'Carregando...';
  }
  if (estado.tipo === 'erro') {
    return estado.mensagem;
  }
  return estado.produtos.length + ' produtos';
}
  1. Linha 1: Define três formas possíveis. O campo tipo diferencia cada uma.
  2. Linha 6: No começo da função, estado pode ser qualquer um dos três. Só tipo é garantido em todos.
  3. Linha 7: Dentro deste if, o TypeScript sabe que é o caso carregando. Isso se chama narrowing (estreitamento).
  4. Linha 10: Se chegou aqui, não era carregando: esse caso saiu da lista.
  5. Linha 11: Dentro deste if, só pode ser erro. Por isso estado.mensagem é permitido.
  6. Linha 13: Sobrou um caso só: sucesso. estado.produtos existe com certeza.
  7. Linha 13: Se você escrevesse estado.mensagem aqui, o editor reclamaria: no caso sucesso, não existe mensagem.

O if não é a única forma de estreitar. typeof valor === "string" separa textos de números. "preco" in objeto confere se um campo existe. Em todos os casos, depois da pergunta o TypeScript passa a saber mais.

Qual linha o TypeScript aceita sem erro?

function formatar(valor: string | number) {
  // qual destas linhas pode ficar aqui?
}
  • if (typeof valor === 'number') return valor.toFixed(2);
  • return valor.toFixed(2);
  • return valor.toUpperCase();

Com type Estado da animação acima, o que o TypeScript aceita e o que ele aponta como erro?

Aceita · Aponta erro

  • const e: Estado = { tipo: 'carregando' };
  • const e: Estado = { tipo: 'erro', mensagem: 'Sem rede' };
  • const e: Estado = { tipo: 'erro' };
  • const e: Estado = { tipo: 'vazio' };
  • const e: Estado = { tipo: 'sucesso', produtos: [] };
  • const e: Estado = { tipo: 'sucesso', mensagem: 'ok' };

Onde os tipos não chegam

Os tipos são poderosos, mas têm limites. Conhecê-los evita a falsa sensação de segurança, que é pior do que não ter tipo nenhum.

any desliga a proteção; unknown obriga você a conferir.

any: sem proteção

const dados: any = JSON.parse(texto);

dados.produtoss.map((p) => p.nome);
// Compila sem reclamar. Quebra na frente do cliente.

unknown: confira antes

const dados: unknown = JSON.parse(texto);

dados.produtos;
// ~~~~ Erro: 'dados' is of type 'unknown'.

if (Array.isArray(dados)) {
  console.log(dados.length); // ok: agora é um array
}

Validar cada item antes de confiar nele. Bibliotecas como o Zod automatizam isso em projetos maiores.

function paraProduto(item: unknown): Produto {
  if (
    typeof item === 'object' && item !== null &&
    'nome' in item && typeof item.nome === 'string' &&
    'preco' in item && typeof item.preco === 'number'
  ) {
    return { nome: item.nome, preco: item.preco };
  }
  throw new Error('Produto inválido na resposta da API');
}

async function buscarProdutos(): Promise<Produto[]> {
  const resposta = await fetch('/api/produtos');
  const dados: unknown = await resposta.json();
  if (!Array.isArray(dados)) throw new Error('Esperava uma lista');
  return dados.map(paraProduto);
}

O código declara const produto: Produto = await resposta.json() e a API manda { "nome": "Pastel", "preco": "8" }. O que acontece?

  • Nada avisa; produto.preco é o texto "8" e as contas saem erradas
  • O TypeScript mostra um erro no editor
  • O navegador lança um erro de tipo ao receber o JSON
  • O TypeScript converte "8" em 8 automaticamente

Erro comum

Usar any para o erro sumir

O erro some, a proteção também. Prefira unknown e confira o valor, ou descubra o tipo certo.

Erro comum

Mentir com as

dados as Produto[] manda o TypeScript acreditar em você sem conferir. É uma promessa, não uma verificação.

Erro comum

Desligar o strict

Com "strict": true no tsconfig.json, o TypeScript confere null, undefined e parâmetros sem tipo. Sem ele, metade da proteção desaparece. Deixe sempre ligado.

Erro comum

Confiar em tipos para dados externos

Resposta de API, localStorage, campo de formulário: tudo o que vem de fora precisa ser validado em tempo de execução.

Qual destes problemas o TypeScript pega antes de rodar, e qual só uma validação durante a execução pega?

O TypeScript pega antes · Só a validação ao rodar pega

  • Escrever produto.prco no lugar de produto.preco
  • Chamar total("25", 2) com texto
  • A API mandar preco como texto
  • Usar desconto opcional sem tratar undefined
  • O localStorage ter um JSON antigo, com outro formato
  • A API devolver um objeto quando você esperava uma lista

Fechamento

  • TypeScript é JavaScript com tipos: o compilador confere tudo antes de rodar e depois apaga os tipos.
  • Anote os parâmetros das funções e deixe a inferência cuidar das variáveis; descreva objetos com type ou interface e marque campos opcionais com ?.
  • Unions listam os casos possíveis, e o narrowing com if, typeof e in faz o TypeScript saber qual caso você está tratando.
  • Prefira unknown a any, mantenha strict ligado e valide em tempo de execução tudo o que vem da rede.

Coloque tipos no seu catálogo

Leve o catálogo do projeto Aplicação com API para TypeScript, sem any, e prove que ele não confia cegamente na API.

  1. Ative "strict": true no tsconfig.json e confira que continua ligado no fim
  2. Crie o type Produto com todos os campos que a tela usa, marcando os opcionais com ?
  3. Descreva o estado da tela como uma union discriminada com carregando, sucesso, vazio e erro
  4. Escreva uma função que valida cada item da resposta da API, recebendo unknown, antes de usá-lo
  5. Rode o compilador e garanta zero erros sem usar any nem as para escondê-los
  6. Quebre a validação de propósito, mudando um campo da resposta, e confira que a tela mostra o estado de erro

Referências

Cursos relacionados