Utility Types Essenciais (Parte 1): Dominando Partial, Required, Readonly e Record no TypeScript
Utility Types Essenciais (Parte 1): Dominando Partial, Required, Readonly e Record no TypeScript
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.
📑 Índice do Conteúdo
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):
// 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 });
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:
// 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:
// 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:
{ [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!
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:
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}`);
7. Armadilhas Comuns e Boas Práticas de Engenharia
- Não Confunda
Readonly<T>com Congelamento em Runtime: OReadonly<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émObject.freeze(). - Evite Usar
Record<string, any>Desenfreadamente: UsarRecord<string, any>é equivalente a desativar a tipagem do objeto. Sempre restrinja o tipo das chaves para uma união literal específica ou useRecord<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 deTem 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 emKdevem 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.
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