JavaScript декораторы наконец-то в Stage 3

18 апреля 2022 года, после 5 лет доработки (первый коммит от 30 апреля 2017 года), proposal по декораторам наконец-то достиг 3 стадии, что означает что у него есть спецификация, тестовая имплементация и осталась только полировка на основе фидбека от разработчиков. Учитывая что это уже четвертая (!) итерация декораторов, их переход в стадию принятия это эпохальное событие для JS - не припомню ни одной другой фичи, которая прошла такой длинный и тернистый путь, с диаметрально разными подходами и аж двумя разными legacy-имплементациями, в Babel и TypeScript. Давайте же посмотрим на неё повнимательней.

Ссылки

https://github.com/tc39/proposal-decorators - репозиторий самого предложения, включая все предыдущие версии (в истории коммитов).

http://senocular.github.io/articles/js_history_of_decorators.html - история предложений, включая ссылки на все четыре основные версии.

https://javascriptdecorators.org/ - независимая имплементация

https://babeljs.io/docs/en/babel-plugin-proposal-decorators - плагин для Babel

Кстати, новая версия датируется в Babel как 2021-12 - потому что была представлена на саммите TC39 в декабре 2021 года.

Чем отличается от предыдущих версий

Во-первых, новые декораторы пока работают только с классами и их элементами. Впрочем, предложения по расширению той же логики на функции/параметры/объекты/переменные/аннотации/блоки/инициализаторы есть, но в текущую спеку не входят (что неудивительно, вряд ли кто-то хочет потратить еще 5 лет на достижение Stage 4).

Во-вторых, главное отличие новых декораторов: они работают только с сущностью которую декорируют (класс, поле класса, метод, геттер/сеттер и аксессор - новая сущность, о которой далее), а не с дескрипторами свойств и/или прототипами классов, как легаси подходы.

То есть они не способны добавить новые сущности в прототип/инстанс класса или хотя бы изменить их вид (с поля на геттер/сеттер, например), а могут только преобразовать ту сущность, которая описана в исходном коде - обернуть её в дополнительную логику или полностью заменить на другую, но того же вида.

Это было сделано в первую очередь под давлением разработчиков V8 основных движков, так как чрезмерная гибкость предыдущих декораторов крайне плохо подходила для оптимизации кода в рантайме - именно поэтому принятие декораторов так затянулось.

Демо и синтаксис применения декораторов

Ну и сразу полный пример со всеми возможными комбинациями синтаксиса:

//export должен быть перед декоратором
export default
//декоратор класса, может изменять сам класс
@defineElement("some-element")
class SomeElement extends HTMLElement {
  //декоратор поля - может заменить значение поля при инициализации класса
  //все дальнейшие чтения/записи он не отслеживает
  @inject('some-dep')
  dep

  //новый синтаксис - аксессор
  //по факту просто сахар для пары геттер/сеттер
  //похож на автоматически реализуемые свойства в C#
  //могут быть и приватными и статическими
  //декоратор может отслеживать чтение/запись
  @reactive accessor clicked = false

  //ну с методами и прочим все как обычно
  @logged
  someMethod() {
    return 42
  }

  //да, с приватными элементами тоже работает, как и со статическими
  //название декоратора может быть через точку
  @random.int(0, 42)
  #val

  @logged
  get val() {
    return this.#val
  }

  @logged
  set val(value) {
    this.#val = value
  }

  //апофеоз:
  //статический приватный аксессор c декоратором со сложным доступом
  @(someArr[3].someFunc('param'))
  static acсessor #name = 'some-element'
}

Текущие имплементации полифиллов этот пример полностью переварить еще не могут но, думаю, в скором времени это исправится.

Синтаксис для применения декораторов в целом не слишком отличается от привычного, есть только пара деталей:

1. Декоратор класса должен идти после export (если он есть) - это наверное главное отличие от статус-кво.

2. Для "обычного" применения декоратора можно использовать идентификатор, точку и вызов функции - @dotted.form.with('some-call')

3. Для "сложного" применения можно использовать синтаксис со скобками: @(complex[1])

Написание декораторов

Тут никаких особых сюрпризов - декоратор это обычная функция с таким типом:

context предоставляет, как ни странно, контекст, сведения о месте применения декоратора, где:

• kind - вид элемента, на который применяется декоратор

