Arrays Tipados e Tuplas no TypeScript: Guia Prático
⚡ Curso de TypeScript • Web-ZoneWare

Arrays Tipados e Tuplas (Tuples) no TypeScript: Guia Prático

Lição 6 de 50

Arrays Tipados e Tuplas (Tuples) no TypeScript: Guia Prático

⚡ Módulo 1 • Aula 06 de 50

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.

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>).
arrays-basicos.ts
TypeScript
TypeScript 10 linhas
// 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];
⚠️

Cuidado com a Precedência de Parênteses: Declarar (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:

matrizes.ts
TypeScript
TypeScript 12 linhas
// 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:

arrays-readonly.ts
TypeScript
TypeScript 8 linhas
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:

tuplas-basicas.ts
TypeScript
TypeScript 12 linhas
// 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:

tuplas-nomeadas.ts
TypeScript
TypeScript 5 linhas
// 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:

tuplas-opcionais.ts
TypeScript
TypeScript 5 linhas
// 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:

tuplas-rest.ts
TypeScript
TypeScript 4 linhas
// 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:

tuplas-readonly.ts
TypeScript
TypeScript 4 linhas
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:

rastreamento-rotas.ts
TypeScript
TypeScript 37 linhas
// 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}`);
Execute e teste códigos interativos na ferramenta oficial do portal:
Abrir no Playground IDE →

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.
💡

Dica Pro de Engenharia Web-ZoneWare: Utilize Named Tuples (Tuplas Nomeadas) sempre que uma função utilitária precisar retornar mais de um valor relacionado (ex: [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.

🚀

Próximo Passo Prático: Com arrays e tuplas dominados, na Lição 07 vamos desvendar os Enums no TypeScript: numéricos, strings, a anatomia de compilação reversa e por que adotar const enum para máxima performance.

🛠️ Laboratório Prático & Prática Imediata

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.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground 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
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima