Decorators de Campos e Acessores no TypeScript: Guia
⚡ Curso de TypeScript • Web-ZoneWare

Decorators de Campos, Acessores e Auto-Accessors no TypeScript 5.0 (TC39 Stage 3)

Lição 39 de 50

Decorators de Campos, Acessores e Auto-Accessors no TypeScript 5.0 (TC39 Stage 3)

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

Decorators de Campos, Acessores e Auto-Accessors no TypeScript 5.0 (TC39 Stage 3)

💡
O Que Você Vai Aprender Hoje: Historicamente, decorar propriedades de classes em JavaScript sempre foi um pesadelo: os campos eram inicializados diretamente na instância, impossibilitando interceptar leituras e escritas sem truques obscuros. No TypeScript 5.0, a nova especificação introduziu a palavra-chave 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!

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:

TypeScript 10 linhas
// 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:

TypeScript: A Nova Sintaxe de Auto-Accessor

TypeScript 8 linhas
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:

TypeScript: Decorator de Auto-Accessor para Sanitização de Texto

TypeScript 33 linhas
// 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:

TypeScript: Decorator de Campo para Valores Padrão e UUIDs

TypeScript 30 linhas
// 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":

TypeScript: Decorando Getters Tradicionais com Formatação

TypeScript 24 linhas
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).

⚠
Status Atual da Especificação: Na especificação TC39 Stage 3 nativa do JavaScript, a proposta de decorators de parâmetros foi separada para uma fase posterior. Frameworks corporativos continuam suportando decorators de parâmetros através da biblioteca de reflexão 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:

TypeScript: Validador Enterprise de Dados de Clientes

TypeScript 75 linhas
// 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);
}
⚗️ Teste no Playground IDE Web-ZoneWare
Compile auto-accessors, teste validações de e-mail e CPF com decorators e inspecione getters em tempo real.

Abrir Playground TypeScript →

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ção obj.campo = valor, é obrigatório utilizar accessor.
  • Nunca Invoque o Setter Recursivamente: Dentro do método set de um decorator de auto-accessor, nunca escreva this.propriedade = valor, pois isso causará estouro de pilha por recursão infinita (RangeError: Maximum call stack size exceeded). Utilize sempre o método original target.set.call(this, valor).
  • Tratamento do Valor Inicial no init: Lembre-se de fornecer o método init no 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.

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