Темная сторона TypeScript — @декораторы на примерах

В TypeScript термин "поле" обычно не используется, и поля называют также свойствами (property). Это создает большую путаницу, т.к. разница есть. Если мы объявляем свойство с методами доступа get/set, то в объявлении класса появляется вызов Object.defineProperty и в декораторе доступен дескриптор, а если объявляем просто поле (в терминах C# и Java) — то не появляется ничего, и, соответственно, дескриптор не передается в декоратор. Это определяет сигнатуру декораторов, поэтому я использую термин "поле", чтобы отличать их от свойств с методами доступа.

{
    "compilerOptions": {
        "target": "ES5",
        "experimentalDecorators": true
    }
}

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

function safe(target: Object, propertyKey: string, descriptor: TypedPropertyDescriptor<any>): TypedPropertyDescriptor<any> {
  // Запоминаем исходную функцию
  var originalMethod = descriptor.value;
  // Подменяем ее на нашу обертку
  descriptor.value = function SafeWrapper () {
    try {
      // Вызываем исходный метод
      originalMethod.apply(this, arguments);
    } catch(ex) {
      // Просто выводим в консоль, исполнение кода будет продолжено
      console.error(ex);
    }
  };
  // Обновляем дескриптор
  return descriptor;
}

function OnChange<ClassT, T>(callback: (ClassT, T) => void): any {
    return (target: Object, propertyKey: string | symbol) => {
      // Необходимо задействовать существующий дескриптор, если он есть.
      // Это позволит объявять несколько декораторов на одном свойстве.
      var descriptor = Object.getOwnPropertyDescriptor(target, propertyKey) 
        || {configurable: true, enumerable: true};
      // Подменяем или объявляем get и set
      var value: T;
      var originalGet = descriptor.get || (() => value);
      var originalSet = descriptor.set || (val => value = val);
      descriptor.get = originalGet;
      descriptor.set = function(newVal: T) {
        // Внимание, если определяем set через function, 
        // то this - текущий экземпляр класса,
        // если через лямбду, то this - Window!!!
        var currentVal = originalGet.call(this);
        if (newVal != currentVal) {
          // Вызываем статический метод callback с двумя параметрами
          callback.call(target.constructor, this, newVal);
        }
        originalSet.call(this, newVal);
      };
      // Объявляем новое свойство, либо обновляем дескриптор
      Object.defineProperty(target, propertyKey, descriptor);
      return descriptor;
    }
}

Обратите внимание, мы вызываем defineProperty и возвращаем дескриптор из декоратора. Это связано с багом в reflect-metadata, из-за которого для декоратора полей возвращаемое значение игнорируется.

// Объявляем декоратор
function Inject(target: Object, propKey: string): any {
    // Получаем конструктор типа свойства 
    // (в примере ниже это будет конструктор класса ILogService)
    var propType = Reflect.getMetadata("design:type", target, propKey);
    // Переопределяем декорируемое свойство
    var descriptor = {
        get: function () {
          // this - текущий объект класса
          var serviceLocator = this.serviceLocator || globalSericeLocator;
          return serviceLocator.getService(propType);  

        }
    };
    Object.defineProperty(target, propKey, descriptor);
    return descriptor;
}

Обратите внимание, мы вызываем defineProperty и возвращаем дескриптор из декоратора. Это связано с багом в reflect-metadata, из-за которого для декоратора полей возвращаемое значение игнорируется.

class ServiceLocator {
  services: [{interfaceType: Function, instance: Object }] = [] as any;

  registerService(interfaceType: Function, instance: Object) {
    var record = this.services.find(x => x.interfaceType == interfaceType);
    if (!record) {
      record = { interfaceType: interfaceType, instance: instance};
      this.services.push(record);
    } else {
      record.instance = instance;
    }
  }
  getService(interfaceType: Function) {
    return this.services.find(x => x.interfaceType == interfaceType).instance;
  }
}

// Уникальный ключ для наших метаданных
const JsonNameMetadataKey = "Habrahabr_PFight77_JsonName";
// Декоратор
function JsonName(name: string) {
    return (target: Object, propertyKey: string) => {
        // Сохраняем в метаданных переднный name
        Reflect.defineMetadata(JsonNameMetadataKey, name, target, propertyKey);
    }
}
// Функция, работающая в паре с декоратором
function serialize(model: Object): string {
  var result = {};
  var target = Object.getPrototypeOf(model);
  for(var prop in model) {
    // Загружаем сохраненное декоратором значение
    var jsonName = Reflect.getMetadata(JsonNameMetadataKey, target, prop) || prop;    
    result[jsonName] = model[prop];
  }
  return JSON.stringify(result);
}

@ServerModelField — конвертер серверных моделей на декораторах

Постановка задачи следующая. С сервера к нам прилетают некоторые JSON-данные примерно такого вида (похожий JSON шлет один BaaS сервис):

{
    "username":"PFight77",
    "email":"test@gmail.com",
    "doc": {
        "info":"The author of the article"
    }
}

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

class UserAdditionalInfo {
    @ServerModelField("info")
    public mRole: string;
}
class UserInfo {
    @ServerModelField("username")
    private mUserName: string;
    @ServerModelField("email")
    private mEmail: string;
    @ServerModelField("doc")
    private mAdditionalInfo: UserAdditionalInfo;

    public get DisplayName() {
        return mUserName + " " + mAdditionalInfo.mRole;
    }
    public get ID() {
        return mEmail;
    }    
    public static parse(jsonData: string): UserInfo {
        return convertFromServer(JSON.parse(jsonData), UserInfo);
    }
    public serialize(): string {
        var serverData = convertToServer(this);
        return JSON.stringify(serverData);
    }
}

Разберем, как это реализовано.

Во-первых, нам необходимо определить декоратор поля ServerModelField, который будет принимать строковый параметр и сохранять его в метаданных. Кроме того, для разбора JSON нам еще нужно знать, какие поля с нашим декоратором есть в классе вообще. Для этого объявим еще один экземпляр метаданных, общий для всех полей класса, в котором и сохраним имена всех декорированных членов. Здесь мы уже будем не только сохранять метаданные через Relect.defineMetadata, но и получать через Reflect.getMetadata.

// Объявляем уникальные ключи, по которым будем идентифицировать наши метаданные
const ServerNameMetadataKey = "Habrahabr_PFight77_ServerName";
const AvailableFieldsMetadataKey = "Habrahabr_PFight77_AvailableFields";
// Объявляем декоратор
export function ServerModelField(name?: string) {
    return (target: Object, propertyKey: string) => {
        // Сохраняем в метаданных переданный name, либо название самого свойства, если параметр не задан
        Reflect.defineMetadata(ServerNameMetadataKey, name || propertyKey, target, propertyKey);
        // Проверяем, не определены ли уже availableFields другим экземпляром декоратора
        var availableFields = Reflect.getMetadata(AvailableFieldsMetadataKey, target);
        if (!availableFields) {
            // Ok, мы первые, значит создаем новый массив
            availableFields = [];
            // Не передаем 4-й параметр(propertyKey) в defineMetadata, 
            // т.к. метаданные общие для всех полей
            Reflect.defineMetadata(AvailableFieldsMetadataKey, availableFields, target);            
        }
        // Регистрируем текущее поле в метаданных
        availableFields.push(propertyKey);
    }
}

Ну и осталось написать функцию convertFromServer. В ней почти нет ничего особенного, она просто вызывает Reflect.getMetadata и использует полученные метаданные для разбора JSON. Одна особенность — эта функция должна создать экземпляр UserInfo через new, поэтому мы передаем ей помимо JSON-данных еще и класс: convertFromServer(JSON.parse(data), UserInfo). Чтобы понять, как это работает, посмотрите спойлер ниже.

class MyClass {
}
// Объявляем переменную типа "конструктор класса без параметров"
var myType: { new(): any; }; 
// Присваиваем переменной наш класс
myType = MyClass; 
// Эквивалентно new MyClass()
var obj = new myType();

Вторая особенность — это использование данных о типе поля, генерируемых благодаря настройке "emitDecoratorMetadata": true в tsconfig.json. Прием заключается в вызове Reflect.getMetadata с ключом "design:type", который возвращает конструктор соответствующего типа. Например, вызов Reflect.getMetadata("design:type", target, "mAdditionalInfo") вернет конструктор UserAdditionalInfo. Мы будем использовать эту информацию для того, чтобы правильно обрабатывать поля пользовательских типов. Например, класс UserAdditionalInfo также использует декоратор @ServerModelField, поэтому мы должны также использовать эти метаданные для анализа JSON.

Третья особенность заключается в получении соответствующего target, откуда мы будем брать метаданные. Мы используем декораторы полей, поэтому метаданные нужно брать из прототипа класса. Для декораторов статических членов нужно использовать конструктор класса. Получить прототип можно, вызвав Object.getPrototypeOf или же обратившись к свойству prototype конструктора.

Все остальные комментарии в коде:

export function convertFromServer<T>(serverObj: Object, type: { new(): T ;} ): T {
    // Создаем объект, с помощью конструктора, переданного в параметре type
    var clientObj: T = new type();
    // Получаем контейнер с метаданными
    var target = Object.getPrototypeOf(clientObj);
    // Получаем из метаданных, какие декорированные свойства есть в классе
    var availableNames = Reflect.getMetadata(AvailableFieldsMetadataKey, target) as [string];
    if (availableNames) {
        // Обрабатываем каждое свойство
        availableNames.forEach(propName => {
            // Получаем из метаданных имя свойства в JSON
            var serverName = Reflect.getMetadata(ServerNameMetadataKey, target, propName);
            if (serverName) {
                // Получаем значение, переданное сервером
                var serverVal = serverObj[serverName];
                if (serverVal) {
                    var clientVal = null;
                    // Проверяем, используются ли в классе свойства декораторы @ServerModelField
                    // Получаем конструктор класса
                    var propType = Reflect.getMetadata("design:type", target, propName);
                    // Смотрим, есть ли в метаданных класса информация о свойствах
                    var propTypeServerFields =  Reflect.getMetadata(AvailableFieldsMetadataKey, propType.prototype) as [string];
                    if (propTypeServerFields) {
                        // Да, класс использует наш декоратор, обрабатываем свойство рекурсивно
                        clientVal = convertFromServer(serverVal, propType);
                    } else {
                        // Нет, просто копируем значение
                        clientVal = serverVal;
                    }
                    // Записываем результат в конечный объект
                    clientObj[propName] = clientVal;
                }
            }
        });
    } else {
        errorNoPropertiesFound(getTypeName(type));
    }

    return clientObj;
}
function errorNoPropertiesFound<T>(typeName: string) {
    throw new Error("There is no @ServerModelField directives in type '" + typeName + "'. Nothing to convert.");
}

function getTypeName<T>(type: { new(): T ;}) {
     return parseTypeName(type.toString());
}

function parseTypeName(ctorStr: string) {
     var matches = ctorStr.match(/w+/g);
     if (matches.length > 1) {
         return matches[1];
     } else {
         return "<can not determine type name>";

    }
}

Аналогичный вид имеет обратная функция — convertToServer.

function convertToServer<T>(clientObj: T): Object {
    var serverObj = {};

    var target = Object.getPrototypeOf(clientObj);
    var availableNames = Reflect.getMetadata(AvailableFieldsMetadataKey, target) as [string];
    availableNames.forEach(propName=> {        
        var serverName = Reflect.getMetadata(ServerNameMetadataKey, target, propName);
        if (serverName) {
            var clientVal = clientObj[propName];
            if (clientVal) {
                var serverVal = null;
                var propType = Reflect.getMetadata("design:type", target, propName);
                var propTypeServerFields =  Reflect.getMetadata(AvailableFieldsMetadataKey, propType.prototype) as [string];
                if (clientVal && propTypeServerFields) {
                    serverVal = convertToServer(clientVal);
                } else {
                    serverVal = clientVal;
                }
                serverObj[serverName] = serverVal;
            }
        }
    });

    if (!availableNames) {
        errorNoPropertiesFound(parseTypeName(clientObj.constructor.toString()));
    }

    return serverObj;
}

var ControllerNameMetadataKey = "Habr_PFight77_ControllerName";
// Первый декоратор. 
// К сожалению, нет надежного способа узнать 
// имя класса (устойчивого к минификации),
// поэтому имя класса придется передавать вручную.
function Controller(name: string) {
    return (target: Function) {
    Reflect.defineMetadata(ControllerNameMetadataKey, name, target.prototype);
  };
}
// Второй декоратор, применяемый к методам
function Action(target: Object, propertyKey: string, descriptor: TypedPropertyDescriptor<any>): TypedPropertyDescriptor<any> {
  // Запоминаем исходную функцию
  var originalMethod = descriptor.value;
  // Подменяем ее на нашу обертку
  descriptor.value = function ActionWrapper () {
        // Получаем url, сохраненное декоратором Controller 
      var controllerName = Reflect.getMetadata(ControllerNameMetadataKey, target);
      // Формируем url вида /ControllerName/ActionName
      var url = "/" + controllerName + "/" + propertyKey;
      // Передаем url последним параметром
      [].push.call(arguments, url);
      // Вызываем исходный метод с дополнительным параметром
      originalMethod.apply(this, arguments);
  };
  // Обновляем дескриптор
  return descriptor;
}
// Функция, упрощающая объявление методов
function post(data: any, args: IArguments): any {
  // Получаем url, переданный декоратором @Action
  var url = args[args.length - 1];
  return $.ajax({ url: url, data: data, method: "POST" });
}