Index Signatures no TypeScript: Guia Completo
⚡ Curso de TypeScript • Web-ZoneWare

Index Signatures: Propriedades Dinâmicas e Dicionários Tipados no TypeScript

Lição 15 de 50

Index Signatures: Propriedades Dinâmicas e Dicionários Tipados no TypeScript

⚡ Módulo 2 • Aula 15 de 50

No mundo real, nem sempre conhecemos os nomes exatos de todas as chaves de um objeto antecipadamente: dicionários, caches em memória, tabelas de tradução i18n e mapas de configuração exigem flexibilidade. Aprenda como dominar as Index Signatures no TypeScript para modelar propriedades dinâmicas com segurança estrita e evitar armadilhas de runtime.

1. O Que É uma Index Signature e Por Que Ela Existe

Uma Index Signature permite descrever o tipo dos valores de um objeto quando você não sabe de antemão os nomes de todas as propriedades que ele conterá, mas conhece o tipo da chave e o tipo do valor associado a ela.

A sintaxe utiliza colchetes com um nome de parâmetro representativo (como [chave: string] ou [index: number]) seguido pelo tipo do valor retornado:

typescript

JavaScript 16 linhas
// Definindo um mapa de contagem de acessos (Dicionário de números)
interface ContadorAcessos {
    [url: string]: number;
}
 
const metricasDiarias: ContadorAcessos = {
    "/home": 1420,
    "/web-academy/typescript/": 890,
    "/contato": 45
};
 
// Podemos adicionar novas chaves arbitrariamente, desde que o valor seja number:
metricasDiarias["/blog/artigo-ts"] = 312;
 
// ❌ Erro de compilação: TS2322: Type 'string' is not assignable to type 'number'.
metricasDiarias["/sobre"] = "duzentos";

2. A Regra de Ouro da Compatibilidade Estrutural

Quando você combina uma Index Signature com propriedades fixas pré-definidas na mesma interface, o TypeScript impõe uma regra matemática intransigente: o tipo de retorno da index signature deve ser abrangente o bastante para acolher todas as propriedades nomeadas.

Se uma propriedade explícita tiver um tipo incompatível com a assinatura de índice geral, o compilador rejeitará o contrato imediatamente:

typescript

CODE 25 linhas
// ❌ ERRO DE COMPILAÇÃO:
interface PerfilInvalido {
    [chave: string]: string; // Declara que TODAS as chaves de texto devem ter valor string!
    nome: string;            // Válido: string é compatível com string.
    // TS2411: Property 'idade' of type 'number' is not assignable to 'string' index type 'string'.
    idade: number;           
}
 
// ==========================================
// ✅ SOLUÇÃO 1: Usar Union Type na Index Signature
// ==========================================
interface PerfilFlexivel {
    [chave: string]: string | number; // Agora aceita tanto texto quanto números!
    nome: string;
    idade: number;
}
 
// ==========================================
// ✅ SOLUÇÃO 2: Separar Propriedades Fixas do Dicionário Dinâmico
// ==========================================
interface PerfilSeparado {
    nome: string;
    idade: number;
    metadadosCustomizados: Record<string, unknown>; // Dicionário isolado!
}

3. Dualidade de Índices: string versus number

No JavaScript, os objetos possuem uma peculiaridade histórica fundamental: se você indexar um objeto com um número (ex: obj[10]), o runtime automaticamente converte esse número para uma string (obj["10"]) antes de buscar a propriedade na memória.

Por conta dessa conversão implícita do JavaScript, o TypeScript exige que se uma interface contiver ambas as index signatures (numérica e de texto), o tipo retornado pelo índice numérico DEVE ser um subtipo do tipo retornado pelo índice de string:

typescript

JavaScript 21 linhas
class Animal {
    especie: string = "Desconhecida";
}
 
class Cachorro extends Animal {
    latir() {
        console.log("Au au!");
    }
}
 
