Utility Types no TypeScript: Partial, Required e Record
⚡ Curso de TypeScript • Web-ZoneWare

Utility Types Essenciais (Parte 1): Dominando Partial, Required, Readonly e Record no TypeScript

Lição 33 de 50

Utility Types Essenciais (Parte 1): Dominando Partial, Required, Readonly e Record no TypeScript

Módulo 5: Utility Types, Decorators & Metaprogramação
Lição 33 de 50
Nível: Intermediário / Avançado
⏱ Tempo de Leitura e Prática: 25 minutos

Utility Types Essenciais (Parte 1): Dominando Partial, Required, Readonly e Record no TypeScript

💡
O Que Você Vai Aprender Hoje: Bem-vindo ao Módulo 5! O TypeScript oferece um conjunto de ferramentas integradas globalmente chamadas Utility Types (Tipos Utilitários). Em vez de duplicar contratos e interfaces para cada variação de dados da sua aplicação, você aprenderá a transformar tipos existentes com Partial<T> para atualizações parciais (HTTP PATCH), Required<T> para validações de integridade, Readonly<T> para blindagem de estados imutáveis e Record<K, T> para mapas e dicionários altamente seguros.

1. O Que São Utility Types e Por Que Eles Evitam a Duplicação de Código

Em projetos de médio e grande porte, é comum que a mesma entidade de negócios precise existir em múltiplos formatos ligeiramente diferentes:

  • O modelo completo do banco de dados (todas as propriedades preenchidas).
  • O payload de criação via formulário (alguns campos com valores padrão podem ser opcionais).
  • O payload de atualização (qualquer campo individual pode ser atualizado isoladamente).
  • O estado em cache (onde nenhuma propriedade pode ser modificada diretamente).

Criar uma interface separada para cada uma dessas situações gera uma explosão de código duplicado e frágil (conhecido na engenharia de software como Interface Sprawl). Os Utility Types resolvem isso permitindo que uma única interface mestre seja dinamicamente adaptada para qualquer cenário!

2. Partial<T>: Atualizações Atômicas e Requisições PATCH

O utilitário Partial<T> recebe um tipo genérico T e retorna um novo tipo com todas as suas propriedades transformadas em opcionais (adicionando o modificador ? a cada chave):

TypeScript: Definição Interna e Uso Prático de Partial

TypeScript 27 linhas
// Definição nativa interna na lib.es5.d.ts do TypeScript:
// type Partial<T> = { [P in keyof T]?: T[P]; };
 
interface UsuarioConta {
    id: number;
    nome: string;
    email: string;
    telefone: string;
    cargo: string;
}
 
// Em uma rota de atualização PATCH, o cliente pode enviar apenas o telefone e o nome:
function atualizarUsuario(id: number, dadosAtualizacao: Partial<UsuarioConta>): UsuarioConta {
    console.log(`Atualizando usuário #${id} com os campos:`, dadosAtualizacao);
    // Lógica de mesclagem no banco de dados...
    return {} as UsuarioConta;
}
 
// Válido: atualizando apenas o telefone
atualizarUsuario(101, { telefone: "(11) 98888-7777" });
 
// Válido: atualizando nome e email
atualizarUsuario(102, { nome: "Carlos Eduardo", email: "[email protected]" });
 
// Erro estático do compilador caso envie um campo inexistente:
// @ts-expect-error - "salario" não existe em UsuarioConta
atualizarUsuario(103, { salario: 15000 });
⚠
Atenção: Partial é Superficial (Shallow): O Partial<T> nativo torna opcionais apenas as propriedades de primeiro nível. Se uma propriedade for um objeto aninhado (ex: endereco: { rua: string; numero: number }), as propriedades internas daquele objeto continuarão obrigatórias a menos que você aplique um utilitário recursivo como DeepPartial<T>.

3. Required<T>: Garantia de Preenchimento Total

O oposto complementar do Partial é o Required<T>. Ele utiliza o modificador -? que aprendemos na Lição 32 para remover toda e qualquer opcionalidade, exigindo que todas as propriedades sejam obrigatoriamente fornecidas:

TypeScript: Garantindo Integridade Total com Required

