Topazdocs
Начало

Data Lens

Создайте, протестируйте, упакуйте и автономно запустите многомодульное local-first Web-приложение Topaz.

Data Lens показывает весь Web Application Loop в одном поддерживаемом приложении. Оно разбирает JSON и CSV в браузере, хранит строки и сводки в номинальных типах, нормализует многоязычные метки через зафиксированную пакетную зависимость и обрабатывает фильтрацию, сортировку, выбор, ошибки и клавиатуру, не отправляя набор данных на сервер. Topaz 5.7.0 предоставляет этот workflow в режиме языка topaz-5.7.

Выбор Web-продукта

Используйте web-app, когда Topaz владеет состоянием приложения, событиями, обновлением и представлением. Компилятор проверяет единый lifecycle init/update/view и создаёт полный статический продукт с ограниченным безопасным DOM-host. Выбирайте raw web или web-worker, когда существующий JavaScript-host владеет UI либо worker-протоколом и вызывает отдельные типизированные exports Topaz. Playground — песочница компилятора, а не модель развёртывания.

Data Lens использует web-app, потому что модель и взаимодействия принадлежат Topaz.

Структура пакета

Начните с установленного scaffold, затем разделите parsing, transformation, model, view и lifecycle по модулям:

BASH
topaz init --target web-app --root data-lens
mkdir -p data-lens/src data-lens/tests registry/lens_labels/1.0.0/src

Manifest приложения задаёт эффективную цель сборки, управляемый stylesheet и одну локальную зависимость:

TOML
[package]
name = "data_lens"
version = "0.1.0"
language = "5.7"
entry = "src/main.tpz"

[build]
target = "web-app"
deterministic = true

[web]
title = "Topaz Data Lens"
styles = ["styles/app.css"]
assets = []

[dependencies]
std = "5.7"
lens_labels = "1.0.0"

Храните приложение в пяти исходных модулях:

src/main.tpz       lifecycle и сообщения
src/model.tpz      номинальные строки, сводка, модель и enum сообщений
src/parsing.tpz    декодирование JSON/CSV и детерминированные ошибки путей
src/transform.tpz  фильтрация, сортировка и агрегаты
src/view.tpz       типизированное построение Html<Msg>

Модель делает переходы состояния явными:

TOPAZ
export record DataRow {
  name: string,
  category: string,
  value: int,
  active: bool,
}

export record Summary {
  totalRows: int,
  activeRows: int,
  totalValue: int,
}

export enum SortMode { ByName, ByValue }

export record Model {
  source: string,
  query: string,
  activeOnly: bool,
  sortMode: SortMode,
  rows: Array<DataRow>,
  summary: Summary,
  status: string,
  error: Option<string>,
}

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

TOPAZ
export function init() -> AppStep<Model, Msg> {
  AppStep { model: initialModel(), commands: [] }
}

export function update(model: Model, message: Msg, event: BrowserEvent) -> AppStep<Model, Msg> {
  match message {
    case QueryChanged => step(applyQuery(model, event.value ?? ""), [])
    case ActiveChanged => step(applyActive(model, event.checked ?? false), [])
    case Apply | Submit => step(applyModel(model), [])
    case SourceKey => {
      if (event.key ?? "") == "Enter" {
        return step(applyModel(model), [])
      }
      step(model, [])
    }
    case Clear => step(clearModel(), [focus("#source")])
  }
}

export function view(model: Model) -> Html<Msg> {
  render(model)
}

Parsing возвращает Result со стабильным путём, например JSON $[0].category: missing field. Update сохраняет ошибку в модели, а view выводит её как текст. Не переносите обработку в JavaScript и не вставляйте исходные данные через innerHTML.

Lock, проверки и тесты

Создайте локальный registry-пакет lens_labels, затем один раз скопируйте его в vendor. Все последующие команды используют lockfile и vendored bytes:

BASH
topaz vendor --root data-lens --from registry
rm -rf registry
topaz check --root data-lens --locked
topaz fmt --root data-lens --check
topaz test data-lens/tests/parsing.tpz --root data-lens --locked
topaz test data-lens/tests/transform.tpz --root data-lens --locked
topaz test data-lens/tests/application.tpz --root data-lens --locked
topaz doc --root data-lens --locked --out-dir data-lens-docs

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

Разработка и упаковка

Во время разработки используйте loopback-сервер, затем соберите управляемый продукт:

BASH
topaz dev --root data-lens --port 8000
topaz build --root data-lens --locked --release --out-dir data-lens-product

Проверьте CSV- и JSON-примеры, Unicode-метки, текстовый фильтр, checkbox только активных строк, оба режима сортировки, submit и Enter, выбор, очистку и одну ошибку отсутствующего поля. После ошибочной правки сервер продолжает отдавать последний исправный продукт.

Итоговый каталог содержит HTML, безопасный host приложения, проверенный raw Web facade, WASM, объявленные стили, лицензии, notices и topaz-artifact.json. Скопируйте только data-lens-product/ в новый статический корень, удалите исходники пакета и build storage, отключите сеть и раздавайте этот каталог. Все сценарии выше должны продолжить работу: продукту не нужны установка Topaz, registry, исходные файлы, npm runtime, CDN или удалённый сервис данных.

Дальше