Стандартные декораторы: что они делают на самом деле

Декоратор — это функция. Строка @logged над методом просит: когда класс будет объявлен, позови logged, передай ей сам метод и объект с описанием места — контекст, — а если она вернёт новую функцию, поставь её вместо метода. Декоратор ниже возвращает обёртку: она печатает каждый вызов и передаёт работу исходному методу. Прогноз: в каком порядке появятся строки, сколько раз напечатается «декоратор получил add» при двух экземплярах и что покажет последняя строка?

function logged(method: (...args: string[]) => string, context: ClassMethodDecoratorContext) {
  console.log(`декоратор получил ${String(context.name)}`);
  return function (this: unknown, ...args: string[]) {
    console.log(`вызов ${String(context.name)}(${args.join(", ")})`);
    return method.apply(this, args);
  };
}

console.log("перед классом");

class Notes {
  @logged
  add(title: string) {
    return `заметка «${title}»`;
  }
}

console.log("после класса");
const first = new Notes();
const second = new Notes();
console.log(first.add("хлеб"));
console.log(second.add("молоко"));
console.log(first.add === second.add);

Три детали в обёртке не случайны. Она объявлена через function, а не стрелкой: ей нужен свой this — объект, у которого вызвали метод, — и method.apply(this, args) передаёт его исходному методу, как в статье про call и apply. Стрелка взяла бы this самого декоратора, а его зовут без объекта: там undefined, и метод, которому нужен this, упал бы с TypeError. Запись this: unknown в скобках — не параметр, а подпись для компилятора, какой this ждёт функция; при выполнении она стирается, как любой тип. И String(context.name): имя члена класса бывает символом, а символ в шаблонную строку сам не превращается.

Всё, что должно происходить на каждом вызове, живёт в обёртке. Сам декоратор про вызовы ничего не знает: к тому времени он давно отработал.

Браузер декораторов не понимает — ни один движок их пока не выполняет, об этом последний раздел. Песочница отдаёт браузеру то, что компилятор выпустил из примера функцией transpileModule; ею в части про сборку переводили файлы с JSX и типами. Переведём класс с одним декоратором и напечатаем, что компилятор написал на его месте. Прогноз: где окажется вызов logged — в объявлении метода, в конструкторе или где-то ещё?

declare const ts: any;

const source = `
class Notes {
  @logged
  add(title) {
    return title;
  }
}`;

// помощники компилятор ставит в начало файла — печатаем только класс
const { outputText } = ts.transpileModule(source, {
  compilerOptions: { target: ts.ScriptTarget.ES2023 },
});
console.log(outputText.slice(outputText.indexOf("let Notes")).trim());

Декоратор зовут из блока static { … }. Это статический блок класса: код, который выполняется один раз, пока класс объявляется, — отсюда и строка «декоратор получил add» до первого new. __esDecorate — помощник из начала файла. Он берёт метод из прототипа, зовёт с ним декораторы из списка [logged], начиная с последнего, то есть ближайшего к методу, и возвращённую функцию ставит на место метода. Принять он готов только функцию или undefined: на строку или число помощник отвечает TypeError: Function expected, а компилятор ещё до запуска — ошибкой типа.

Четвёртый аргумент — тот самый контекст, записанный литералом: kind: "method", имя, static, private, объект access с функциями чтения и metadata. Объект для метаданных компилятор создаёт, только если в движке есть Symbol.metadata. В песочнице его нет, поле получает undefined, и что с этим делать, разберёт следующая статья. Метода addInitializer в литерале нет: помощник добавляет его в контекст сам, а функции, переданные в него, складывает в массив _instanceExtraInitializers. Этот массив выполняет конструктор — к нему вернёмся через два раздела.

Декоратор можно поставить на сам класс и на его метод, геттер, сеттер или поле, статические и приватные тоже: тип DecoratorContext объединяет контексты всех этих видов. Декоратор where ничего не меняет, только печатает, что узнал о месте. Прогноз: в каком порядке выйдут шесть строк и совпадёт ли он с порядком в тексте класса?

