Доброго времени суток, друзья!

Представляю вашему вниманию адаптированный перевод нового варианта предложения (сентябрь 2020 г.), касающегося использования декораторов в JavaScript, с небольшими пояснениями относительно характера происходящего.

Впервые данное предложение прозвучало около 5 лет назад и с тех пор претерпело несколько значительных изменений. В настоящее время оно (по-прежнему) находится на второй стадии рассмотрения.

Если вы раньше не слышали о декораторах или хотите освежить свои знания, рекомендую ознакомиться со следующими статьями:

• Декораторы в JavaScript
• Минимальное руководство по декораторам ECMAScript
• Декораторы JavaScript с нуля

Итак, что такое декоратор? Декоратор (decorator) — это функция, вызываемая на элементе класса (поле или методе) или на самом классе в процессе его определения, оборачивающая или заменяющая элемент (или класс) новым значением (возвращаемым декоратором).

Декорированное поле класса обрабатывается как обертка из геттера/сеттера, позволяющая извлекать/присваивать (изменять) значение этому полю.

Декораторы также могут аннотировать элемент класса метаданными (metadata). Метаданные — это коллекция простых свойств объекта, добавленных декораторами. Они доступны как набор вложенных объектов в свойстве [Symbol.metadata].

Синтаксис

Синтаксис декораторов, помимо префикса @ (@decoratorName), предполагает следующее:

• Выражения декораторов ограничены цепочкой переменных (можно использовать несколько декораторов), доступом к свойству с помощью ., но не c помощью [], и вызовом посредством ()
• Декорироваться могут не только определения классов, но и их элементы (поля и методы)
• Декораторы классов указываются после export и default

Для определения декораторов не существует каких-либо специальных правил; любая функция может быть использована в качестве такового.

Детали семантики

Декоратор оценивается в три этапа:

1. Выражение декоратора (все, что следует после @) оценивается вместе с вычисляемыми названиями свойств
2. Декоратор вызывается (как функция) в процессе определения класса, после оценки методов, но до объединения конструктора и прототипа
3. Декоратор применяется (изменяет конструктор и прототип) только один раз после вызова

1. Вычисление декораторов

Декораторы оцениваются как выражения вместе с вычисляемыми именами свойств. Это происходит слева направо и сверху вниз. Результат декоратора сохраняется в своего рода локальную переменную, которая вызывается (используется) после завершения определения класса.

2. Вызов декораторов

Декоратор вызывается с двумя аргументами: оборачиваемым элементом и, опционально, объектом контекста.

Оборачиваемый элемент: первый параметр

Первый аргумент, который оборачивается декоратором, это то, что мы декорируем (извиняюсь за тавтологию):

• Если речь идет о простом методе, методе инициализации, геттере или сеттере: соответствующая функция
• Если о классе: сам класс
• Если о поле: объект с двумя свойствами:
  
  
  • get: функция без параметров, которая вызывается с получателем (receiver), представляющим собой объект, возвращающий содержащееся в нем значение
  • set: функция, принимающая один параметр (новое значение), которая вызывается с получателем, представляющим собой переданный объект, и возвращает undefined

Объект контекста: второй параметр

Объект контекста — объект, передаваемый декоратору в качестве второго аргумента — содержит следующие свойства:

• kind: имеет одно из следующих значений:
  
  
  • «class»
  • «method»
  • «init-method»
  • «getter»
  • «setter»
  • «field»
• name:
  
  
  • публичное поле или метод: name — строковый или символьный ключ свойства
  • частное поле или метод: отсутствует
  • класс: отсутствует
• isStatic:
  
  
  • статическое поле или метод: true
  • поле или метод экземпляра: false
  • класс: отсутствует

«Target» (конструктор или прототип) не передается декораторам полей или методов по той причине, что она («цель») еще не сконструирована в момент вызова декоратора.

Возвращаемое значение

Возвращаемое значение зависит от типа декоратора:

• класс: новый класс
• метод, геттер или сеттер: новая функция
• поле: объект с тремя свойствами:
  
  
  • get
  • set
  • initialize: функция, вызываемая с тем же аргументом, что и set, возвращающая значение, которое используется для инициализации переменной. Данная функция вызывается, когда настройка низлежащего (внутреннего) хранилища (underlying storage) зависит от инициализатора поля или определения метода
• метод init: объект с двумя свойствами:
  
  
  • method: функция, заменяющая метод
  • initialize: функция без аргументов, возвращаемое значение которой игнорируется, и которая вызывается с вновь созданным объектом в качестве получателя

