Estação #02

Se os tipos primitivos (string, number, boolean) são os átomos de uma aplicação web, os Arrays e Objetos são as moléculas. No desenvolvimento de interfaces ricas com React, raramente lidamos com dados isolados. O cenário real envolve listas de produtos, grades de usuários, objetos de configuração, dicionários de tradução e cargas úteis (payloads) complexas trafegadas entre o cliente e APIs REST ou GraphQL.

O JavaScript puro, por sua natureza de tipagem dinâmica, trata arrays e objetos de forma extremamente flexível e, consequentemente, vulnerável. Um array em JavaScript pode conter simultaneamente números, strings, funções e objetos, enquanto um objeto pode ter propriedades adicionadas ou removidas em tempo de execução sem qualquer aviso. Ao introduzir o TypeScript no ecossistema React, o objetivo principal é domar essa flexibilidade, impondo contratos estruturais rigorosos que o compilador possa analisar estaticamente.

Neste capítulo de aprofundamento, dissecaremos a sintaxe, os padrões arquiteturais e as armadilhas comuns ao trabalhar com Arrays, Tuplas e Objetos tipados, além de demonstrar como o TypeScript é a ferramenta definitiva para proteger a imutabilidade exigida pelo motor de renderização do React.

Arrays no TypeScript: Muito Mais que Simples Listas

Em uma aplicação típica, arrays são utilizados primordialmente para renderizar coleções de elementos na interface do usuário através do método .map(). O TypeScript oferece duas abordagens sintáticas principais para tipar um array de tipos homogêneos.

Colchetes vs. Genéricos

A sintaxe mais comum e idiomática no TypeScript é a utilização do tipo seguido de colchetes [].

const nomesUsuarios: string[] = ["Ana", "Carlos", "Beatriz"];
const idades: number[] = [25, 30, 28];

Alternativamente, é possível utilizar a sintaxe de Genéricos (Generics), que invoca a interface nativa do Array:

const nomesUsuarios: Array<string> = ["Ana", "Carlos", "Beatriz"];
const idades: Array<number> = [25, 30, 28];

Ambas as abordagens são funcionalmente idênticas e a escolha recai sobre diretrizes de estilo da equipe. Contudo, a verdadeira vantagem surge na prevenção de erros. Se um array for tipado como string[], qualquer tentativa de injetar um valor de outro tipo será imediatamente interceptada:

// Erro de compilação: O argumento do tipo 'number' não é atribuível ao parâmetro do tipo 'string'.
nomesUsuarios.push(42);

Tuplas (Tuples): O Segredo por Trás dos Hooks

Uma Tupla é um array de tamanho fixo onde o tipo de cada posição é conhecido e não precisa ser o mesmo. Este é um conceito fundamental para desenvolvedores React, pois é exatamente a estrutura de dados retornada pelo hook useState.

Quando declaramos uma tupla, os tipos são isolados por índice:

type CoordenadaGeografica = [number, number, string];

const localizacao: CoordenadaGeografica = [-23.5505, -46.6333, "São Paulo"];

Para entender a relevância das tuplas, basta observar a assinatura interna do hook useState na biblioteca do React:

function useState<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>];

O retorno é explicitamente tipado como uma Tupla contendo dois elementos estritos: o estado no índice 0 (do tipo S) e a função despachante no índice 1 (do tipo Dispatch). É graças à tipagem baseada em tuplas que o TypeScript permite que você faça a desestruturação (destructuring) nomeando livremente as variáveis, enquanto mantém a inferência de tipo correta para cada uma delas:

// 'contador' é inferido como number. 'setContador' é inferido como a função de atualização.
const [contador, setContador] = useState(0);

Protegendo a Renderização: ReadonlyArray e a Imutabilidade

O React baseia sua reconciliação de estado e gatilhos de re-renderização na imutabilidade das referências de memória. Mutar um array de estado diretamente em JavaScript (usando métodos como .push(), .pop(), ou .splice()) não notifica o React sobre a mudança, resultando em uma interface que não se atualiza.

O TypeScript fornece uma ferramenta de design formidável para impedir isso a nível de código-fonte: o ReadonlyArray.

interface ComponenteListaProps {
  // A lista não pode ser modificada por este componente
  itens: ReadonlyArray<string>; 
}

const ListaDinamica: React.FC<ComponenteListaProps> = ({ itens }) => {
  // Erro Fatal: A propriedade 'push' não existe no tipo 'readonly string[]'.
  // itens.push("Novo Item"); 

  return (
    <ul>
      {itens.map((item, index) => <li key={index}>{item}</li>)}
    </ul>
  );
};

Ao utilizar ReadonlyArray<T> (ou a sintaxe curta readonly T[]), o TypeScript remove todas as assinaturas de métodos mutáveis do objeto. Você só poderá usar métodos que retornam um novo array, como .map(), .filter(), .concat() e .slice(). Essa prática alinha o TypeScript perfeitamente com a filosofia funcional do React.

