Decorators em TypeScript: de método, classe, campo e accessor

Um decorator é uma função que você anexa a uma classe ou a um membro de classe com @name. Ele recebe o método original (ou a classe, ou o campo) mais um objeto de contexto que o descreve, e pode retornar um substituto. O TypeScript suporta os decorators padrão sem nenhuma flag do compilador.

function logged<This, Args extends unknown[], Return>(
    method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    const name = String(context.name);
    return function (this: This, ...args: Args): Return {
        console.log(`-> ${name}(${args.join(", ")})`);
        const result = method.call(this, ...args);
        console.log(`<- ${name} = ${result}`);
        return result;
    };
}

class Calculator {
    @logged
    add(a: number, b: number): number {
        return a + b;
    }
}

new Calculator().add(2, 3);
// -> add(2, 3)
// <- add = 5

@logged roda uma vez, quando a classe é definida, e substitui add pelo wrapper que retorna. Toda chamada passa pelo wrapper. Os parâmetros genéricos mantêm intactos o this, os argumentos e o tipo de retorno do método, então add continua recebendo dois números e retornando um número.

Como os decorators são compilados

Os decorators padrão vêm de uma proposta do TC39 para o JavaScript, e o TypeScript os implementa desde o TypeScript 5.0. A proposta ainda não faz parte do padrão JavaScript, e o Node 24 não entende a sintaxe @, então quando o target é ES2022 (como nestas páginas) o compilador reescreve cada classe decorada em JavaScript puro que chama funções auxiliares (__esDecorate e __runInitializers, geradas no topo do arquivo). A saída roda em qualquer lugar em que ES2022 roda.

Uma consequência: um arquivo com decorators não roda com o type stripping nativo do Node (node file.ts), que só remove tipos e deixa o @ no lugar. O Node para com SyntaxError: Invalid or unexpected token. Compile-o antes com tsc ou um bundler.

Tipos de decorator e suas assinaturas

Todo decorator padrão tem o formato (value, context) => replacement | void. O que é o value, e o que você pode retornar, depende do que está sendo decorado:

Todo objeto de contexto tem kind, name e addInitializer. O contexto de um membro de classe também tem static, private e um objeto access para ler o membro a partir de uma instância. Decorators também funcionam em membros estáticos e #private.

Decorator factories

Para passar opções, escreva uma função que retorna um decorator e chame-a no local do @. Isso é uma decorator factory:

function retry(times: number) {
    return function <This, Args extends unknown[], Return>(
        method: (this: This, ...args: Args) => Return,
        _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
    ) {
        return function (this: This, ...args: Args): Return {
            for (let attempt = 1; ; attempt++) {
                try {
                    return method.call(this, ...args);
                } catch (e) {
                    if (attempt >= times) throw e;
                    console.log(`attempt ${attempt} failed, retrying`);
                }
            }
        };
    };
}

class Client {
    calls = 0;

    @retry(3)
    fetchData(): string {
        this.calls++;
        if (this.calls < 3) throw new Error("flaky");
        return `ok after ${this.calls} calls`;
    }
}

console.log(new Client().fetchData());

@retry(3) chama retry primeiro, e a função que ele retorna é o decorator de fato. Vários decorators se empilham: em @a @b method(), b é aplicado primeiro e a envolve o resultado.

Decorators de classe e addInitializer

Um decorator de classe recebe a própria classe. Ele pode retornar uma subclasse para substituí-la, ou não retornar nada e só registrá-la em algum lugar. context.addInitializer registra código para rodar em um momento específico: em um decorator de classe, logo depois que a classe é totalmente definida; em um decorator de método, quando cada instância é construída.

const registry = new Map<string, new () => object>();

function register(id: string) {
    return function <T extends new () => object>(target: T, context: ClassDecoratorContext<T>) {
        context.addInitializer(() => {
            registry.set(id, target);
        });
    };
}

// Binds a method to its instance, so it survives being passed as a callback.
function bound<This, Args extends unknown[], Return>(
    _method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    context.addInitializer(function (this: This) {
        const self = this as Record<string | symbol, unknown>;
        const fn = self[context.name] as (...a: unknown[]) => unknown;
        self[context.name] = fn.bind(this);
    });
}

