TypeScript: Código Mais Seguro e Produtivo em Projetos Reais

JavaScript é flexível demais. Uma variável pode ser string, number, null e um objeto — tudo na mesma função. TypeScript adiciona um sistema de tipos que detecta erros antes mesmo do código rodar, reduzindo bugs em produção e acelerando a manutenção em times de qualquer tamanho.

Por que TypeScript, e não apenas JavaScript?

A promessa do JavaScript era simplicidade: escreva e execute. Mas à medida que aplicações cresceram, a ausência de tipos tornou-se um gargalo. Renomear uma propriedade de objeto exigia buscas manuais em dezenas de arquivos. Uma função recebia argumentos inesperados e falhava silenciosamente. Testes capturavam esses erros, mas só em runtime.

TypeScript compila para JavaScript puro, o que significa que roda em qualquer lugar onde JS roda: navegadores, Node.js, dispositivos IoT. A diferença está no desenvolvimento: o compilador analisa seu código e aponta inconsistências antes do deploy.

Configurando um Projeto do Zero

A configuração mínima exige três passos: instalar o compilador, criar um tsconfig.json e configurar o entry point.

# Inicializa o projeto
npm init -y

# Instala TypeScript localmente (recomendado)
npm install typescript --save-dev

# Gera o tsconfig.json padrão
npx tsc --init

O tsconfig.json gerado contém dezenas de opções comentadas. Para projetos novos, recomenda-se ativar o strict mode, que habilita verificações rigorosas e evita armadilhas comuns.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

Tipos Básicos: O Alfabeto

TypeScript estende os tipos primitivos do JavaScript com anotações explícitas. A regra fundamental: toda variável, parâmetro e retorno de função pode ter um tipo.

// Tipos primitivos
let nome: string = "Ana";
let idade: number = 28;
let ativo: boolean = true;
let nada: null = null;
let indefinido: undefined = undefined;

// Arrays
let notas: number[] = [8.5, 9.0, 7.5];
let alternativo: Array<string> = ["a", "b"];

// Any e unknown: não são a mesma coisa
let qualquer: any = 42;       // desabilita verificação
let desconhecido: unknown = 42; // exige verificação antes de uso

if (typeof desconhecido === "number") {
  console.log(desconhecido.toFixed(2));
}

unknown é preferível a any. Ele força você a validar o tipo antes de operar, preservando a segurança que o TypeScript oferece.

Interfaces e Type Aliases

Objetos complexos precisam de estrutura. Interfaces e type aliases definem contratos: a forma esperada de um objeto. Interfaces são extensíveis; type aliases são mais flexíveis para uniões e tuplas.

interface Usuario {
  id: number;
  nome: string;
  email: string;
  admin?: boolean; // propriedade opcional
}

interface Admin extends Usuario {
  permissoes: string[];
}

// Type alias para uniões
type Status = "pendente" | "aprovado" | "rejeitado";

type Pedido = {
  id: string;
  valor: number;
  status: Status;
};

function processarPedido(p: Pedido): string {
  if (p.status === "aprovado") {
    return `Pedido ${p.id} liberado para envio.`;
  }
  return `Pedido ${p.id} aguardando análise.`;
}

A escolha entre interface e type geralmente é estilística. Para objetos que serão estendidos, prefira interface. Para uniões, tuplas ou mapeamentos, type é mais natural.

Inferência: Menos Código, Mesma Segurança

TypeScript é inteligente o suficiente para deduzir tipos em muitos contextos. Anotar tudo é desnecessário e verboso.

// Inferência automática
const saudacao = "Olá";       // string
const numeros = [1, 2, 3];    // number[]
const hoje = new Date();      // Date

// Retorno de função inferido
function dobrar(x: number) {
  return x * 2; // retorno inferido como number
}

// Objeto literal com inferência
const usuario = {
  nome: "Carlos",
  idade: 34,
};

usuario.nome = 123; // Erro: Type 'number' is not assignable to type 'string'

Generics: Código Reutilizável e Tipado

Generics permitem escrever funções, classes e interfaces que funcionam com qualquer tipo, mas mantêm a informação de tipo em vez de recair em any.

// Função genérica simples
function primeiro<T>(array: T[]): T | undefined {
  return array[0];
}

const p1 = primeiro([1, 2, 3]);     // number | undefined
const p2 = primeiro(["a", "b"]);    // string | undefined

// Com restrições (constraints)
interface TemId {
  id: string;
}

function buscarPorId<T extends TemId>(lista: T[], id: string): T | undefined {
  return lista.find((item) => item.id === id);
}

// Generic em interface
interface RespostaApi<T> {
  dados: T;
  status: number;
  mensagem?: string;
}

type UsuarioApi = RespostaApi<Usuario>;
// { dados: Usuario; status: number; mensagem?: string }

Generics são particularmente úteis em bibliotecas, utilitários reutilizáveis e abstrações sobre fetch, bancos de dados e estado global. Eles eliminam a necessidade de casting manual.

Union Types e Narrowing