Objetos: A Espinha Dorsal das Aplicações Web

Enquanto os arrays gerenciam coleções, os Objetos modelam as entidades de domínio da nossa aplicação. Um usuário, um produto em um carrinho de compras, ou as configurações de um painel analítico são representados como objetos. No TypeScript, definimos a "forma" (shape) desses objetos primariamente através de Interfaces ou Type Aliases.

Interfaces e Tipagem Estrutural (Duck Typing)

O TypeScript utiliza um sistema de Tipagem Estrutural, frequentemente apelidado de "Duck Typing" ("Se anda como um pato e grasna como um pato, então é um pato"). Isso significa que o compilador não se importa com a origem do objeto ou qual classe o instanciou; ele verifica apenas se o objeto possui todas as chaves e os tipos corretos exigidos pelo contrato.

interface PerfilUsuario {
  id: string;
  nomeCompleto: string;
  email: string;
  nivelAcesso: number;
}

const renderizarPerfil = (usuario: PerfilUsuario) => {
  console.log(`Renderizando ${usuario.nomeCompleto}`);
};

// Válido, pois o objeto atende estruturalmente à interface PerfilUsuario.
renderizarPerfil({
  id: "uuid-123",
  nomeCompleto: "João Silva",
  email: "joao@email.com",
  nivelAcesso: 1
});

Propriedades Opcionais e Valores Padrão em Componentes

Na modelagem de dados do mundo real, nem toda informação está sempre disponível. Perfis de usuários podem ou não ter um número de telefone cadastrado; botões podem ou não ter um ícone à esquerda. Para modelar essa incerteza controlada, utilizamos propriedades opcionais sinalizadas com um ponto de interrogação ?.

interface ConfiguracaoBotao {
  texto: string;
  acao: () => void;
  iconeUrl?: string; // Propriedade Opcional
  desabilitado?: boolean; // Propriedade Opcional
}

No contexto de componentes React, propriedades opcionais em interfaces de Props casam perfeitamente com a atribuição de valores padrão (Default Parameters) na desestruturação, garantindo que o componente nunca quebre por ausência de dados:

const BotaoCustomizado: React.FC<ConfiguracaoBotao> = ({ 
  texto, 
  acao, 
  iconeUrl, 
  desabilitado = false // Valor padrão seguro se undefined for passado
}) => {
  return (
    <button onClick={acao} disabled={desabilitado}>
      {iconeUrl && <img src={iconeUrl} alt="Ícone" />}
      {texto}
    </button>
  );
};

A Segurança do Modificador readonly em Objetos

Assim como o ReadonlyArray protege listas, o modificador readonly pode ser aplicado às propriedades individuais de um objeto. Isso é vital quando lidamos com entidades cruciais vindas do banco de dados cujo identificador não deve, sob nenhuma circunstância, ser alterado pelo frontend.

interface TransacaoFinanceira {
  readonly id: string;
  readonly dataCriacao: Date;
  valor: number;
  status: "pendente" | "concluida" | "cancelada";
}

const processarTransacao = (t: TransacaoFinanceira) => {
  // Permitido: Atualização de status operacional
  t.status = "concluida"; 
  
  // Erro de Compilação: Não é possível atribuir a 'id' porque é uma propriedade de somente leitura.
  // t.id = "novo-id-malicioso"; 
};

Em geradores de estado complexos como o Redux ou o Context API, marcar a raiz do objeto de estado inteiro como readonly força a equipe a escrever reducers puros, criando cópias profundas (deep copies) ou utilizando bibliotecas como o Immer, blindando a arquitetura contra bugs de mutação em cadeia.

Assinaturas de Índice (Index Signatures) para Dicionários Dinâmicos

Há cenários na construção de sistemas web onde não conhecemos as chaves de um objeto antecipadamente. Pense em um objeto que mapeia códigos de erro de uma API REST para mensagens traduzidas, ou um sistema de cache de requisições.

Para tipar esses "dicionários", utilizamos as Assinaturas de Índice:

interface MapaTraducoes {
  [codigoErro: string]: string;
}

const mensagensErro: MapaTraducoes = {
  "ERR_404": "Recurso não encontrado.",
  "ERR_500": "Falha interna no servidor.",
  "ERR_NETWORK": "Verifique sua conexão com a internet."
};

Essa estrutura diz ao compilador: "Qualquer propriedade neste objeto deve ter uma chave do tipo string, e o seu valor também deve ser do tipo string". É uma forma de flexibilidade, porém tipada, substituindo o terrível hábito de utilizar o tipo any para objetos dinâmicos.

A Intersecção: Arrays de Objetos e o Coração do React

A fusão de Arrays e Objetos é o padrão de dados mais trafegado no ciclo de vida de uma Single Page Application. Quando você consome uma API de listagem, o que o seu Frontend recebe é invariavelmente um Array de Objetos Tipados.

Tipando Listagens e o Problema da Propriedade 'Key'

