Arrays Tipados e Tuplas (Tuples) no TypeScript: Guia Prático
Aprenda a estruturar coleções ordenadas com segurança de tipos: domine a sintaxe de arrays homogêneos e multidimensionais, blinde listas contra mutações acidentais com readonly e utilize Tuplas (Tuples) para representar sequências rígidas e pares de dados.
📑 Índice do Conteúdo
1. Arrays Tipados: As Duas Sintaxes Equivalentes
No TypeScript, existem duas maneiras formais e equivalentes de declarar que uma variável armazena uma lista ordenada de elementos homogêneos:
- Sintaxe Literal com Colchetes (
Tipo[]): A abordagem mais concisa e amplamente adotada pela comunidade (ex:number[],string[]). - Sintaxe com Tipo Genérico (
Array<Tipo>): Uma notação baseada em tipos genéricos (ex:Array<number>,Array<string>).
TypeScript
// 1. Sintaxe Literal com Colchetes
const precos: number[] = [29.90, 49.50, 199.00];
const tecnologias: string[] = ["TypeScript", "Next.js", "Docker"];
// 2. Sintaxe Genérica (Semanticamente idêntica)
const identificadores: Array<number> = [101, 102, 103];
// 3. Arrays Heterogêneos (União de Tipos dentro do Array)
// O array aceita números ou strings misturados:
const dadosMistos: (string | number)[] = ["ID-99", 1500, "ID-100", 2800];
(string | number)[] representa um array de elementos que podem ser string ou number. Se você esquecer os parênteses e escrever string | number[], você estará declarando que a variável é uma string única OU um array de números!
2. Arrays Multidimensionais (Matrizes)
Para representar matrizes bidimensionais (como grades, tabelas ou tabuleiros), basta encadear colchetes adicionais:
TypeScript
// Matriz 3x3 de números (number[][]):
const tabuleiroJogoDaVelha: number[][] = [
[1, 0, 2],
[0, 1, 0],
[2, 0, 1]
];
// Matriz tridimensional de coordenadas (3D):
const gradeVoxel: number[][][] = [
[[255, 0, 0], [0, 255, 0]],
[[0, 0, 255], [255, 255, 0]]
];
3. Imutabilidade com Arrays Readonly
Em JavaScript, arrays são estruturas mutáveis. Qualquer parte do código pode invocar métodos de mutação como push(), pop() ou alterar posições diretamente por índice (precos[0] = 0), causando efeitos colaterais silenciosos em aplicações concorrentes.
Para proteger listas contra alterações acidentais, utilize o modificador readonly:
TypeScript
const cargosAdmin: readonly string[] = ["SuperAdmin", "Auditor", "Gerente"];
// ❌ ERROS DE COMPILAÇÃO IMEDIATOS:
// cargosAdmin.push("Estagiario"); // Erro TS2339: Property 'push' does not exist on type 'readonly string[]'.
// cargosAdmin[0] = "Convidado"; // Erro TS2542: Index signature only permits reading.
// Métodos de leitura e cópia imutável (map, filter, slice) continuam 100% disponíveis:
const cargosEmMinusculo = cargosAdmin.map(c => c.toLowerCase()); // Válido e seguro!
4. O que são Tuplas (Tuples) no TypeScript?
Uma Tupla é uma estrutura de coleção especializada do TypeScript onde o número exato de elementos e o tipo de cada posição (índice) são rigorosamente conhecidos e fixados.
Enquanto um array number[] pode ter qualquer quantidade de números (0, 5 ou 10.000 itens), uma tupla [number, string] exige exatamente dois elementos, sendo o primeiro um número e o segundo uma string:
TypeScript
// Declaração de Tupla: [códigoStatus, mensagemStatus]
let respostaHttp: [number, string] = [200, "OK"];
// ❌ ERRO TS2322: Tipos ou ordem invertida
// respostaHttp = ["OK", 200]; // Type 'string' is not assignable to type 'number'.
// ❌ ERRO TS2322: Quantidade incorreta de elementos
// respostaHttp = [200, "OK", true]; // Source has 3 elements but target allows 2.
// Desestruturação limpa e segura com tipos deduzidos automaticamente:
const [codigo, mensagem] = respostaHttp;
// codigo é inferido como number; mensagem é inferida como string
5. Recursos Modernos de Tuplas (TS 4.0+)
Tuplas Nomeadas (Named Tuples)
O TypeScript permite atribuir rótulos descritivos a cada posição da tupla. Esses rótulos não alteram o código em tempo de execução, mas transformam a experiência no editor, documentando o significado de cada índice no Intellisense:
TypeScript
// Definição elegante de coordenadas geográficas
type PontoGeografico = [latitude: number, longitude: number];
// Ao passar o mouse sobre a variável ou parâmetro, o VS Code exibe "latitude" e "longitude":
const localizacaoSede: PontoGeografico = [-23.5505, -46.6333];
Elementos Opcionais em Tuplas
Assim como em interfaces e funções, você pode declarar elementos opcionais em tuplas utilizando o caractere ? ao final da posição:
TypeScript
// O terceiro elemento (telefone) é opcional:
type ContatoRapido = [nome: string, email: string, telefone?: string];
const contato1: ContatoRapido = ["Marcos", "[email protected]"];
const contato2: ContatoRapido = ["Helena", "[email protected]", "(11) 98888-7777"];
Tuplas com Rest Elements (…T[])
Você pode criar tuplas com uma parte inicial fixa e uma cauda de tamanho variável:
TypeScript
// Primeiro item: código numérico; demais itens: tags em string
type EventoComTags = [codigo: number, ...tags: string[]];
const logAuditoria: EventoComTags = [1042, "auth", "login", "sucesso", "ip-valido"];
6. Tuplas Readonly: A Blindagem Definitiva
Como tuplas são compiladas para arrays nativos do JavaScript, a especificação legada permitia que métodos como push() adicionassem itens à tupla sem disparar alertas em tempo de execução. Para impedir qualquer violação de tamanho, sempre declare tuplas críticas com o modificador readonly:
TypeScript
const configuracaoResolucao: readonly [largura: number, altura: number] = [1920, 1080];
// ❌ ERRO TS2339: O compilador bloqueia mutações
// configuracaoResolucao.push(60); // Property 'push' does not exist on type 'readonly [largura: number, altura: number]'.
7. Exemplo Prático de Engenharia: Sistema de Geolocalização e Rotas
Veja como integrar arrays e tuplas nomeadas em um serviço profissional de rastreamento logístico:
TypeScript
// 1. Named Tuple para pontos cartográficos
type CoordenadaGPS = readonly [latitude: number, longitude: number];
// 2. Named Tuple para status de envio: [codigoHttp, mensagem, sucesso]
type StatusRastreamento = readonly [codigo: number, mensagem: string, entregue: boolean];
// 3. Array de pontos formando uma rota de entregas
const rotaCaminhao: CoordenadaGPS[] = [
[-23.5505, -46.6333], // São Paulo (Ponto de Partida)
[-23.1857, -46.8978], // Jundiaí (Parada 1)
[-22.9056, -47.0608] // Campinas (Destino Final)
];
// 4. Função que calcula a distância euclidiana simples entre duas coordenadas
function calcularDistanciaLinear(pontoA: CoordenadaGPS, pontoB: CoordenadaGPS): number {
const [latA, lonA] = pontoA;
const [latB, lonB] = pontoB;
const deltaLat = latB - latA;
const deltaLon = lonB - lonA;
return Math.sqrt(deltaLat * deltaLat + deltaLon * deltaLon);
}
// 5. Função de auditoria que retorna uma Tupla com status
function auditarEntrega(distanciaTotal: number): StatusRastreamento {
if (distanciaTotal > 0) {
return [200, "Rota calculada com sucesso", true];
}
return [400, "Coordenadas idênticas ou inválidas", false];
}
const distanciaSpCampinas = calcularDistanciaLinear(rotaCaminhao[0], rotaCaminhao[2]);
const [statusCod, statusMsg, isEntregue] = auditarEntrega(distanciaSpCampinas);
console.log(`[LOGÍSTICA] Distância calculada: ${distanciaSpCampinas.toFixed(4)} graus.`);
console.log(`[STATUS] #${statusCod} - ${statusMsg} | Ativo: ${isEntregue}`);
8. Tabela Comparativa: Arrays vs. Tuplas
| Característica | Arrays Comuns (T[]) |
Tuplas Comuns ([T, U]) |
Tuplas Readonly (readonly [T, U]) |
|---|---|---|---|
| Tamanho da Coleção | Dinâmico (0 a N elementos). | Rigorosamente fixo por contrato. | Rigorosamente fixo por contrato. |
| Homogeneidade | Tipos uniformes (ou união ampla). | Posição por posição com tipos específicos. | Posição por posição com tipos específicos. |
| Métodos de Mutação (push) | Permitidos. | Permitidos em runtime (potencial risco). | Bloqueados em compilação. |
| Acesso por Desestruturação | Gera T | undefined nos índices. |
Tipos exatos preservados na ordem. | Tipos exatos preservados na ordem. |
[dados: T, erro: Error | null] ou [latitude: number, longitude: number]). Isso oferece a ergonomia de desestruturação com a documentação embutida de um objeto, sem alocar memória extra para chaves desnecessárias.
const enum para máxima performance.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE