Restrições Genéricas com extends (Generic Constraints) no TypeScript
Embora Generics permitam escrever código aplicável a qualquer tipo, na imensa maioria das situações reais precisamos impor limites e pré-requisitos estruturais aos nossos tipos. Aprenda como dominar as Restrições Genéricas (Generic Constraints) com a cláusula extends e descubra como preservar o subtipo exato de retorno.
📑 Índice do Conteúdo
1. O Dilema do Genérico Ilimitado
Quando você declara um parâmetro genérico puro <T>, o compilador do TypeScript adota uma postura de máxima neutralidade: ele assume que T pode ser literalmente qualquer coisa — desde uma string até um número, um booleano ou um objeto vazio.
Por conta dessa incerteza, o compilador proíbe preventivamente o acesso a qualquer propriedade ou método que não seja compartilhado por todos os tipos possíveis do JavaScript:
// ❌ TENTATIVA INVÁLIDA:
function registrarComprimento<T>(item: T): number {
// 💥 Erro de compilação:
// TS2339: Property 'length' does not exist on type 'T'.
// return item.length;
return 0;
}
Como o TypeScript pode saber se o chamador passará um número (que não tem .length) ou uma string (que tem .length)? Ele não pode! Para resolver isso, precisamos restringir o tipo genérico a um contrato mínimo.
2. A Cláusula extends em Ação: Restringindo Tipos
Para impor que um tipo genérico obedeça a uma forma estrutural mínima, utilizamos a palavra-chave extends dentro dos colchetes angulares (<T extends FormatoMinimo>):
// Definindo uma interface de pré-requisito:
interface TemComprimento {
length: number;
}
// ✅ RESTRINGINDO T: "T pode ser qualquer coisa, DESDE QUE tenha a propriedade length"
function registrarComprimento<T extends TemComprimento>(item: T): number {
console.log("Comprimento verificado:", item.length);
return item.length;
}
// 1. Strings possuem .length: ✅ Válido!
registrarComprimento("TypeScript Profissional"); // 23
// 2. Arrays possuem .length: ✅ Válido!
registrarComprimento([10, 20, 30, 40]); // 4
// 3. Objetos literais com a chave length: ✅ Válido!
registrarComprimento({ length: 100, titulo: "Relatório" });
// 4. Números NÃO possuem .length: ❌ Erro de compilação!
// registrarComprimento(42);
// TS2345: Argument of type 'number' is not assignable to parameter of type 'TemComprimento'.
3. A Regra de Ouro: Preservando o Subtipo Específico
Muitos desenvolvedores novatos questionam: “Por que escrever <T extends PossuiId>(item: T): T em vez de simplesmente anotar o parâmetro como (item: PossuiId): PossuiId?”
A resposta é a preservação do subtipo de retorno. Veja a diferença dramática no exemplo abaixo:
interface Identificavel {
id: string;
}
interface Colaborador extends Identificavel {
nome: string;
cargo: string;
salarioCentavos: number;
}
// ❌ ABORDAGEM SEM GENERICS: Degradação de Tipo
function atualizarRegistroSemGenerics(item: Identificavel): Identificavel {
return { ...item, id: item.id.toUpperCase() };
}
const func1: Colaborador = { id: "col_01", nome: "Luciana", cargo: "Dev", salarioCentavos: 900000 };
const retorno1 = atualizarRegistroSemGenerics(func1);
// 💥 retorno1 é apenas "Identificavel"!
// Perdemos acesso a retorno1.nome, retorno1.cargo e retorno1.salarioCentavos!
// ==========================================
// ✅ ABORDAGEM COM RESTRINGIMENTO GENÉRICO:
// ==========================================
function atualizarRegistroGenerico<T extends Identificavel>(item: T): T {
return { ...item, id: item.id.toUpperCase() };
}
const retorno2 = atualizarRegistroGenerico(func1);
// ✨ retorno2 preserva integralmente o tipo "Colaborador"!
console.log("Colaborador:", retorno2.nome);
console.log("Cargo:", retorno2.cargo);
console.log("Salário:", retorno2.salarioCentavos);
4. Restrições Baseadas em Chaves com o Operador keyof
Um dos padrões mais aclamados de toda a arquitetura TypeScript é utilizar um parâmetro genérico para restringir outro parâmetro genérico através do operador keyof. Isso viabiliza funções de busca e acesso dinâmico com 100% de segurança de tipos:
// "K" é restrito estritamente às chaves existentes no tipo "T":
function obterPropriedade<T, K extends keyof T>(objeto: T, chave: K): T[K] {
return objeto[chave];
}
const produto = {
codigo: "SKU-992",
preco: 349.90,
emEstoque: true,
tags: ["eletronicos", "audio"]
};
// 1. O compilador autocompleta as chaves válidas e sabe o tipo exato do retorno:
const preco = obterPropriedade(produto, "preco"); // Tipo: number
const tags = obterPropriedade(produto, "tags"); // Tipo: string[]
// 2. Chaves inexistentes geram erro imediato no editor:
// obterPropriedade(produto, "desconto");
// ❌ TS2345: Argument of type '"desconto"' is not assignable to parameter of type '"codigo" | "preco" | "emEstoque" | "tags"'.
5. Restrições Múltiplas com Interseções (&)
Se a sua função exigir que o tipo genérico atenda simultaneamente a mais de uma interface ou contrato, basta combiná-los utilizando o operador de interseção (&):
interface GravavelEmDisco {
salvar(): Promise<void>;
}
interface Auditavel {
criadoEm: Date;
autorId: string;
}
// T deve implementar AMBAS as interfaces:
async function persistirComAuditoria<T extends GravavelEmDisco & Auditavel>(entidade: T): Promise<T> {
console.log(`Auditoria: Registro criado por ${entidade.autorId} em ${entidade.criadoEm.toISOString()}`);
await entidade.salvar();
return entidade;
}
<T extends Contrato> como a tradução formal do princípio de substituição e da tipagem estrutural do TypeScript: você aceita qualquer tipo no mundo que possua pelo menos aquele formato mínimo, devolvendo exatamente o mesmo tipo refinado que entrou sem perder nenhuma propriedade adicional.
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