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));251035- Um erro dizendo que texto não pode ser somado
NaN
- Escrever
produto.prcono lugar deproduto.precodevolveundefined, e a conta viraNaN. - Chamar
usuario.endereco.cidadequando 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
- Você → TypeScript: carrinho.ts. Você escreve o código com tipos num arquivo
.ts. O editor já consulta o TypeScript enquanto você digita. - 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.
- Você → TypeScript: código corrigido. Você converte o valor com
Number(...)e salva. Agora as etiquetas combinam. - TypeScript → TypeScript: remove os tipos. O compilador (o
tsc, ou o Vite no projeto) apaga as anotações e gera JavaScript comum. - 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:
precosó aceita números. Chamartotal("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 quetotaldevolve. 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 esperanumber - 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
typepara tudo. - Campo opcional
? desconto?: numberquer 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:
descontopode serundefined - 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çõesMelhor 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';
}- Linha 1: Define três formas possíveis. O campo
tipodiferencia cada uma. - Linha 6: No começo da função,
estadopode ser qualquer um dos três. Sótipoé garantido em todos. - Linha 7: Dentro deste
if, o TypeScript sabe que é o caso carregando. Isso se chama narrowing (estreitamento). - Linha 10: Se chegou aqui, não era carregando: esse caso saiu da lista.
- Linha 11: Dentro deste
if, só pode ser erro. Por issoestado.mensagemé permitido. - Linha 13: Sobrou um caso só: sucesso.
estado.produtosexiste com certeza. - Linha 13: Se você escrevesse
estado.mensagemaqui, 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"em8automaticamente
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.prcono lugar deproduto.preco - Chamar
total("25", 2)com texto - A API mandar
precocomo texto - Usar
descontoopcional sem tratarundefined - O
localStorageter 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
typeouinterfacee marque campos opcionais com?. - Unions listam os casos possíveis, e o narrowing com
if,typeofeinfaz o TypeScript saber qual caso você está tratando. - Prefira
unknownaany, mantenhastrictligado 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.
- Ative
"strict": truenotsconfig.jsone confira que continua ligado no fim - Crie o
type Produtocom todos os campos que a tela usa, marcando os opcionais com? - Descreva o estado da tela como uma union discriminada com carregando, sucesso, vazio e erro
- Escreva uma função que valida cada item da resposta da API, recebendo
unknown, antes de usá-lo - Rode o compilador e garanta zero erros sem usar
anynemaspara escondê-los - Quebre a validação de propósito, mudando um campo da resposta, e confira que a tela mostra o estado de erro