// ✅ VÁLIDO: Cachorro é subtipo de Animal.
interface Zoologico {
    [id: number]: Cachorro;  // Mais específico (subtipo)
    [nome: string]: Animal;  // Mais abrangente (supertipo)
}
 
// ❌ ERRO: TS2413: 'number' index type 'Animal' is not assignable to 'string' index type 'Cachorro'.
interface ZooInvalido {
    [id: number]: Animal;
    [nome: string]: Cachorro;
}

4. O Perigo Oculto e a Flag noUncheckedIndexedAccess

Por padrão, nas configurações padrão do TypeScript, ao acessar qualquer chave de um objeto com index signature, o compilador assume otimisticamente que a propriedade sempre existe. Isso cria uma falsa sensação de segurança que pode derrubar sua aplicação em produção com o infame TypeError: Cannot read properties of undefined:

typescript

JavaScript 14 linhas
interface TabelaPrecos {
    [produto: string]: number;
}
 
const precos: TabelaPrecos = {
    notebook: 4500,
    mouse: 120
};
 
// Com as configurações padrão do TS:
const valorTeclado = precos["teclado"]; 
// O compilador diz que valorTeclado é "number", mas em runtime ele é UNDEFINED!
console.log(valorTeclado.toFixed(2)); 
// 💥 TypeError em runtime: Cannot read properties of undefined (reading 'toFixed')!

Para eliminar essa vulnerabilidade fatal de arquitetura, o TypeScript introduziu no tsconfig.json a flag de rigor absoluto: "noUncheckedIndexedAccess": true.

Quando ativada, qualquer leitura em uma index signature tem seu tipo de retorno automaticamente afunilado para Tipo | undefined, obrigando você a realizar checagens defensivas:

typescript

JavaScript 13 linhas
// COM "noUncheckedIndexedAccess": true no tsconfig.json:
const valorTeclado = precos["teclado"]; // Tipo inferido: number | undefined!
 
// ❌ O compilador agora avisa e BLOQUEIA o erro antes do deploy:
// TS18048: 'valorTeclado' is possibly 'undefined'.
// valorTeclado.toFixed(2);
 
// ✅ Código defensivo profissional:
if (typeof valorTeclado === "number") {
    console.log("Preço:", valorTeclado.toFixed(2));
} else {
    console.warn("Produto não catalogado na tabela de preços.");
}

5. Modificador readonly em Index Signatures

Você também pode aplicar o modificador readonly a uma assinatura de índice para criar tabelas de lookup e dicionários de leitura estritamente congelados:

typescript

JavaScript 11 linhas
interface DicionarioImutavel {
    readonly [termo: string]: string;
}
 
const traducoes: DicionarioImutavel = {
    btn_salvar: "Save",
    btn_cancelar: "Cancel"
};
 
// ❌ Erro de compilação: TS2542: Index signature in type 'DicionarioImutavel' only permits reading.
// traducoes["btn_salvar"] = "Salvar";

6. Index Signatures vs. Utilitário Record<K, V>

Muitas vezes você verá no código sênior o uso do utility type Record<Keys, Type>. Qual a relação dele com a Index Signature?

  • [key: string]: V aceita qualquer string arbitrária e é implementado diretamente dentro de uma interface.
  • Record<K, V> é mais flexível porque permite restringir as chaves a uniões literais exatas (ex: Record<'ativo' | 'inativo', number>), algo que uma Index Signature tradicional não permite na sintaxe padrão.
💡

Dica Pro de Engenharia Web-ZoneWare: Habilite sempre "noUncheckedIndexedAccess": true no arquivo tsconfig.json dos seus projetos corporativos. Ele transforma o TypeScript em um escudo de ferro contra acessos a chaves inexistentes em objetos de configuração e mapas de dados externos.

🚀

Próximo Passo Prático: Agora que você domina propriedades dinâmicas, na Lição 16 aprenderemos como assumir o controle do sistema de tipos quando você sabe mais que o compilador: Asserções de Tipo (Type Assertions com as) e Asserções Constantes (as const).

🛠️ 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