Cruzo — минималистичный UI-фреймворк без лишней сложности 

Знакомимся с Cruzo. Часть 1. RxBucket – контейнер состояний и конфигураций компонентов на фронте

Я продолжаю серию обзорных статей о js-фреймворке Cruzo. Я работаю над этим фреймворком последние 6 лет, много идей отпало, осталось только что реально нужно в работе.
Здесь я расскажу вам о сердце фреймворка – шаблонизаторе. Для его реализации была написана стековая виртуальная машина.
Какая еще виртуальная машина внутри js спросите вы? Это VM — но не «виртуальный процессор» вроде JVM или WebAssembly, а интерпретатор байткода, написанный на JavaScript.

Немного о разметке шаблонов в Cruzo

Разметка шаблонов Cruzo это – расширенный HTML, а синтаксис выражений подмножество JavaScript, но с некоторыми оговорками (::rx, once::).

<span>{{ once::root.label }}</span>

<button onclick="{{root.count$.update(root.count$::rx + 1)}}">
  ping: {{root.count$::rx}}
</button>

Вдобавок к этому, если мы говорим про компонент Cruzo (AbstractComponent), там шаблон – это функция, это не просто статичный файл.

export class MyComponent extends AbstractComponent {
  ...
  getHTML() {
    return `<div>
        <button onclick="{{ root.count.update(root.count::rx + 1) }}">
        Clicks: <b>{{ root.count::rx }}</b>
        </button>
      </div>`;
  }
  ...
}

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

Например, можно собрать разметку на ходу — без условий внутри самого HTML:

export class MyComponent extends AbstractComponent {
  ...
  getHTML() {
    let extHTML = ``;
  
    if (this.config.myParam) {
      extHTML = <div class="ext-block"></div>;
    }
  
    return `${extHTML}
        <button onclick="{{root.count$.update(root.count$::rx + 1)}}">
          ping: {{root.count$::rx}}
        </button>
    `;
  }
}

Как создается шаблон в Cruzo

Путь создания шаблона в Cruzo начинается не с “ручного” парсинга, парсинг HTML-разметки выполняет сам браузер

export abstract class AbstractComponent<Config = any, ValueType = any, StateType = any>{
  ...  
  protected initTemplate() {
    const html = this.getHTML();
  
    if (html) {
      this.node.innerHTML = html;
      
      this.template = new Template({
        node: this.node,
        self: () => this,
        selector: this.selector,
        tplFile: this.tplFile,
        domStructureChanged: () => {
          this.domStructureChanged();
        },
      });
    
      this.template.detectChanges();
      this.updateDependencies();
    }
  }
  ...
}

В класс Template просто передается нода с шаблоном

export class Template {
  ...
  constructor(params: TemplateParams) {
    Object.assign(this, params);
  
    if (typeof this.self !== "function") {
      throw new Error("Invalid self param");
    }
  
    if (!this.root) {
      this.root = this;
      this.debug = {
        selector: params.selector,
        tplFile: params.tplFile,
      };
      
      this.onRxUpdate = this.getRxUpdate();
    }
  
    this.handleDomAttributes();
    this.handleAttributes();
    if (!this.innerHtmlTemplateBC) this.handleChildrens(this.node);
    this.setEvents();
  }
  ...
}

Внутри самого Template происходит обход DOM-дерева. Ищутся выражения с {{...}}, специальным образом обрабатываются атрибуты такие как attached, inner-html, repeat, let-...

Lifecycle шаблона

AbstractComponent.initTemplate() → создается экземпляр класса Template, при инициализации происходит обход DOM, во время которого находятся {{expr}} → tokenizeExpr(expr) → new VMProgramCompiler(tokens).getBytecode(expr)

Чуть позже вы увидите, как шаблон превращается в байт-код.

Также возможны два варианта обновления шаблона.

Если мы используем AbstractComponent.template.detectChanges() мы пересчитываем все свойства и делаем обновления в DOM, также при вызове этого метода снимутся текущие подписки на реактивные значения в шаблоне и создадутся новые. Этот метод обязательно вызывается в AbstractComponent.initTemplate(), а второй вариант обновления шаблона это просто изменение реактивного значения Rx.update(newVal). Рекомендуется использовать просто обновление реактивных значений, аAbstractComponent.template.detectChanges() оставить на инициализацию

