Restrições Genéricas no TypeScript: extends
⚡ Curso de TypeScript • Web-ZoneWare

Restrições Genéricas com extends (Generic Constraints) no TypeScript

Lição 27 de 50

Restrições Genéricas com extends (Generic Constraints) no TypeScript

⚡ Módulo 4 • Aula 27 de 50

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.

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:

typescript

JavaScript 7 linhas
// ❌ 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>):

typescript

JavaScript 23 linhas
// 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:

typescript

JavaScript 32 linhas
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:

typescript

JavaScript 19 linhas
// "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 (&):

typescript

JavaScript 15 linhas
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;
}
💡

Dica Pro de Engenharia Web-ZoneWare: Pense na cláusula <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.

🚀

Próximo Passo Prático: Com as restrições genéricas dominadas, na Lição 28 levaremos os Generics para a Programação Orientada a Objetos: Classes e Interfaces Genéricas na Prática.

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