function where(value: unknown, context: DecoratorContext) {
  const parts: string[] = [context.kind, String(context.name)];
  if (context.kind !== "class") {
    parts.push(context.static ? "статический" : "экземпляра");
    parts.push(context.private ? "приватный" : "открытый");
  }
  console.log(parts.join(" · "));
}

@where
class Router {
  @where
  handle(path: string) {
    return this.#match(path);
  }

  @where
  #match(path: string) {
    return path === "/";
  }

  @where
  static create() {
    return new Router();
  }

  @where
  get size() {
    return 1;
  }

  @where
  prefix = "/api";
}

console.log(Router.create().handle("/"));

Порядок не текстовый. Первым вызван статический create, хотя в классе он третий. За ним методы и геттер экземпляра, потом поле, и последним — декоратор класса, хотя он стоит выше всех. Так зовут и tsc, и esbuild. Класс последним по делу: его декоратор получает класс, в котором члены уже украшены, и может заменить его целиком — другим классом. У поля первый аргумент undefined: пока класс объявляется, значения нет, оно появится в каждом экземпляре. У приватного метода имя — строка "#match", но это только подпись. Приватный член с решёткой по строковому ключу не достать, для этого в контексте есть access.get.

Главного в таблице нет: самого класса. Декоратор метода получает функцию и описание, но не класс, в котором она лежит, и не прототип. Это решение стандарта, а не упущение TypeScript.

У Nest декораторы пишутся со скобками и часто с аргументами. После @ может стоять любое выражение, которое даёт функцию, в том числе вызов. Get("/:id") — не декоратор, а фабрика: обычная функция, которая запоминает путь и возвращает настоящий декоратор. Обе фабрики ниже печатают, когда их вычислили, а декораторы, которые они вернули, — когда их позвали. Прогноз: в каком порядке выйдут шесть строк?

function Controller(prefix: string) {
  console.log(`вычислено Controller("${prefix}")`);
  return function (value: Function, context: ClassDecoratorContext) {
    console.log(`вызван Controller("${prefix}") для ${context.name}`);
  };
}

function Get(path: string) {
  console.log(`вычислено Get("${path}")`);
  return function (method: Function, context: ClassMethodDecoratorContext) {
    console.log(`вызван Get("${path}") для ${String(context.name)}`);
  };
}

@Controller("/notes")
class NotesController {
  @Get("/")
  list() {
    return ["хлеб", "молоко"];
  }

  @Get("/:id")
  byId(id: string) {
    return `заметка ${id}`;
  }
}

Сначала три «вычислено» — сверху вниз, как написано, начиная с класса. Потом декораторы методов и последним декоратор класса, в порядке из прошлого раздела. Это два разных шага. Выражения после @ вычисляются, пока читается объявление, а декораторы зовутся, когда методы уже определены. Для фабрики это значит, что аргументы — путь, роль, схема ввода — известны заранее, а пользоваться ими декоратор будет позже.

Теперь посмотрите, чего не хватает маршрутизатору. Get("/:id") знает путь и имя метода, byId, но не знает, что метод лежит в NotesController с префиксом /notes: класса в его контексте нет. Каркасу же нужна запись «GET /notes/:id → NotesController.byId», которую можно найти по классу, когда придёт запрос. Где декоратор метода оставляет такую запись и как её достать — вопрос следующей статьи.

Декоратор метода работает, когда экземпляров ещё нет, а иногда работа нужна именно в экземпляре. Классический случай — метод, положенный в переменную: const increment = counter.increment теряет this. Лечение из первой части — bind, но привязать метод можно только к конкретному объекту. Для этого у контекста есть addInitializer: переданная в него функция выполнится позже, и для члена экземпляра this в ней — создаваемый объект. Декоратор bound кладёт в экземпляр привязанную копию метода. Прогноз: сработает ли оторванный increment и в каком порядке окажутся ключи экземпляра?

function bound(method: Function, context: ClassMethodDecoratorContext) {
  context.addInitializer(function () {
    this[context.name] = method.bind(this);
  });
}

