Decoradores en TypeScript: de método, clase, campo y accessor

Un decorador es una función que asocias a una clase o a un miembro de una clase con @name. Recibe el método original (o la clase, o el campo) más un objeto de contexto que lo describe, y puede devolver un sustituto. TypeScript admite los decoradores estándar sin ninguna opción del 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 se ejecuta una sola vez, cuando se define la clase, y sustituye add por el envoltorio que devuelve. Cada llamada pasa por el envoltorio. Los parámetros genéricos mantienen intactos los tipos de this, de los argumentos y del retorno del método, así que add sigue recibiendo dos números y devolviendo un número.

Cómo se compilan los decoradores

Los decoradores estándar vienen de una propuesta de TC39 para JavaScript, y TypeScript los implementa desde TypeScript 5.0. La propuesta todavía no forma parte del estándar de JavaScript, y Node 24 no interpreta la sintaxis @, así que cuando el target es ES2022 (como en estas páginas) el compilador reescribe cada clase decorada en JavaScript normal que llama a funciones auxiliares (__esDecorate y __runInitializers, que se generan al principio del archivo). La salida funciona en cualquier sitio donde funcione ES2022.

Una consecuencia: un archivo con decoradores no se puede ejecutar con el type stripping integrado de Node (node file.ts), que solo quita los tipos y deja el @ en su sitio. Node se detiene con SyntaxError: Invalid or unexpected token. Compílalo antes con tsc o con un bundler.

Tipos de decoradores y sus firmas

Todo decorador estándar tiene la forma (value, context) => replacement | void. Qué es value, y qué puedes devolver, depende de lo que se decora:

Todos los objetos de contexto tienen kind, name y addInitializer. El contexto de un miembro de clase también tiene static, private y un objeto access para leer el miembro desde una instancia. Los decoradores también funcionan con miembros estáticos y #private.

Fábricas de decoradores

Para pasar opciones, escribe una función que devuelva un decorador y llámala en el sitio del @. Eso es una fábrica de decoradores:

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) llama primero a retry, y la función que devuelve es el decorador real. Los decoradores se apilan: en @a @b method(), b se aplica primero y a envuelve el resultado.

Decoradores de clase y addInitializer

Un decorador de clase recibe la propia clase. Puede devolver una subclase para sustituirla, o no devolver nada y simplemente registrarla en algún sitio. context.addInitializer registra código que se ejecuta en un momento concreto: en un decorador de clase, justo después de que la clase esté completamente definida; en un decorador de método, cuando se construye cada instancia.

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

El decorador de clase va encima de la clase (o después de export). Sin @bound, llamar a loose() lanzaría un error, porque this sería undefined.

Decoradores de campo y de accessor

Un decorador de campo no puede ver ni interceptar asignaciones posteriores: su value es undefined, y lo único que puede devolver es una función que transforma el valor inicial del campo. Para interceptar lecturas y escrituras, declara el campo con la palabra clave accessor, que lo convierte en un par getter y setter respaldado por un almacenamiento privado, y decora eso:

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
}

accessor forma parte de la misma propuesta. Genera un getter y un setter reales sobre un campo #private, y por eso p.price = -5 pasa por el set del decorador.

Estándar frente a los experimentalDecorators antiguos

Antes de TypeScript 5.0, los únicos decoradores de TypeScript eran una versión temprana de la propuesta, que se activaba con experimentalDecorators. Esa opción sigue existiendo, y cambia el compilador al modelo antiguo, con otras firmas y otra semántica:

Un decorador escrito para un modelo no pasa la comprobación de tipos en el otro. Aquí hay un decorador de estilo antiguo en un proyecto sin la opción:

// 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.

La solución es reescribirlo con la forma estándar (value, context), como en el primer ejemplo de esta página, o activar el modelo antiguo para todo el proyecto:

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

Angular, NestJS y TypeORM siguen poniendo experimentalDecorators en las configuraciones que generan sus herramientas y que piden sus documentaciones. NestJS y TypeORM también necesitan emitDecoratorMetadata, porque leen tipos en tiempo de ejecución: NestJS para inyectar los parámetros del constructor, TypeORM para asociar propiedades a columnas:

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

Si usas uno de esos frameworks, escribe los decoradores a la manera antigua y sigue su documentación. Para código nuevo sin un framework así, usa los decoradores estándar.

Cuándo usar decoradores

Los decoradores encajan con comportamiento transversal que de otro modo se repetiría en muchos métodos: logging, medición de tiempos, caché, reintentos, comprobaciones de acceso, validación y registro de clases en un contenedor o un router. También ocultan el flujo de control, porque quien lee tiene que buscar qué hace @retry antes de saber qué hace el método. Para uno o dos usos, una función de orden superior normal (const fetchData = retry(3, rawFetch)) es más sencilla y además funciona fuera de las clases.