• name - название элемента

• access - объект который позволяет в произвольный момент времени получить/установить значение элемента, может пригодиться, например, для DI. Разрешен только для элементов класса, но не для самих классов (то есть get или set есть только когда kind != 'class')

• private и static - есть ли у элемента класса соответствующие модификаторы

• addInitializer позволяет выполнить код после того как сам класс (не инстанс!) или элемент класса полностью определен - например, в нем можно зарегистрировать класс в DI или забиндить метод. Не применим только для поля класса (то есть определен когда kind != 'field' - об этом далее)

Input и Output зависят от kind, но в целом Input - это значение элемента как оно написано в коде, а Output - значение на которое оно будет заменено в рантайме.

Важный нюанс - для полей класса (когда kind == 'field') Input всегда undefined, а Output может быть функцией вида (initValue: unknown) => any - эта функция вызывается при инициализации класса для вычисления начального значения поля. Именно из-за этого для поля класса не передается addInitializer - Output его заменяет.

Пример декоратора logged:

function logged(value, { kind, name }) {
  if (kind === "method") {
    return function (...args) {
      console.log(`starting ${name} with arguments ${args.join(", ")}`);
      const ret = value.call(this, ...args);
      console.log(`ending ${name}`);
      return ret;
    };
  }
  if (kind === "field") {
    return function (initialValue) {
      console.log(`initializing ${name} with value ${initialValue}`);
      return initialValue;
    };
  }
  if (kind === "class") {
    return class extends value {
      constructor(...args) {
        super(...args);
        console.log(`constructing an instance of ${name} with arguments ${args.join(", ")}`);
      }
    }
}

Ну или вот customElement с использованием addInitializer:

function customElement(name) {
  (value, { addInitializer }) => {
    addInitializer(function() {
      customElements.define(name, this);
    });
  }
}

@customElement('my-element')
class MyElement extends HTMLElement {
  static get observedAttributes() {
    return ['some', 'attrs'];
  }
}

Больше примеров (в том числе и с применением access для DI) смотрите на гитхабе.

Аксессоры

Ограничения новых декораторов в виде запрета на изменение вида элемента в целом логичны, но они убивают один крайне важный юзкейс декораторов - когда поле превращается в пару геттер/сеттер с дополнительной логикой вокруг. Это может быть, например, логгирование изменений поля для отладки, а может быть полноценная система реактивности, как в MobX, который, по сути, основан на этом хаке:

import {computed, observable, autorun} from 'mobx'

class Counter {
  	//вот здесь поле превращается в геттер/сеттер
    @observable num = 1
  	//а будет так
    @observable accessor num = 1
    
    @computed
    get double() {
        return this.num * 2
    }
}

const counter = new Counter()

//выведет 2
autorun(() => console.log(counter.double)) 

//когда изменяем num, изменится и double
counter.num = 2
//autorun выполняется снова и выводит 4

С новыми декораторами все такие поля придется помечать как accessor что, конечно, не слишком весело, но в целом терпимо и может отслеживаться, например, тайпскриптом. Под капотом работать это будет примерно так:

class C {
  accessor x = 1;
}

//Раскрывается в...

class C {
  #x = 1;

  get x() {
    return this.#x;
  }

  set x(val) {
    this.#x = val;
  }
}

Имплементации

Пока ждем реализации в основных тулзах - в первую очередь это, конечно, поддержка аксессоров как нового синтаксиса. Когда IDE, TypeScript и Babel (esbuild и т.д.) смогут их корректно обрабатывать, сделать полифиллы будет не так и сложно.

И я крайне надеюсь что TypeScript будет корректно обрабатывать типы декораторов при замене значений - сейчас декоратор никак не может повлиять на тип декорируемого значения.

Ссылки для отслеживания внедрения:

https://github.com/microsoft/TypeScript/issues/48885 - TypeScript - фича включена в планы на версию 4.8.

https://github.com/evanw/esbuild/issues/104 - esbuild - ждут реализации в TS/node/браузерах.

Ну а потом последует волна переезда на новую реализацию со стороны экосистемы. К счастью, декораторы в JS не так и распространены, и при этом новые декораторы могут быть реализованы в библиотеках вместе со старыми - их сигнатура отличается от Babel/TS декораторов.

Дождались, в общем.