У TypeScript есть встроенная поддержка JSX синтаксиса и компилятор TypeScript'а предоставляет годные инструменты по настройке процесса компиляции JSX. По сути, это создает возможность писать типизированный DSL используя JSX. В этой статье речь пойдет именно про это — как написать DSL из г с помощью JSX. Заинтересовавшихся прошу под кат.


→ Репозиторий с готовым примером.


В этой статье я не буду показывать возможности на примерах, относящихся к вебу, React'у и подобным. Пример не из веба позволит продемонстрировать что возможности JSX не ограничены React'ом, его компонентами и генерацией html в общем случае. В этой статьи я покажу как реализовать DSL для генерации объектов сообщений для Slack.


Вот код который мы возьмем за основу. Это маленькая фабрика сообщений одного и того же типа:


interface Story { 
  title: string
  link: string
  publishedAt: Date
  author: { name: string, avatarURL: string }
}

const template = (username: string, stories: Story[]) => ({
  text: `:wave: Привет ${username}, зацени наши последние статьи.`,
  attachments: stories.map(s => ({
    title,
    color: '#000000',
    title_link: s.link,
    author_name: s.author.name,
    author_icon: s.author.avatarURL,
    text: `Опубликовано в _${s.publishedAt}_.`
  })
})

Вроде бы выглядит неплохо, но тут есть один момент который можно значительно улучшить — читабельность. Например, обратите внимание на непонятно к чему относящееся свойство color, на два поля для заголовка (title и title_link) или на подчеркивания в text (текст внутри _ будет курсивом). Все это мешает нам разделять контент от стилистических деталей, усложняя поиск того что важно. И вот с такими проблемами DSL и должны помогать.


Вот тот же пример только уже написанный в JSX:


const template = (username: string, stories: Story[]) => 
  <message>
    :wave: Привет ${username}, зацени наши последние статьи.

    {stories.map(s =>
      <attachment color='#000000'>
        <author icon={s.author.avatarURL}>{s.author.name}</author>
        <title link={s.link}>{s.title}</title>

        Опубликовано в <i>{s.publishedAt}</i>.
      </attachment>
    )}
  </message>

Намного лучше! Все что должно жить вместе объединилось, стилистические детали и контент четко разделены — красота одним словом.


Пишем DSL


Настраиваем проект


Сначала необходимо включить JSX в проекте и сказать компилятору что мы не используем React, что наш JSX нужно компилировать иначе.


// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "Template.create"
  }
}

"jsx": "react" включает поддержку JSX в проекте и компилятор компилирует все JSX элементы в вызовы React.createElement. А опция "jsxFactory" настраивает компилятор на использование нашей фабрики JSX элементов.


После этих нехитрых настроек код вида:


import * as Template from './template'

const JSX = <message>Text with <i>italic</i>.</message>

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


const Template = require('./template');

const JSX = Template.create('message', null,
    'Text with ',
    Template.create('i', null, 'italic'),
    '.');

Опишем JSX теги


Теперь, когда компилятор знает во что компилировать JSX, нам нужно объявить сами теги. Для этого мы задействуем одну из классных возможностей TypeScript'а — а именно локальные декларации пространств имен. Для случая с JSX TypeScript ожидает что в проекте есть пространство имен JSX(конкретная локация файла не имеет значения) с интерфейсом IntrinsicElements в котором и описаны сами теги. Компилятор их цепляет и использует для проверки типов и для подсказок.


// jsx.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    i: {}
    message: {}
    author: { icon: string }
    title: { link?: string }
    attachment: {
      color?: string
    }
  }
}

Здесь мы объявили все JSX теги для нашего DSL и все их атрибуты. По сути, имя ключа в интерфейсе это название самого тега который будет доступен в коду. Значение это описание доступных атрибутов. У некоторых тегов (i в нашем случае) может и не быть никаких атрибутов, у других опциональные или вообще необходимые.


Собственно фабрика — Template.create


Наша фабрика из tsconfig.json и есть предмет разговора. Она будет использоваться в рантайме для создания объектов.


В самом простом случае она может выглядеть как-то так:


