Decorators de Campos, Acessores e Auto-Accessors no TypeScript 5.0 (TC39 Stage 3)
Decorators de Campos, Acessores e Auto-Accessors no TypeScript 5.0 (TC39 Stage 3)
accessor (Auto-Accessors). Hoje você aprenderá a criar decorators para campos normais, getters/setters e auto-accessors, habilitando validação declarativa, máscaras de dados e sanitização em tempo real!
📑 Índice do Conteúdo
1. O Problema Histórico das Propriedades de Classe e a Chegada do Auto-Accessor
Em JavaScript, quando você declara nome: string = "Ana"; em uma classe, esse campo não passa por nenhum método: ele é simplesmente gravado na memória da instância. Se você quisesse validar esse valor sempre que alguém tentasse alterá-lo, era forçado a escrever manualmente um getter e um setter com um campo privado auxiliar:
// Abordagem Verbosa Tradicional:
class ExemploAntigo {
private _nome: string = "";
get nome(): string { return this._nome; }
set nome(valor: string) {
if (!valor) throw new Error("Nome obrigatório");
this._nome = valor;
}
}
Para resolver isso de forma elegante, a especificação TC39 e o TypeScript 5.0 introduziram a palavra-chave accessor. Ao declarar um campo como accessor, o compilador gera automaticamente o campo privado oculto e os acessores get e set:
class UsuarioModerno {
// Cria automaticamente o getter e setter nos bastidores!
accessor nome: string = "Carlos";
}
const user = new UsuarioModerno();
console.log(user.nome); // Invoca o getter gerado
user.nome = "Eduardo"; // Invoca o setter gerado
2. Decorators de Auto-Accessors (ClassAccessorDecoratorContext)
O verdadeiro poder dos auto-accessors surge quando os combinamos com Decorators. Um decorator aplicado a um accessor recebe um objeto contendo os métodos get e set originais e pode retornar novos métodos get e set substitutos, além de uma função init para tratar o valor inicial:
// Assinatura do decorator para auto-accessors:
function EmCaixaAlta<This, Value extends string>(
target: { get: (this: This) => Value; set: (this: This, value: Value) => void },
context: ClassAccessorDecoratorContext<This, Value>
) {
return {
// Intercepta a leitura (getter)
get(this: This): Value {
return target.get.call(this);
},
// Intercepta a escrita (setter): força o valor a maiúsculas antes de gravar!
set(this: This, novoValor: Value) {
const valorTratado = (novoValor ? novoValor.trim().toUpperCase() : "") as Value;
console.log(`[ACCESSOR SET] Formatando "${novoValor}" -> "${valorTratado}"`);
target.set.call(this, valorTratado);
},
// Trata o valor inicial fornecido no construtor ou declaração
init(valorInicial: Value): Value {
return (valorInicial ? valorInicial.trim().toUpperCase() : "") as Value;
}
};
}
class PerfilEmpresa {
@EmCaixaAlta
accessor codigoIdentificador: string = "emp-998";
}
const empresa = new PerfilEmpresa();
console.log(empresa.codigoIdentificador); // ___WZW_STR_0___ (Formatado no init!)
empresa.codigoIdentificador = "matriz_sp"; // Log: Formatando ___WZW_STR_1___ -> ___WZW_STR_2___
console.log(empresa.codigoIdentificador); // ___WZW_STR_0___
3. Decorators de Campos Comuns (ClassFieldDecoratorContext)
E quanto às propriedades convencionais da classe (declaradas sem a palavra accessor)?
Um decorator de campo recebe undefined como primeiro parâmetro (porque o campo ainda não existe no protótipo da classe) e seu context.kind é "field". Esse decorator pode retornar uma função inicializadora que transforma o valor inicial da propriedade no momento em que cada instância é construída:
// Decorator que gera um UUID aleatório caso a propriedade não receba valor
function GerarUuidPadrao(
target: undefined,
context: ClassFieldDecoratorContext
) {
const nomeCampo = String(context.name);
// Retorna uma função que recebe o valor atribuído e retorna o valor final
return function (valorInicial: any) {
if (!valorInicial) {
const novoId = `UUID-${Math.random().toString(36).substring(2, 9).toUpperCase()}`;
console.log(`[CAMPO AUTO] ${nomeCampo} inicializado com ${novoId}`);
return novoId;
}
return valorInicial;
};
}
class PedidoVenda {
@GerarUuidPadrao
public id!: string;
constructor(public valorTotal: number) {}
}
const pedido1 = new PedidoVenda(150.00);
console.log("ID Pedido 1:", pedido1.id); // UUID-XXXXX gerado automaticamente!
const pedido2 = new PedidoVenda(300.00);
console.log("ID Pedido 2:", pedido2.id); // Outro UUID único!
4. Decorators de Getters e Setters Tradicionais
Se você já declarou explicitamente um método get ou set tradicional na sua classe, você pode decorá-los individualmente. O objeto de contexto terá context.kind = "getter" ou context.kind = "setter":
function FormatarMoedaBRL(
getterOriginal: Function,
context: ClassGetterDecoratorContext
) {
return function (this: any): string {
const valorNumerico: number = getterOriginal.call(this);
return new Intl.NumberFormat("pt-BR", {
style: "currency",
currency: "BRL"
}).format(valorNumerico);
};
}
class FaturaMensal {
constructor(private totalCentavos: number) {}
@FormatarMoedaBRL
get valorFormatado(): number {
return this.totalCentavos / 100;
}
}
const fatura = new FaturaMensal(154990);
console.log("Total da fatura:", fatura.valorFormatado); // ___WZW_STR_1___
5. O Que Aconteceu com Decorators de Parâmetros?
Na era pré-TS 5.0 (com experimentalDecorators), você talvez tenha visto anotações diretamente nos parâmetros de funções, como: metodo(@Body() payload: any).
reflect-metadata e metadados de métodos, tópico fundamental que dominaremos na Lição 40!
6. Exemplo Enterprise: Validação Declarativa com Auto-Accessors
Vamos construir um sistema corporativo completo de validação de formulários com auto-accessors, impedindo e-mails inválidos e formatando CPFs em tempo real:
// Decorator Factory para validação estrita de E-mail
function ValidarEmail() {
return function <This, Value extends string>(
target: { get: (this: This) => Value; set: (this: This, value: Value) => void },
context: ClassAccessorDecoratorContext<This, Value>
) {
const regexEmail = /^[^s@]+@[^s@]+.[^s@]+$/;
return {
set(this: This, novoEmail: Value) {
if (!regexEmail.test(novoEmail)) {
const msgErro = `[ERRO DE VALIDAÇÃO] E-mail inválido fornecido: "${novoEmail}"`;
console.error(msgErro);
throw new Error(msgErro);
}
console.log(`[E-MAIL VÁLIDO]: ${novoEmail}`);
target.set.call(this, novoEmail.toLowerCase() as Value);
},
init(valorInicial: Value): Value {
if (valorInicial && !regexEmail.test(valorInicial)) {
throw new Error(`E-mail inicial inválido: "${valorInicial}"`);
}
return valorInicial ? (valorInicial.toLowerCase() as Value) : valorInicial;
}
};
};
}
// Decorator Factory para formatação de CPF (aplica máscara 000.000.000-00)
function MascaraCpf() {
return function <This, Value extends string>(
target: { get: (this: This) => Value; set: (this: This, value: Value) => void },
context: ClassAccessorDecoratorContext<This, Value>
) {
function formatar(cpfBruto: string): string {
const digitos = cpfBruto.replace(/D/g, "");
if (digitos.length !== 11) return cpfBruto;
return digitos.replace(/(d{3})(d{3})(d{3})(d{2})/, "$1.$2.$3-$4");
}
return {
set(this: This, valor: Value) {
target.set.call(this, formatar(valor) as Value);
},
init(valorInicial: Value): Value {
return valorInicial ? (formatar(valorInicial) as Value) : valorInicial;
}
};
};
}
class CadastroClienteEmpresarial {
@ValidarEmail()
accessor email: string;
@MascaraCpf()
accessor cpf: string;
constructor(email: string, cpf: string) {
this.email = email;
this.cpf = cpf;
}
}
// 1. Instanciação com dados válidos:
const cliente = new CadastroClienteEmpresarial("[email protected]", "12345678901");
console.log("E-mail sanitizado:", cliente.email); // ___WZW_STR_1___
console.log("CPF formatado:", cliente.cpf); // ___WZW_STR_1___
// 2. Tentativa de atribuir e-mail inválido em runtime:
try {
cliente.email = "email_sem_arroba.com";
} catch (e: any) {
console.log("Operação bloqueada com sucesso:", e.message);
}
7. Armadilhas Comuns e Boas Práticas Sênior
- Não Confunda Decorator de Campo com Decorator de Accessor: Um decorator em um campo normal (sem
accessor) não consegue interceptar atribuições posteriores de valor; ele só executa no momento da inicialização. Se você precisa validar ou transformar dados em cada atribuiçãoobj.campo = valor, é obrigatório utilizaraccessor. - Nunca Invoque o Setter Recursivamente: Dentro do método
setde um decorator de auto-accessor, nunca escrevathis.propriedade = valor, pois isso causará estouro de pilha por recursão infinita (RangeError: Maximum call stack size exceeded). Utilize sempre o método originaltarget.set.call(this, valor). - Tratamento do Valor Inicial no
init: Lembre-se de fornecer o métodoinitno objeto retornado pelo decorator de auto-accessor caso você precise sanitizar o valor passado diretamente na declaração ou no construtor.
Resumo da Lição 39
- A palavra-chave
accessor(Auto-Accessor) do TypeScript 5.0 gera automaticamente campos privados com getters e setters nativos. - Decorators de Auto-Accessors (
ClassAccessorDecoratorContext) interceptam tanto a leitura (get) quanto a escrita (set) e inicialização (init). - Decorators de Campos comuns (
ClassFieldDecoratorContext) operam na fase de inicialização da instância, sendo ideais para gerar identificadores padrão e UUIDs. - Decorators de Getters/Setters tradicionais modificam o acesso a propriedades computadas da classe.
- Essa infraestrutura viabiliza validação declarativa limpa em entidades de domínio sem poluir a arquitetura do projeto.
📝 Exercício Prático Desafiador da Lição 39
1. Crie um Decorator de Auto-Accessor chamado @LimitarIntervalo(min: number, max: number) para propriedades numéricas. Se o valor atribuído for menor que min ou maior que max, ele deve lançar um erro descritivo de validação.
2. Aplique seu decorator em uma classe TermostatoSensor no campo accessor temperaturaAlvo: number; com limites de 10 a 40 graus Celsius e comprove o bloqueio de valores fora do intervalo.
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