@register("greeter")
class Greeter {
    name = "Ada";

    @bound
    greet(): string {
        return `Hello, ${this.name}`;
    }
}

const g = new Greeter();
const loose = g.greet; // detached from g
console.log(loose());  // Hello, Ada
console.log([...registry.keys()], registry.get("greeter") === Greeter); // [ 'greeter' ] true

O decorator de classe fica acima da classe (ou depois do export). Sem o @bound, chamar loose() lançaria um erro, porque o this seria undefined.

Decorators de campo e de accessor

Um decorator de campo não consegue ver nem interceptar atribuições posteriores: o value dele é undefined, e tudo o que ele pode retornar é uma função que transforma o valor inicial do campo. Para interceptar leituras e escritas, declare o campo com a palavra-chave accessor, que o transforma em um par de getter e setter sobre um armazenamento privado, e decore isso:

function trimmed(_value: undefined, _context: ClassFieldDecoratorContext<unknown, string>) {
    return (initial: string) => initial.trim();
}

function positive<This>(
    target: ClassAccessorDecoratorTarget<This, number>,
    context: ClassAccessorDecoratorContext<This, number>,
): ClassAccessorDecoratorResult<This, number> {
    const check = (v: number) => {
        if (v <= 0) throw new RangeError(`${String(context.name)} must be positive, got ${v}`);
        return v;
    };
    return {
        init: check, // runs on the initial value
        set(v) {
            target.set.call(this, check(v));
        },
    };
}

class Product {
    @trimmed title = "  Lamp  ";
    @positive accessor price = 30;
}

const p = new Product();
console.log(`[${p.title}]`, p.price); // [Lamp] 30
p.price = 45;
console.log(p.price); // 45
try {
    p.price = -5;
} catch (e) {
    if (e instanceof Error) console.log(e.message); // price must be positive, got -5
}

O accessor faz parte da mesma proposta. Ele gera um getter e um setter de verdade sobre um campo #private, e é por isso que p.price = -5 passa pelo set do decorator.

Decorators padrão vs experimentalDecorators legado

Antes do TypeScript 5.0, os únicos decorators que o TypeScript tinha eram uma versão inicial da proposta, ativada com experimentalDecorators. Essa flag ainda existe e troca o compilador para o modelo legado, com assinaturas e semântica diferentes:

Um decorator escrito para um modelo não passa na verificação de tipos no outro. Aqui está um decorator no estilo legado em um projeto sem a flag:

// This does not compile: a legacy decorator used as a standard one.
function log(target: object, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = function (this: unknown, ...args: unknown[]) {
        console.log("calling", key);
        return original.apply(this, args);
    };
}

class Service {
    @log
    run(): string {
        return "done";
    }
}

console.log(new Service().run());

index.ts(11,5): error TS1241: Unable to resolve signature of method decorator when called as an expression.
  The runtime will invoke the decorator with 2 arguments, but the decorator expects 3.

A solução é reescrevê-lo na forma padrão (value, context), como no primeiro exemplo desta página, ou ligar o modelo legado no projeto inteiro:

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Angular, NestJS e TypeORM ainda definem experimentalDecorators nas configurações que suas ferramentas geram e que suas docs pedem. NestJS e TypeORM também precisam do emitDecoratorMetadata, porque leem tipos em tempo de execução: o NestJS para injetar parâmetros de construtor, o TypeORM para mapear propriedades para colunas:

// Legacy model: needs experimentalDecorators (and emitDecoratorMetadata for DI).
@Injectable()
class UsersService {
    constructor(@Inject(DB) private db: Database) {}
}

Se você usa um desses frameworks, escreva os decorators do jeito legado e siga as docs dele. Para código novo sem um framework desses, use os decorators padrão.

Quando usar decorators

Decorators combinam com comportamentos transversais que, sem eles, se repetiriam em muitos métodos: log, medição de tempo, cache, novas tentativas, verificações de acesso, validação e registro de classes em um container ou roteador. Eles também escondem o fluxo de controle, já que quem lê precisa procurar o que o @retry faz antes de saber o que o método faz. Para um ou dois usos, uma função de ordem superior simples (const fetchData = retry(3, rawFetch)) é mais simples e funciona também fora de classes.