class Counter {
  count = 0;

  @bound
  increment() {
    this.count += 1;
    return this.count;
  }
}

const counter = new Counter();
const increment = counter.increment;
console.log(increment(), increment());
console.log(Object.keys(counter));

Оторванный метод работает: 1 2. Инициализатор записал в экземпляр собственное свойство increment — привязанную копию, — и оно заслонило метод прототипа. А порядок ключей показывает, когда это случилось: increment появился раньше count. Инициализаторы методов выполняются до полей. В выводе из второго раздела полей не было, и __runInitializers стоял в конструкторе. У Counter поле есть, и компилятор вписывает вызов прямо в его инициализатор, перед значением: count = (__runInitializers(this, _instanceExtraInitializers), 0). Прочитать поле в таком инициализаторе нельзя: его ещё нет.

Под примером компилятор возражает: «Объект имеет тип "Неизвестный"», в терминале это TS2571. Запуску это не мешает, но причина поучительна. Декоратор — отдельная функция, её можно поставить в любой класс, и ClassMethodDecoratorContext без аргументов типа не знает, в какой: this в инициализаторе описан как unknown. Параметр типа, как в обобщённой функции, тут не спасёт. С ClassMethodDecoratorContext<This> в инициализаторе окажется This, но внутри декоратора это по-прежнему какой угодно тип без индексной сигнатуры, и запись по произвольному имени компилятор не пропустит, только ошибка сменится на TS7053. Неизвестный объект нужно не индексировать, а отдать функции, которая принимает любой:

function bound(method: Function, context: ClassMethodDecoratorContext) {
  context.addInitializer(function () {
    Object.defineProperty(this, context.name, { value: method.bind(this) });
  });
}

class Timer {
  label = "чайник";

  @bound
  ring() {
    return `${this.label} вскипел`;
  }
}

const ring = new Timer().ring;
console.log(ring());

Ноль диагностик, хотя this остался неизвестным. Object.defineProperty описан так, что первым аргументом берёт что угодно, а вторым — любое имя свойства, строку или символ. Поэтому ему подходят и this типа unknown, и context.name, а привязанная копия встаёт в экземпляр так же, как в Counter.

Когда выполняется инициализатор, зависит от того, что украшено. Проверено и в песочнице, и под tsx:

В Nest тело запроса попадает в метод контроллера через декоратор параметра: create(@Body() dto). Попробуем то же в песочнице. Body() — фабрика, которая сообщает о своём вызове. Прогноз: напечатает ли пример «Body() вызван»?

function Body() {
  console.log("Body() вызван");
  return function (value: unknown, context: unknown) {};
}

class NotesController {
  create(@Body() dto: { title: string }) {
    return dto;
  }
}

console.log(new NotesController().create({ title: "хлеб" }));

Компилятор отвечает «Декораторы здесь недопустимы», в терминале это TS1206. Печатается только тело: Body() не вызвался ни разу. Из выпущенного кода декоратор исчез, от метода осталось create(dto) { return dto; }. Так же поступает tsc в терминале: ошибка, код выхода 2 — и файл, в котором декоратора нет. Ошибка компилятора, как вы помните, выпуск не отменяет, поэтому сборка, которая не смотрит на диагностики, получит работающий на вид код, где @Body молча ничего не делает.

Декораторов параметров в стандарте нет не по забывчивости. Модель стандартного декоратора — «получил значение, вернул замену того же вида». У параметра, пока объявляется класс, значения нет: аргумент появится только при вызове, а сам параметр в JavaScript не объект — его не передать в функцию и не заменить. Декоратору параметра остаётся одно: оставить каркасу пометку «в первый аргумент этого метода положи тело запроса». В старой системе декораторов TypeScript так и устроено: декоратор параметра получает прототип, имя метода и номер параметра и ничего не возвращает. Предложение стандарта параметры прямо не включает. Для них в комитете TC39 есть отдельное предложение, и с марта 2023 года оно стоит на первой стадии: комитет согласился изучать задачу, но решения ещё не выбрал.