3. Применение декораторов

Декораторы применяются после их вызова. Промежуточные этапы алгоритма работы декораторов не могут быть зафиксированы — вновь созданный класс является недоступным до тех пор, пока не будут применены все декораторы методов и полей экземпляров.

Декораторы классов вызываются после применения декораторов полей и методов.

Наконец, применяются декораторы статических полей.

Семантика декраторов полей

Декоратор поля класса представляет собой пару геттер/сеттер — упаковку для частного поля. Поэтому код:

function id(v) { return v }

class C {
  @id x = y
}

имеет такую семантику:

class C {
  // префикс # указывает на приватность переменной-поля
  #x = y
  get x() { return this.#x }
  set x(v) { this.#x = v }
}

Декораторы полей ведут себя подобно частным полям. Следующий код выбросит исключение TypeError из-за того, что мы пытаемся получить доступ к «y» до ее добавления в экземпляр:

class C {
  @id x = this.y
  @id y
}
new C // TypeError

Пара геттер/сеттер — это обычные методы объекта, которые являются неперечислимыми (неперечисляемыми, если угодно), как и другие методы. Содержащиеся в ней приватные поля добавляются один за другим, вместе с инициализаторами, как обычные частные поля.

Цели проектирования

• Должно быть одинаково легко как использовать встроенные декораторы, так и писать собственные
• Декораторы должны применяться только к декорируемым объектам без побочных эффектов

Случаи применения

• Хранение метаданных в классах и методах
• Преобразование поля в аксессор
• Оборачивание метода или класса (такое использование декораторов чем-то напоминает проксирование объектов)

Примеры

Примеры реализации и использования декораторов.

@logged

Декоратор @logged выводит в консоль сообщения о начале и завершении выполнения метода. Существуют другие популярные декораторы, оборачивающие функции, например: @deprecated, debounce, @memoize и т.д.

Использование:

// расширение .mjs указывает на файл-модуль
import { logged } from './logged.mjs'

class C {
  @logged
  m(arg) {
    this.#x = arg
  }

  @logged
  set #x(value) { }
}

new C().m(1)
// запуск m с аргументами 1
// запуск set #x с аргументами 1
// завершение set #x
// завершение m

@logged может быть реализован в JavaScript в качестве декоратора. Декоратор — это функция, которая вызывается с аргументом, содержащим декорируемый элемент. Таким элементом может быть метод, геттер или сеттер. Декораторы могут вызываться со вторым аргументом — контекстом, однако, в данном случае он нам не нужен.

Значение, возвращаемое декоратором, заменяет оборачиваемый элемент. Для методов, геттеров и сеттеров, возвращаемое значение — это заменяющая их функция.

// logged.mjs

export function logged(f) {
  // получаем название функции
  const name = f.name
  function wrapped(...args) {
    // сообщаем о запуске функции
    console.log(`запуск ${name} с аргументами ${args.join(', ')}`)
    // получаем результат выполнения функции
    const ret = f.call(this, ...args)
    // сообщаем о завершении функции
    console.log(`завершение ${name}`)
    // возвращаем результат
    return ret
  }
  // Object.defineProperty() определяет новое или изменяет существующее свойство объекта
  // https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty
  Object.defineProperty(wrapped, 'name', { value: name, configurable: true })
  // возвращаем обертку
  return wrapped
}

Результат транспиляции приведенного примера может выглядеть следующим образом:

let x_setter

class C {
  m(arg) {
    this.#x = arg
  }

  static #x_setter(value) { }
  // предложение - статические блоки инициализации класса (class static initialization blocks)
  // https://github.com/tc39/proposal-class-static-block
  static { x_setter = C.#x_setter }
  set #x(value) { return x_setter.call(this, value) }
}

C.prototype.m = logged(C.prototype.m, { kind: "method", name: "m", isStatic: false })
x_setter = logged(x_setter, {kind: "setter", isStatic: false})

Обратите внимание, что геттеры и сеттеры декорируются раздельно. Аксессоры (вычисляемые свойства) не объединяются, как в предыдущих предложениях.

@defineElement

HTML Custom Elements (пользовательские элементы, часть веб-компонентов) позволяют создавать свои собственные HTML-элементы. Регистрация элементов осуществляется с помощью customElements.define. Вот как можно выполнить регистрацию элемента с помощью декораторов:

import { defineElement } from './defineElement.js'

@defineElement('my-class')
class MyClass extends HTMLElement { }

Классы могут декорироваться наравне с методами и аксессорами.

// defineElement.mjs
export function defineElement(name, options) {
  return klass => {
    customElements.define(name, klass, options); return klass
  }
}

Декоратор принимает аргументы, которые сам же использует, поэтому он реализуется как функция, возвращающая другую функцию. Вы можете думать об этом как о «фабрике декораторов»: после передачи аргументов, вы получаете другой декоратор.

Декораторы, добавляющие метаданные

Декораторы могут снабжать элементы класса метаданными путем добавления свойства metadata к передаваемому им объекту-контексту. Все объекты, содержащие метаданные, объединяются с помощью Object.assign и помещаются в свойство класса [Symbol.metadata]. Например:

// добавление метаданных к классу
@annotate({x: 'y'}) @annotate({v: 'w'}) class C {
  // добавление метаданных к методу
  @annotate({a: 'b'}) method() { }
  // добавление метаданных к полю
  @annotate({c: 'd'}) field
}

C[Symbol.metadata].class.x                    // 'y'
C[Symbol.metadata].class.v                    // 'w'
// методы, предоставляемые классом, являются распределенными или совместными,
C[Symbol.metadata].prototype.methods.method.a // 'b'
// а поля собственными
C[Symbol.metadata].instance.fields.field.c    // 'd'

Обратите внимание, что формат представления объекта с аннотацией является примерным и впоследствии может быть уточнен. Основная задача примера — показать, что аннотация — это всего лишь объект, не требующий использования библиотек для чтения или записи данных в него, он создается системой автоматически.

Рассматриваемый декоратор может быть реализован так:

function annotate(metadata) {
  return (_, context) => {
    context.metadata = metadata
    return _
  }
}

При каждом вызове декоратора ему передается новый контекст, затем свойство metadata, при условии, что оно не равняется undefined, включается в [Symbol.metadata].

Обратите внимание, что метаданные, добавляемые к самому классу, а не к его методу, недоступны для декораторов, объявленных в классе. Добавление метаданных в класс происходит в конструкторе после вызова всех «внутренних» декораторов во избежание потери данных.

@tracked

Декоратор @tracked наблюдает за полем класса и вызывает метод render при вызове сеттера. Данный паттерн и похожие на него паттерны широко используются различными фреймворками для решения проблемы повторного рендеринга.

Семантика декорирумых полей предполагает обертку из геттера/сеттера вокруг некоторого приватного хранилища данных. @tracked может обернуть пару геттер/сеттер для реализации логики повторного рендеринга:

import {tracked} from './tracked.mjs'

class Element {
  @tracked counter = 0

  increment() { this.counter++ }

  render() { console.log(counter) }
}

const e = new Element()
e.increment() // в консоль выводится 1
e.increment() // 2

При декорировании поля, «обернутое» значение представляет собой объект с двумя свойствами: функциями get и set, предназначенными для управления внутренним хранилищем. Они сконструированы таким образом, чтобы автоматически привязываться к экземпляру (с помощью call()).

// tracked.mjs
export function tracked({ get, set }) {
  return {
    get,
    set(value) {
      if (get.call(this) !== value) {
        set.call(this, value)
        this.render()
      }
    }
  }
}

Ограниченный доступ к приватным полям и методам

Порой некоторому коду, находящемуся за пределами класса, может потребоваться доступ к приватным полям или методам. Например, для обеспечения взаимодействия между двумя классами или в целях тестирования кода внутри класса.

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

import { PrivateKey } from './private-key.mjs'

let key = new PrivateKey()

export class Box {
  @key.show #contents
}

export function setBox(box, contents) {
  return key.set(box, contents)
}

export function getBox(box) {
  return key.get(box)
}

Обратите внимание, что приведенный пример — это своего рода хак, который легче реализовать с помощью конструкций наподобие ссылок на приватные имена с помощью private.name или расширения области видимости приватных имен с помощью private/with. Однако он показывает, как данное предложение органично расширяет существующий функционал.

// private-key.mjs
export class PrivateKey {
#get
#set

show({ get, set }) {
  assert(this.#get === undefined && this.#set === undefined)
  this.#get = get
  this.#set = set
  return { get, set }
}
get(obj) {
  return this.#get.call(obj)
}
set(obj, value) {
  return this.#set.call(obj, value)
}
}

@deprecated

Декоратор @deprecated выводит в консоль предупреждение об использовании устаревших полей, методов или аксессоров. Пример использования:

import { deprecated } from './deprecated.mjs'

export class MyClass {
  @deprecated field

  @deprecated method() { }

  otherMethod() { }
}

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

function wrapDeprecated(fn) {
  let name = fn.name
  function method(...args) {
    console.warn(`код ${name} признан устаревшим`)
    return fn.call(this, ...args)
  }
  Object.defineProperty(method, 'name', { value: name, configurable: true })
  return method
}

export function deprecated(element, { kind }) {
  switch (kind) {
    case 'method':
    case 'getter':
    case 'setter':
      return wrapDeprecated(element)
    case 'field': {
      let { get, set } = element
      return { get: wrapDeprecated(get), set: wrapDeprecated(set) }
    }
    default:
      // включая 'class'
      throw new Error(`${kind} является недопустимой целью @deprecated`)
  }
}

Декораторы методов, требующие предварительной настройки

Некоторые декораторы методов основаны на выполнении кода при создании экземпляра класса. Например:

• Декоратор @on('event') для методов класса расширяет HTMLElement, который регистрирует этот метод как обработчик события в конструкторе
• Декоратор @bound является эквивалентом this.method = this.method.bind(this) в конструкторе

Существуют разные способы использования названных декораторов.

Вариант 1: конструкторы и метаданные

Эти декораторы представляют собой комбинацию метаданных и примеси (mixin), содержащей операции по инициализации, которые используются в конструкторе.

@on с примесью

class MyClass extends WithActions(HTMLElement) {
  @on('click') clickHandler() {}
}

Указанный декоратор может быть определен следующим образом:

// у нас может быть несколько обработчиков с одинаковыми именами,
// поэтому используется Symbol
// https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Symbol
const handler = Symbol('handler')
function on(eventName) {
  return (method, context) => {
    context.metadata = { [handler]: eventName }
    return method
  }
}

class MetadataLookupCache {
  // в качестве ключей используются объекты,
  // во избежание утечек памяти используется WeakMap
  // https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
  #map = new WeakMap()
  #name
  constructor(name) { this.#name = name }
  get(newTarget) {
    let data = this.#map.get(newTarget)
    if (data === undefined) {
      data = []
      let klass = newTarget
      while (klass !== null && !(this.#name in klass)) {
        for (const [name, { [this.#name]: eventName }] of Object.entries(klass[Symbol.metadata].instance.methods)) {
          if (eventName !== undefined) {
            data.push({ name, eventName })
          }
        }
        klass = klass.__proto__
      }
      this.#map.set(newTarget, data)
    }
    return data
  }
}

const handlersMap = new MetadataLookupCache(handler)

function WithActions(superClass) {
  return class C extends superClass {
    constructor(...args) {
      super(...args)
      const handlers = handlersMap.get(new.target, C)
      for (const { name, eventName } of handlers) {
        this.addEventListener(eventName, this[name].bind(this))
      }
    }
  }
}

@bound c примесью

@bound может быть использован следующим образом:

class C extends WithBoundMethod(Object) {
  #x = 1
  @bound method() { return this.#x }
}

const c = new C()
const m = c.method
m() // 1, а не TypeError

Реализация декоратора может выглядеть так:

const boundName = Symbol('boundName')
function bound(method, context) {
  context.metadata = { [boundName]: true }
  return method
}

const boundMap = new MetadataLookupCache(boundName)

function WithBoundMethods(superClass) {
  return class C extends superClass {
    constructor(...args) {
      super(...args)
      const names = boundMap.get(new.target, C)
      for (const { name } of names) {
        this[name] = this[name].bind(this)
      }
    }
  }
}

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

Вариант 2: декораторы метода init

Декоратор init: предназначен для случаев, когда требуется выполнить операцию по инициализации, но невозможно вызвать суперкласс/примесь. Он позволяет добавлять такие операции при выполнении конструктора.

@on c init

Использование:

class MyElement extends HTMLElement {
  @init: on('click') clickHandler()
}

Декоратор init: вызывается также, как декораторы методов, но возвращает пару { method, initialize }, где initialize вызывается с новым экземпляром в качестве значения this, без аргументов, и ничего не возвращает.

function on(eventName) {
  return (method, context) => {
    assert(context.kind === 'init-method')
    return { method, initialize() { this.addEventListener(eventName, method) } }
  }
}

@bound с init

init: также может использоваться для построения декоратора init: bound:

class C {
  #x = 1
  @init: bound method() { return this.#x }
}

const c = new C()
const m = c.method
m() // 1, а не TypeError

Декоратор @bound может быть реализован следующим образом:

function bound(method, { kind, name }) {
  assert(kind === 'init-method')
  return { method, initialize() { this[name] = this[name].bind(this) } }
}

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

На этом позвольте откланяться. Благодарю за внимание.