Operador keyof e Lookup Types: Indexação Tipada de Propriedades no TypeScript
Para construir utilitários avançados e evitar redundância em modelos de dados, o TypeScript oferece duas ferramentas metalinguísticas complementares de altíssimo poder: o operador keyof para inspecionar nomes de propriedades e os Lookup Types (T[K]) para extrair tipos por indexação.
📑 Índice do Conteúdo
1. O Operador keyof (Type Query de Chaves)
O operador keyof opera sobre um tipo de objeto e produz uma união de literais de string ou numéricos representando todas as chaves públicas presentes naquele contrato:
interface UsuarioPerfil {
id: string;
nome: string;
email: string;
idade: number;
ativo: boolean;
}
// O operador keyof extrai uma união literal exata com os nomes das chaves:
type ChavesUsuario = keyof UsuarioPerfil;
// Resultado: "id" | "nome" | "email" | "idade" | "ativo"
// Qualquer variável deste tipo só aceita essas strings específicas:
let campoFormulario: ChavesUsuario = "email"; // ✅ Válido!
// campoFormulario = "telefone"; // ❌ TS2322: Type '"telefone"' is not assignable to type 'ChavesUsuario'.
[chave: string]: unknown, o resultado de keyof será string | number. Isso ocorre porque o JavaScript converte automaticamente chaves numéricas para texto ao acessar propriedades de dicionários.
2. Lookup Types (Indexed Access Types: T[K])
Assim como você usa colchetes no JavaScript para acessar o valor de uma propriedade (obj["email"]), no TypeScript você usa colchetes para acessar o tipo estático dessa propriedade: é o chamado Lookup Type ou Indexed Access Type.
// Extraindo o tipo de uma propriedade isolada:
type TipoEmail = UsuarioPerfil["email"]; // Tipo: string
type TipoIdade = UsuarioPerfil["idade"]; // Tipo: number
// Extraindo tipos de múltiplas propriedades simultaneamente via Union:
type Identificadores = UsuarioPerfil["id" | "email"]; // Tipo: string
// 🌟 O TRUQUE SUPREMO: Extrair a união de TODOS os tipos de valores do objeto!
type TodosValoresPossiveis = UsuarioPerfil[keyof UsuarioPerfil];
// Resultado: string | number | boolean
3. Lookup Types em Arrays e Tuplas (T[number])
Os Lookup Types não se limitam a objetos: você pode utilizá-los para desempacotar tipos internos de listas e tuplas sem precisar redefinir interfaces:
const niveisPermissao = ["leitura", "escrita", "administrador"] as const;
// 1. Extraindo o tipo dos elementos de um array ou tupla usando [number]:
type NivelPermissao = (typeof niveisPermissao)[number];
// Resultado: "leitura" | "escrita" | "administrador"
// 2. Extraindo tipos posicionais específicos em tuplas usando o índice fixo [0], [1]:
type CoordenadaGeo = [latitude: number, longitude: number, cidade: string];
type TipoLatitude = CoordenadaGeo[0]; // Tipo: number
type TipoCidade = CoordenadaGeo[2]; // Tipo: string
4. Caso Prático 1: Getter e Setter Totalmente Tipados
Combinar keyof com Lookup Types é o segredo para escrever utilitários universais de acesso e mutação de propriedades com 100% de segurança de tipos:
// Getter Universal e Seguro:
function obterPropriedade<T, K extends keyof T>(objeto: T, chave: K): T[K] {
return objeto[chave];
}
// Setter Universal e Seguro:
function atualizarPropriedade<T, K extends keyof T>(objeto: T, chave: K, novoValor: T[K]): void {
objeto[chave] = novoValor;
}
const config = {
tema: "escuro" as "escuro" | "claro",
portaServidor: 8080,
modoDepuracao: true
};
// 1. O compilador valida o tipo exato do valor correspondente à chave informada:
atualizarPropriedade(config, "portaServidor", 3000); // ✅ Válido!
atualizarPropriedade(config, "tema", "claro"); // ✅ Válido!
// 2. O compilador BARRARÁ se passarmos um tipo incompatível com aquela chave:
// atualizarPropriedade(config, "portaServidor", "porta-8080");
// ❌ TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
5. Caso Prático 2: Sistema de Eventos Tipados (Type-Safe EventEmitter)
Em arquiteturas modernas reativas, é fundamental garantir que o payload de cada evento corresponda estritamente ao tipo da mensagem disparada:
// Contrato Central de Mensageria da Aplicação:
interface EventosSistema {
"USUARIO_CRIADO": { id: string; email: string; criadoEm: Date };
"PAGAMENTO_APROVADO": { transacaoId: string; valorCentavos: number };
"SISTEMA_OFFLINE": { codigoMotivo: number };
}
// Classe de Emissão de Eventos com Indexação Tipada:
class EmissorEventos {
private ouvintes: { [K in keyof EventosSistema]?: Array<(dados: EventosSistema[K]) => void> } = {};
on<K extends keyof EventosSistema>(evento: K, callback: (payload: EventosSistema[K]) => void): void {
if (!this.ouvintes[evento]) {
this.ouvintes[evento] = [];
}
this.ouvintes[evento]!.push(callback);
}
emit<K extends keyof EventosSistema>(evento: K, payload: EventosSistema[K]): void {
const callbacks = this.ouvintes[evento];
if (callbacks) {
callbacks.forEach(cb => cb(payload));
}
}
}
// Consumo com Autocomplete Inteligente:
const emissor = new EmissorEventos();
// ✅ O editor autocompleta "USUARIO_CRIADO" e sabe que dados possui .email:
emissor.on("USUARIO_CRIADO", (dados) => {
console.log("Novo aluno cadastrado:", dados.email);
});
// ✅ O compilador exige exatamente os campos de PAGAMENTO_APROVADO:
emissor.emit("PAGAMENTO_APROVADO", {
transacaoId: "TX-7711",
valorCentavos: 19900
});
keyof e Lookup Types é a chave que abre a porta para os recursos mais avançados do TypeScript. Eles servem de alicerce para os Mapped Types e todos os Utility Types nativos (como Pick, Omit e Record) que utilizaremos no Módulo 5.
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