Отсюда развилка всей части. Nest построен на старой системе: в tsconfig.json стартового проекта Nest 12 включены experimentalDecorators и emitDecoratorMetadata, а @Body и @Param в методах контроллера и @Inject в конструкторе — декораторы параметров. Наш каркас пишется на стандартных и обходится без них: метод контроллера получает всё о запросе одним объектом, а сервис объявляет свои зависимости списком — так их прочитает свой контейнер. Откуда в Nest берётся constructor(private repo: Repo) без единой пометки и чем такой проект собирать, разберёт статья «Почему Nest живёт на старых декораторах».

В песочнице декораторы переписывает компилятор TypeScript. Сервер части VI запускает Node, а встроенный запуск .ts типы только стирает. Ниже один и тот же файл — декоратор метода и декоратор класса — сначала под tsx, потом под node. Прогноз для второго запуска: какая строка напечатается первой?

function logged(method: (this: unknown, title: string) => string, context: ClassMethodDecoratorContext) {
  console.log(`декоратор получил ${String(context.name)}`);
  return function (this: unknown, title: string) {
    console.log(`вызов ${String(context.name)}("${title}")`);
    return method.call(this, title);
  };
}

function controller(value: Function, context: ClassDecoratorContext) {
  console.log(`декоратор получил класс ${context.name}`);
}

console.log("перед классом");

@controller
class Notes {
  @logged
  add(title: string) {
    return `заметка «${title}»`;
  }
}

console.log(new Notes().add("хлеб"));

перед классом
декоратор получил add
декоратор получил класс Notes
вызов add("хлеб")
заметка «хлеб»

function logged(method: (this: unknown, title: string) => string, context: ClassMethodDecoratorContext) {
  console.log(`декоратор получил ${String(context.name)}`);
  return function (this: unknown, title: string) {
    console.log(`вызов ${String(context.name)}("${title}")`);
    return method.call(this, title);
  };
}

function controller(value: Function, context: ClassDecoratorContext) {
  console.log(`декоратор получил класс ${context.name}`);
}

console.log("перед классом");

@controller
class Notes {
  @logged
  add(title: string) {
    return `заметка «${title}»`;
  }
}

console.log(new Notes().add("хлеб"));

<пример>/deco.ts:15
@controller
^

SyntaxError: Invalid or unexpected token
    at <внутренние кадры node>

Node.js v<версия>

tsx отработал как песочница: декоратор метода раньше декоратора класса, оба до первого вызова. Внутри tsx — esbuild, и он переводит декораторы в обычный JavaScript, как tsc. А node не напечатал даже «перед классом»: файл не разобрался. Сравните с отказом на enum. Там Node узнавал синтаксис TypeScript и называл его — ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX. Здесь SyntaxError без кода и без слова TypeScript, как на опечатке. Декоратор не относится к типам: это синтаксис самого JavaScript, и стирание оставляет его движку. А V8, движок Node, декораторов не знает.

И не он один. Стандартными эти декораторы называют по предложению в TC39. В марте 2022 года оно вышло на третью стадию — ту, где комитет считает решение готовым и рекомендует движкам его реализовать, а в марте 2023-го TypeScript 5.0 научился компилировать его без флагов. Но за четыре года ни один движок декораторы не выпустил: реализация в V8 остановлена, в SpiderMonkey она частичная, в JavaScriptCore её нет. 19 мая 2026 года комитет вернул предложение ступенью ниже, на стадию 2.7: замысел одобрен, но прежде чем снова звать движки, нужны полные тесты и исправленная спецификация. Туда же вернулось и соседнее предложение — о метаданных декораторов. Поэтому декоратор на практике всегда проходит через компилятор: в песочнице — tsc, под tsx — esbuild. Выполняет движок уже обычные функции.

Для части из этого следует правило запуска. Свой каркас этой главы стоит на стандартных декораторах: в песочнице его компилирует tsc, а когда он ответит на настоящем сокете, запускать его будет tsx, не node. У Nest своя система, а значит, и свой способ сборки.