Выражение компилируется один раз. При клике или изменении Rx выполняется уже готовый байт-код, строка заново не парсится.

Спецатрибуты шаблона

Помимо {{ }}, в Cruzo есть атрибуты, которые шаблонизатор понимает особым образом:

• repeat — цикл, клонирование DOM-элементов

• let-* — локальные переменные внутри шаблона

• inner-html — реактивная вставка HTML

• attached — условное наличие элемента в DOM

• onclick, oninput и другие on* — обработчики событий через VM

Пример с let-* и inner-html:

<div let-name="{{root.user$::rx.name}}" let-tags="{{root.user$::rx.tags}}">
  Name: <b>{{name ?? "Anonymous"}}</b>
  <span inner-html="{{root.html$::rx}}"></span>
</div>

Рассмотрим как шаблон превращается в байт-код

Допустим мы имеем шаблон:

<button onclick="{{root.count$.update(root.count$::rx + 1)}}">
  ping: {{root.count$::rx}}
</button>

Дальше идет разбивка на токены. У токенов есть типы

export type Tok =

| { t: "num"; v: number }

| { t: "str"; v: string }

| { t: "id"; v: string }

| { t: "op"; v: string }

| { t: "punc"; v: string }

| { t: "eof" };

Если мы будем рассматривать пример выше, мы получим такие токены через tokenizeExpr()

 0  { t: "id",    v: "root" }
 1  { t: "op",    v: "." }
 2  { t: "id",    v: "count$" }
 3  { t: "op",    v: "." }
 4  { t: "id",    v: "update" }
 5  { t: "punc",  v: "(" }
 6  { t: "id",    v: "root" }
 7  { t: "op",    v: "." }
 8  { t: "id",    v: "count$" }
 9  { t: "op",    v: "::" }
10  { t: "id",    v: "rx" }
11  { t: "op",    v: "+" }
12  { t: "num",   v: 1 }
13  { t: "punc",  v: ")" }
14  { t: "eof" }

Следующий этап это работа VMProgramCompiler.

VMProgramCompiler обходит токены и мы получаем такой байт-код

 0  LOAD_ID            root
 1  GET_PROP           "count$"
 2  GET_PROP_KEEP      "update"
 3  LOAD_ID            root
 4  GET_PROP           "count$"
 5  RX_UI
 6  PUSH_CONST         1
 7  BIN_ADD
 8  CALL_METHOD        argc=1

Этот байт-код хранится в экземпляре класса Template.

Как я упоминал ранее, скомпилированные выражения кешируются — при повторном использовании того же текста компиляция не повторяется.

Что происходит при клике

Когда пользователь нажимает кнопку, VM выполняет байт-код обработчика onclick. Контекст здесь — событие (event), а не текстовая нода.

По сути происходит следующее:

1. root — это текущий компонент

2. count$::rx — текущее значение счётчика (например, 3)

3. 3 + 1 = 4

4. вызывается count$.update(4)

5. срабатывают подписчики — в том числе текст ping: {{root.count$::rx}} на кнопке

6. UI обновляется

Текст кнопки и обработчик клика — два разных выражения. Они компилируются отдельно и живут отдельно.

::rx в тексте и в обработчике

В обработчике события реактивная подписка не нужна — там важно получить актуальное значение в момент клика. В тексте — наоборот, DOM должен обновляться сам, когда Rx меняется.

Зачем VM, а не eval

• нельзя выполнить произвольный код в шаблоне

• ::rx и once:: встроены прямо в VM

• байт-код кешируется

• ошибки приходят с контекстом — выражение, селектор компонента

• нормальная работа с CSP-тегами

Для нетривиальной логики есть методы компонента — их можно вызывать из шаблона:

formatDate(lastLogin: number) {
  return lastLogin ? new Date(lastLogin).toLocaleString() : "-";
}

<b>{{root.formatDate(root.user$::rx.meta?.lastLogin)}}</b>

Шаблонизатор Cruzo — это не парсер HTML и не eval в шаблоне. Браузер парсит разметку, Cruzo находит выражения, токенизирует, компилирует их в байт-код и выполняет через свою VM, а если это реактивные значения ::rx — после их обновлений выполняется байт-код и при изменение результата происходят точечные обновления.

В следующей части, возможно, разберём реактивные примитивы Rx и RxFunc

Попробовать Cruzo: https://github.com/MaratBektemirov/cruzo, https://cruzo.org