Muitas APIs retornam valores que podem ser de tipos diferentes. Union types combinam possibilidades; narrowing restringe o tipo dentro de blocos condicionais.

type Resultado<T> =
  | { sucesso: true; valor: T }
  | { sucesso: false; erro: string };

function tratarResposta<T>(res: Resultado<T>): T | never {
  if (res.sucesso) {
    return res.valor; // T
  }
  throw new Error(res.erro);
}

// Discriminated unions para estados
interface Carregando {
  estado: "carregando";
}
interface Sucesso {
  estado: "sucesso";
  dados: unknown;
}
interface Erro {
  estado: "erro";
  mensagem: string;
}

type EstadoUI = Carregando | Sucesso | Erro;

function renderizar(estado: EstadoUI): string {
  switch (estado.estado) {
    case "carregando":
      return "Carregando...";
    case "sucesso":
      return String(estado.dados);
    case "erro":
      return estado.mensagem;
  }
}

Type Guards e Validação em Runtime

TypeScript desaparece em runtime: não há verificação de tipos quando o código executa. Se você recebe dados de uma API externa, precisa validar antes de usar.

// Type guard com typeof
function isString(val: unknown): val is string {
  return typeof val === "string";
}

// Type guard com instanceof
function isDate(val: unknown): val is Date {
  return val instanceof Date;
}

// Validação de API (exemplo simplificado)
interface Produto {
  id: number;
  nome: string;
  preco: number;
}

function isProduto(obj: unknown): obj is Produto {
  return (
    typeof obj === "object" &&
    obj !== null &&
    "id" in obj &&
    typeof (obj as Record<string, unknown>).id === "number" &&
    "nome" in obj &&
    typeof (obj as Record<string, unknown>).nome === "string" &&
    "preco" in obj &&
    typeof (obj as Record<string, unknown>).preco === "number"
  );
}

// Uso seguro
const dados: unknown = await fetch("/api/produto/1").then((r) => r.json());
if (isProduto(dados)) {
  console.log(dados.nome.toUpperCase()); // seguro
} else {
  console.error("Resposta inválida da API");
}

Para validações mais complexas, bibliotecas como Zod, Valibot ou Yup oferecem schemas declarativos que geram tipos TypeScript automaticamente.

Produtividade com IDE

O verdadeiro ganho de TypeScript não é apenas no compilador, mas na experiência de desenvolvimento. Autocompletar, navegação para definição, refatoração segura e detecção de código morto são possíveis porque a IDE conhece a estrutura do seu programa.

• Renomear símbolo: altera todas as referências em um segundo, sem busca manual.
• Extração de função: a IDE mantém os tipos dos parâmetros automaticamente.
• Verificação de cobertura: identifica branches e caminhos não testados.
• Documentação inline: passe o mouse sobre uma função e veja sua assinatura e comentários JSDoc.
• Importação automática: adicione imports conforme digita, sem digitar caminhos manualmente.

TypeScript em Frameworks Modernos

React, Vue, Svelte, Angular e Next.js oferecem suporte nativo a TypeScript. A integração vai além de compilar: hooks, props, eventos e stores ganham tipos que prevenem erros de componentização.

// React com TypeScript
import { useState } from "react";

interface ContadorProps {
  inicial?: number;
  passo?: number;
}

export default function Contador({ inicial = 0, passo = 1 }: ContadorProps) {
  const [valor, setValor] = useState<number>(inicial);

  return (
    <button onClick={() => setValor((v) => v + passo)}>
      Contador: {valor}
    </button>
  );
}

O ecossistema npm é majoritariamente tipado hoje. Mesmo pacotes antigos geralmente têm arquivos @types/ disponíveis. A experiência de usar uma biblioteca com tipos é drasticamente superior.

Armadilhas Comuns e Como Evitá-las

• any implícito: desative noImplicitAny e use unknown em vez de any.
• Non-null assertion (!): evite `elemento!.propriedade`. Prefira verificações nulas reais.
• Casting forçado (as): `valor as string` silencia o compilador. Use type guards.
• Enums numéricos: prefera const objects ou string enums para evitar valores mágicos.
• Type gymnastics excessivo: se um tipo leva mais de 5 minutos para entender, simplifique.

Conclusão

TypeScript não é apenas uma camada de tipos sobre JavaScript. É uma ferramenta de produtividade que muda como times escrevem, leem e mantêm código. A segurança em tempo de compilação reduz bugs em produção. A inferência inteligente mantém o código enxuto. E a integração com IDEs transforma refatorações arriscadas em operações triviais.

Se você ainda não usa TypeScript, comece com strict: true em um projeto pequeno. A curva de aprendizado de algumas semanas paga-se em meses de desenvolvimento mais tranquilo. Em projetos grandes, a diferença é ainda mais dramática: sem tipos, a complexidade cresce exponencialmente. Com tipos, ela permanece gerenciável.

Perguntas frequentes

Fontes consultadas

• TypeScript Documentation
• TypeScript Handbook — Everyday Types
• Zod — TypeScript-First Schema Validation