Considere a construção de um painel de administração que lista os clientes cadastrados na plataforma. Primeiro, definimos a entidade base. Em seguida, tipamos o estado do componente que abrigará a coleção.

interface Cliente {
  readonly id: number;
  nome: string;
  email: string;
  statusAtivo: boolean;
}

const TabelaClientes = () => {
  // Estado tipado como um Array de objetos 'Cliente'. Inicializa vazio.
  const [clientes, setClientes] = useState<Cliente[]>([]);

  // Simulação de fetch de dados
  useEffect(() => {
    fetch("/api/clientes")
      .then(res => res.json())
      .then(data => setClientes(data));
  }, []);

  return (
    <table>
      <tbody>
        {clientes.map((cliente) => (
          // O TS garante que 'cliente' tenha as propriedades 'id' e 'nome'.
          // Isso ajuda a assegurar o uso correto da prop especial 'key' do React.
          <tr key={cliente.id}>
            <td>{cliente.nome}</td>
            <td>{cliente.email}</td>
            <td>{cliente.statusAtivo ? "Online" : "Offline"}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
};

Uma das armadilhas silenciosas do React com JavaScript puro é esquecer ou errar o nome da propriedade identificadora ao passar para o atributo key na função de mapeamento (o que prejudica gravemente o algoritmo de Diffing e a performance do Virtual DOM). Como o TypeScript mapeia estruturalmente a interface Cliente, se o desenvolvedor tentar acessar cliente.identificador ou cliente.Id (com I maiúsculo), o compilador fará a interceptação imediata.

Tipos Utilitários (Utility Types) Aplicados a Objetos

Conforme a base de código do seu sistema cresce, você notará a necessidade de criar variações das suas interfaces. Copiar e colar propriedades entre interfaces viola o princípio DRY (Don't Repeat Yourself) e gera dívida técnica. Para resolver isso, o TypeScript inclui Tipos Utilitários embutidos que transformam objetos tipados dinamicamente.

Três utilitários são essenciais para o uso com o React: Pick, Omit e Partial.

Pick e Omit: Especialização de Interfaces

Imagine que a interface Cliente mostrada anteriormente tenha 30 propriedades (endereço detalhado, histórico de compras, tokens de sessão). No entanto, você precisa construir um componente <AvatarCliente /> que só requer o nome e uma suposta URL de imagem. Passar o objeto inteiro como propriedade viola o princípio do privilégio mínimo de dados.

Você pode extrair apenas o que precisa usando o Pick:

// Cria um novo tipo baseado em Cliente, MAS contendo apenas 'nome' e 'email'
type PropsResumoCliente = Pick<Cliente, "email" "nome" |>;

const CartaoResumo: React.FC<PropsResumoCliente> = ({ nome, email }) => {
  return <div>{nome} - {email}</div>;
};

Inversamente, o Omit cria um novo tipo excluindo propriedades específicas. Isso é extremamente útil ao criar tipos para formulários de criação de novas entidades, onde o banco de dados ainda não gerou o id.

// Cria um tipo com todas as props de Cliente, exceto o 'id'
type PayloadNovoCliente = Omit<Cliente, "id">;

const enviarNovoCliente = (dados: PayloadNovoCliente) => {
  // Lógica de POST na API
};

Partial: Atualizações Flexíveis de Estado

O Partial<T> é um utilitário que pega todas as propriedades de uma interface e as torna opcionais. Ele reflete exatamente a realidade das operações de "Update" ou métodos HTTP PATCH, onde o usuário pode editar apenas o email, apenas o status, ou múltiplos campos de uma vez.

// Atualiza o estado do cliente no React apenas com as propriedades fornecidas
const atualizarCliente = (atualizacoes: Partial<Cliente>) => {
  setClientes(estadoAtual => 
    estadoAtual.map(c => c.id === atualizacoes.id ? { ...c, ...atualizacoes } : c)
  );
};

// Uso válido: Atualiza apenas o status
atualizarCliente({ id: 10, statusAtivo: false });

Conclusão

Arrays e Objetos são as estruturas primárias pelas quais a complexidade flui em qualquer sistema construído sobre a web. Longe de serem meros repositórios de dados genéricos como no JavaScript clássico, o TypeScript eleva essas estruturas ao status de contratos de arquitetura rigorosos.

O domínio sobre Interfaces estritas, o uso consciente de Tuplas para desestruturação de Hooks, a implementação defensiva de modificadores readonly e a inteligência dos Utility Types são ferramentas que transformam o engenheiro de front-end em um verdadeiro arquiteto de software.

A previsibilidade estrutural que o TypeScript introduz anula classes inteiras de bugs antes que o navegador sequer seja aberto, garantindo que suas árvores de componentes React recebam, mapeiem e processem dados com precisão cirúrgica. Com as fundações de tipos primitivos e estruturas complexas solidificadas, o estágio está pronto para abordarmos a ponta da lança no design de tipos avançados: as Funções, Assinaturas de Eventos e Genéricos avançados.