TypeScript 24 linhas
// Definição nativa:
// type Required<T> = { [P in keyof T]-?: T[P]; };
 
interface OpcoesRelatorio {
    titulo: string;
    formato?: "PDF" | "CSV" | "EXCEL";
    incluirGraficos?: boolean;
    dataLimite?: Date;
}
 
// O usuário pode passar apenas o título na chamada:
function gerarRelatorio(opcoes: OpcoesRelatorio): void {
    // Para processar com segurança sem dezenas de checagens if (opcoes.formato !== undefined),
    // mesclamos com valores padrão garantindo um objeto 100% preenchido:
    const configCompleta: Required<OpcoesRelatorio> = {
        titulo: opcoes.titulo,
        formato: opcoes.formato ?? "PDF",
        incluirGraficos: opcoes.incluirGraficos ?? false,
        dataLimite: opcoes.dataLimite ?? new Date()
    };
 
    // Agora o compilador sabe com 100% de certeza que "configCompleta.formato" NUNCA é undefined!
    console.log(configCompleta.formato.toLowerCase());
}

4. Readonly<T>: Imutabilidade Defensiva

O Readonly<T> aplica o modificador readonly a todas as propriedades do tipo. Uma vez inicializado o objeto, qualquer tentativa de reatribuição direta de propriedades gerará um erro estático de compilação:

TypeScript: Blindagem com Readonly

TypeScript 18 linhas
// Definição nativa:
// type Readonly<T> = { readonly [P in keyof T]: T[P]; };
 
interface SessaoAutenticada {
    token: string;
    userId: string;
    expiraEm: number;
}
 
const sessaoSegura: Readonly<SessaoAutenticada> = {
    token: "jwt_token_999888",
    userId: "usr_42",
    expiraEm: 1770000000
};
 
// Tentativa de mutação acidental:
// @ts-expect-error - TS2540: Cannot assign to 'token' because it is a read-only property.
sessaoSegura.token = "novo_token_hackeado";

5. Record<K, T>: Mapas e Dicionários Fortemente Tipados

O utilitário Record<K, T> é utilizado para criar tipos de objetos que representam mapas chave-valor (dicionários), onde K representa os tipos das chaves e T representa o tipo dos valores associados:

📚
Record vs Index Signature Tradicional: Enquanto { [chave: string]: number } permite qualquer chave textual aleatória e não verifica se alguma chave foi esquecida, um Record<UniaoDeChaves, Tipo> obriga que todas as chaves da união sejam expressamente implementadas no objeto!

TypeScript: Matrizes de Permissões com Record

TypeScript 18 linhas
type NivelAcesso = "ADMIN" | "GERENTE" | "OPERADOR" | "CONVIDADO";
 
interface RegraPermissao {
    podeVisualizar: boolean;
    podeCriar: boolean;
    podeExcluir: boolean;
}
 
// O TypeScript OBRIGA a declarar exatamente as 4 chaves definidas em NivelAcesso:
const matrizPermissoes: Record<NivelAcesso, RegraPermissao> = {
    ADMIN: { podeVisualizar: true, podeCriar: true, podeExcluir: true },
    GERENTE: { podeVisualizar: true, podeCriar: true, podeExcluir: false },
    OPERADOR: { podeVisualizar: true, podeCriar: true, podeExcluir: false },
    CONVIDADO: { podeVisualizar: true, podeCriar: false, podeExcluir: false }
};
 
// Acesso seguro com garantia de existência em tempo de compilação:
console.log(matrizPermissoes.GERENTE.podeExcluir); // false

6. Exemplo Enterprise: Gerenciador de Configurações Reativo

Vejamos como uma arquitetura corporativa moderna combina Required, Partial, Readonly e Record em um único serviço centralizado de gerenciamento de configurações da aplicação:

TypeScript: ApplicationConfigStore Enterprise

TypeScript 59 linhas
interface ConfiguracaoGeral {
    nomeApp: string;
    porta: number;
    ambiente: "desenvolvimento" | "homologacao" | "producao";
    maxRequisicoesPorMinuto?: number;
    habilitarAuditoriaLogs?: boolean;
}
 