type Kinds = keyof JSX.IntrinsicElements // Имена всех тегов
type Attrubute<K extends Kinds> = JSX.IntrinsicElements[K] // и их атрибуты

export const create = <K extends Kinds>(kind: K, attributes: Attrubute<K>, ...children) => {
  switch (kind) {
    case 'i': return `_${chidlren.join('')}_`
    default: // ...
  }
}

Теги которые добавляют только стили к тексту внутри легко написать (i в нашем случае): наша фабрика просто заворачивает содержимое тега в строку с _ с обеих сторон. Проблемы начинаются со сложными тегами. Большую часть времени я провозился именно с ними, в поисках решения почище. В чем же собственно проблема?


А она в том, что компилятор выводит тип <message>Text</message> в any. Что и близко не стояло с типизированным DSL, ну это ладно, вторая часть проблемы в том что тип у всех тегов будет один после прохода через фабрику — это ограничение самого JSX (у React'а все теги преобразуются в ReactElement).


Дженерики идут на помощь!


// jsx.d.ts
declare namespace JSX {
  interface Element {
    toMessage(): {
      text?: string
      attachments?: {
        text?: string
        author_name?: string
        author_icon?: string
        title_link?: string
        color?: string
      }[]
    }
  }

  interface IntrinsicElements {
    i: {}
    message: {}
    author: { icon: string }
    title: { link?: string }
    attachment: {
      color?: string
    }
  }
}

Добавился только Element и теперь компилятор будет выводить все JSX теги в тип Element. Это тоже стандартное поведение компилятора — использовать JSX.Element как тип для всех тегов.


У нашего Element есть только один общий метод — приведение его к типу объекта сообщения. К сожалению он будет работать не всегда, только на самом верхнеуровневом теге <message/> и это будет в райнтайме.


А под спойлером полная версия нашей фабрики.


Собственно код фабрики
import { flatten } from 'lodash'

type Kinds = keyof JSX.IntrinsicElements // Имена всех тегов
type Attrubute<K extends Kinds> = JSX.IntrinsicElements[K] // и их атрибуты

const isElement = (e: any): e is Element<any> =>
  e && e.kind

const is = <K extends Kinds>(k: K, e: string | Element<any>): e is Element<K> =>
  isElement(e) && e.kind === k

/* Конкатенация всех прямых потомков которые не являются элементам (строки) */
const buildText = (e: Element<any>) =>
  e.children.filter(i => !isElement(i)).join('')

const buildTitle = (e: Element<'title'>) => ({
  title: buildText(e),
  title_link: e.attributes.link
})

const buildAuthor = (e: Element<'author'>) => ({
  author_name: buildText(e),
  author_icon: e.attributes.icon
})

const buildAttachment = (e: Element<'attachment'>) => {
  const authorNode = e.children.find(i => is('author', i))
  const author = authorNode ? buildAuthor(<Element<'author'>>authorNode) : {}

  const titleNode = e.children.find(i => is('title', i))
  const title = titleNode ? buildTitle(<Element<'title'>>titleNode) : {}

  return { text: buildText(e), ...title, ...author, ...e.attributes }
}

class Element<K extends Kinds> {
  children: Array<string | Element<any>>

  constructor(
    public kind: K,
    public attributes: Attrubute<K>,
    children: Array<string | Element<any>>
  ) {
    this.children = flatten(children)
  }

  /*
   * Конвертация элемента в тип сообщения работает только с тегом `<message/>`
   */
  toMessage() {
    if (!is('message', this)) return {}
    const attachments = this.children.filter(i => is('attachment', i)).map(buildAttachment)
    return { attachments, text: buildText(this) }
  }
}

export const create = <K extends Kinds>(kind: K, attributes: Attrubute<K>, ...children) => {
  switch (kind) {
    case 'i': return `_${children.join('')}_`
    default: return new Element(kind, attributes, children)
  }
}

→ Репозиторий с готовым примером.


Вместо заключения


Когда я делал эти свои опыты у команды TypeScript'а только появлялось понимание мощи и ограничений того что они сделали с JSX. Сейчас его возможностей еще больше и фабрику можно написать чище. Если появится желание покопаться и улучшить репозиторий с примером — велкам с пулл реквестами.