Как я закрыл трехлетний issue в TypeScript

Всё началось с моего желания описать структуру сообщений между web worker'ами. К сожалению, на тот момент встроенные возможности TypeScript этого не позволяли.

Я засучил рукава и решил это исправить.

Суть проблемы

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

new Worker().addEventListener('message', (message) => {
    message // MessageEvent
    message.data // any
})

В поле data находятся именно те данные, что вы, автор кода, отправляете. И именно тип этого поля хочется определять.

Изучаем MessageEvent поближе

MessageEvent — интерфейс, описывающий сообщения при коммуникации между вкладками, воркерами, сокетами, WebRTC каналами и т.д.

В экосистеме TypeScript этот интерфейс является частью lib.dom.ts и lib.webworker.d.ts, и описан следующим образом:

interface MessageEvent extends Event {
    readonly data: any;
    readonly lastEventId: string;
    readonly origin: string;
    readonly ports: ReadonlyArray<MessagePort>;
    readonly source: MessageEventSource | null;
}

Опытные разработчики сразу увидят тут проблему. Этот интерфейс не Generic — поле data описано строго как any, и мы никак не можем на это повлиять из вне.

Решив поискать информацию по этому поводу в репозитории TypeScript я быстро нашел issue в котором описана эта проблема. И даже больше — автор предложил решение. Но за почти три года, оно так и не было имплементировано. Я засучил рукава, и решил сделать это.

Всего-то и нужно что привести интерфейс MessageEvent, в файлах lib/lib.dom.d.ts и lib/lib.webworker.d.ts к такому виду:

interface MessageEvent<T = any> extends Event {
    readonly data: T;
    readonly lastEventId: string;
    readonly origin: string;
    readonly ports: ReadonlyArray<MessagePort>;
    readonly source: MessageEventSource | null;
}

Сделаем это.

Изучаем TypeScript Instructions for Contributing Code

В нем есть целый раздел посвященный изменениям в файлах lib.d.ts. Оттуда узнаём две вещи:

1. Файлы в папке lib/ напрямую изменять нельзя. Там находятся last-known-good версии и они периодически обновляются на основе соответствующих файлов из папки src/lib/. Вот в них то и нужно вносить правки. В нашем случае это src/lib/dom.generated.d.ts и src/lib/webworker.generated.d.ts
2. Практически все файлы в директории src/lib/ можно просто отредактировать. За исключением генерируемых (.generated.d.ts). Такие файлы создаются с помощью утилиты TSJS-lib-generator и мы должны вносить правки именно в неё.

Изучаем TSJS-lib-generator

TSJS-lib-generator — это инструмент (написанный на TS) который принимает все известные Microsoft Edge веб-интерфейсы и преобразовывает их в набор TypeScript интерфейсов. При этом существует возможность переопределить характеристики каких-либо интерфейсов, удалить некоторые или добавить новые.

Все эти правила описываются в json формате в файлах addedTypes.json, overridingTypes.json и removedTypes.json.

Правило для изменения MessageEvent

Нам нужно изменить существующий интерфейс, поэтому будем редактировать overridingTypes.json.

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

Итак, в overridingTypes.json в свойстве interfaces добавляем новый интерфейс, пока что без каких либо свойств:

{
  "interfaces": {
    "interface": {
      "MessageEvent": {}
    }
  }
}

Пробуем запустить сборку и проверим, что ничего не сломалось:

npm run build

TSJS-lib-generator сгенерирует те самые *.generated.d.ts файлы. И сейчас они должны быть идентичны *.generated.d.ts файлам в репозитории TS.

Добавляем свойство type-parameters, тем самым превращая MessageEvent в Generic:

{
  "interfaces": {
    "interface": {
      "MessageEvent": {
        "type-parameters": [
          {
            "name": "T",
            "default": "any"
          }
        ]
      }
    }
  }
}

Запускаем сборку и проверяем результат:

interface MessageEvent<T = any> extends Event {
    readonly data: any;
    readonly lastEventId: string;
    readonly origin: string;
    readonly ports: ReadonlyArray<MessagePort>;
    readonly source: MessageEventSource | null;
}

Уже ближе к тому, что мы в итоге хотим получить. Добавим описание свойства data и сигнатуры конструктора:

{
  "interfaces": {
    "interface": {
      "MessageEvent": {
        "name": "MessageEvent",
        "type-parameters": [
          {
            "name": "T",
            "default": "any"
          }
        ],
        "properties": {
          "property": {
            "data": {
              "name": "data",
              "read-only": 1,
              "override-type": "T"
            }
          }
        },
        "constructor": {
          "override-signatures": [
            "new<T>(type: string, eventInitDict?: MessageEventInit<T>): MessageEvent<T>"
          ]
        }
      }
    }
  }
}

И вуаля! Генерируется в точности то, что нам необходимо.

interface MessageEvent<T = any> extends Event {
    readonly data: T;
    readonly lastEventId: string;
    readonly origin: string;
    readonly ports: ReadonlyArray<MessagePort>;
    readonly source: MessageEventSource | null;
}

Далее дело за малым:

• Запустить тесты
• Оформить Pull Request в соответствии со всеми правилами описанными в Contribution Guidelines
• И подписать CLA от Microsoft.

Итог

Спустя неделю с момента отправки мой Pull Request был принят. 12.06.2020 были обновлены src/lib/dom.generated.d.ts и src/lib/webworker.generated.d.ts в репозитории TypeScript. А на момент написания статьи все правки перенесены в lib/lib.dom.ts и lib/lib.webworker.d.ts и уже доступны в TypeScript Nightly.

Let's block ads! (Why?)