class GerenciadorConfiguracoes {
    // 1. Estado interno completo e obrigatório (Required)
    private configAtual: Required<ConfiguracaoGeral>;
 
    // 2. Dicionário de ouvintes registrados por evento (Record)
    private ouvintes: Record<"ALTERACAO" | "RESET", Array<() => void>> = {
        ALTERACAO: [],
        RESET: []
    };
 
    constructor(dadosIniciais: ConfiguracaoGeral) {
        this.configAtual = {
            nomeApp: dadosIniciais.nomeApp,
            porta: dadosIniciais.porta,
            ambiente: dadosIniciais.ambiente,
            maxRequisicoesPorMinuto: dadosIniciais.maxRequisicoesPorMinuto ?? 60,
            habilitarAuditoriaLogs: dadosIniciais.habilitarAuditoriaLogs ?? true
        };
    }
 
    // 3. Método de leitura pública: retorna visão imutável para não permitir mutações externas
    public obterConfig(): Readonly<Required<ConfiguracaoGeral>> {
        return Object.freeze({ ...this.configAtual });
    }
 
    // 4. Método de atualização atômica: aceita apenas os campos desejados (Partial)
    public aplicarPatch(mudancas: Partial<ConfiguracaoGeral>): void {
        this.configAtual = {
            ...this.configAtual,
            ...mudancas
        };
        this.notificar("ALTERACAO");
    }
 
    private notificar(evento: "ALTERACAO" | "RESET"): void {
        this.ouvintes[evento].forEach(callback => callback());
    }
}
 
// Demonstração de uso:
const configStore = new GerenciadorConfiguracoes({
    nomeApp: "Web-ZoneWare Core API",
    porta: 3000,
    ambiente: "producao"
});
 
// Atualiza apenas a porta sem quebrar o restante da configuração:
configStore.aplicarPatch({ porta: 8080 });
 
const estadoPublico = configStore.obterConfig();
console.log(`App: ${estadoPublico.nomeApp} rodando na porta ${estadoPublico.porta}`);
⚗️ Teste no Playground IDE Web-ZoneWare
Experimente Partial, Required e Record, teste matrizes de permissão e veja erros de imutabilidade com Readonly.

Abrir Playground TypeScript →

7. Armadilhas Comuns e Boas Práticas de Engenharia

  • Não Confunda Readonly<T> com Congelamento em Runtime: O Readonly<T> impede modificações apenas durante a checagem de tipos do TypeScript. Ele não gera código JavaScript para congelar o objeto em tempo de execução. Se precisar de imutabilidade em runtime real, utilize também Object.freeze().
  • Evite Usar Record<string, any> Desenfreadamente: Usar Record<string, any> é equivalente a desativar a tipagem do objeto. Sempre restrinja o tipo das chaves para uma união literal específica ou use Record<string, unknown>.
  • Composição de Utilitários: Você pode compor utilitários de forma limpa, como Readonly<Partial<T>> para um conjunto de filtros opcionais e imutáveis.

Resumo da Lição 33

  • Partial<T> transforma todas as propriedades de T em opcionais (ideal para requisições PATCH).
  • Required<T> remove a opcionalidade de todas as propriedades (ideal para mesclagem de defaults).
  • Readonly<T> marca todas as propriedades como somente leitura, blindando contratos contra escrita.
  • Record<K, T> cria dicionários tipados onde todas as chaves declaradas em K devem ser satisfeitas.
  • Esses utilitários são nativos da linguagem e evitam a duplicação desenfreada de interfaces no projeto.

📝 Exercício Prático Desafiador da Lição 33

Crie um tipo de entidade ProdutoEstoque com as propriedades: sku (string), nome (string), preco (number), quantidade (number) e descricao (opcional, string).

Em seguida, declare um dicionário CatalogoSKU utilizando Record onde as chaves permitidas sejam os códigos "PROD-001" | "PROD-002" | "PROD-003" e os valores sejam versões imutáveis (Readonly) do produto.

Por fim, crie a assinatura de uma função atualizarProdutoNoCatalogo que receba a chave do produto e um payload com propriedades opcionais (Partial) para atualização segura.

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