Декораторы в TypeScript: метода, класса, поля и accessor

Декоратор это функция, которую вы прикрепляете к классу или члену класса через @name. Она получает исходный метод (или класс, или поле) и объект контекста, который его описывает, и может вернуть замену. TypeScript поддерживает стандартные декораторы без флагов компилятора.

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 выполняется один раз, при определении класса, и заменяет add обёрткой, которую возвращает. Каждый вызов проходит через обёртку. Обобщённые параметры сохраняют типы this, аргументов и возвращаемого значения метода, так что add по-прежнему принимает два числа и возвращает число.

Как компилируются декораторы

Стандартные декораторы происходят из предложения TC39 для JavaScript, и TypeScript реализует их с версии TypeScript 5.0. Предложение ещё не входит в стандарт JavaScript, а Node 24 не разбирает синтаксис @, поэтому при цели ES2022 (как на этих страницах) компилятор переписывает каждый декорированный класс в обычный JavaScript, который вызывает вспомогательные функции (__esDecorate и __runInitializers, выводятся в начале файла). Результат работает везде, где работает ES2022.

Одно следствие: файл с декораторами нельзя запустить через встроенное удаление типов в Node (node file.ts), которое только убирает типы и оставляет @ на месте. Node останавливается с SyntaxError: Invalid or unexpected token. Сначала скомпилируйте файл через tsc или бандлер.

Виды декораторов и их сигнатуры

У каждого стандартного декоратора форма (value, context) => replacement | void. Что такое value и что можно вернуть, зависит от того, что декорируется:

У каждого объекта контекста есть kind, name и addInitializer. У контекста члена класса также есть static, private и объект access для чтения члена из экземпляра. Декораторы работают и со статическими членами, и с членами #private.

Фабрики декораторов

Чтобы передать параметры, напишите функцию, которая возвращает декоратор, и вызовите её в месте @. Это фабрика декораторов:

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) сначала вызывает retry, а функция, которую она возвращает, и есть настоящий декоратор. Несколько декораторов складываются: в @a @b method() сначала применяется b, а a оборачивает результат.

Декораторы класса и addInitializer

Декоратор класса получает сам класс. Он может вернуть подкласс на замену или ничего не возвращать, а просто где-то его зарегистрировать. context.addInitializer регистрирует код, который выполнится в определённый момент: для декоратора класса сразу после полного определения класса, для декоратора метода при создании каждого экземпляра.

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

Декоратор класса ставится над классом (или после export). Без @bound вызов loose() выбросил бы ошибку, потому что this был бы undefined.

Декораторы полей и accessor

Декоратор поля не видит и не может перехватить последующие присваивания: его value равно undefined, и вернуть он может только функцию, которая преобразует начальное значение поля. Чтобы перехватывать чтение и запись, объявите поле с ключевым словом accessor, которое превращает его в пару геттера и сеттера с приватным хранилищем, и декорируйте его:

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 входит в то же предложение. Он генерирует настоящие геттер и сеттер поверх поля #private, поэтому p.price = -5 проходит через set декоратора.

Стандартные декораторы и устаревшие experimentalDecorators

До TypeScript 5.0 единственными декораторами в TypeScript была ранняя версия предложения, включаемая через experimentalDecorators. Этот флаг всё ещё существует и переключает компилятор на устаревшую модель с другими сигнатурами и семантикой:

Декоратор, написанный для одной модели, не проходит проверку типов в другой. Вот декоратор в устаревшем стиле в проекте без флага:

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

Исправить можно двумя способами: переписать его в стандартной форме (value, context), как в первом примере на этой странице, или включить устаревшую модель для всего проекта:

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

Angular, NestJS и TypeORM по-прежнему задают experimentalDecorators в конфигурациях, которые генерируют их инструменты, и требуют его в документации. NestJS и TypeORM нужен ещё и emitDecoratorMetadata, потому что они читают типы во время выполнения: NestJS для внедрения параметров конструктора, TypeORM для сопоставления свойств с колонками:

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

Если вы используете один из этих фреймворков, пишите декораторы по-старому и следуйте его документации. Для нового кода без такого фреймворка используйте стандартные декораторы.

Когда использовать декораторы

Декораторы подходят для сквозного поведения, которое иначе повторялось бы во многих методах: логирование, замер времени, кеширование, повторные попытки, проверка доступа, валидация и регистрация классов в контейнере или маршрутизаторе. При этом они скрывают поток управления: читателю нужно посмотреть, что делает @retry, прежде чем понять, что делает метод. Для одного-двух применений обычная функция высшего порядка (const fetchData = retry(3, rawFetch)) проще и работает и вне классов.