# fast-xml-parser: мастерская XML-интеграций

Девять задач и 19 готовых вариантов с настоящим выполнением fast-xml-parser 5.12.1. В браузере документ обрабатывается локальным Web Worker, в Node.js CLI — worker_threads. Это не запись и не серверная имитация. Данные вымышленные; редактор не отправляет их на сайт, localStorage не используется.

Браузерный результат зависит от введённого текста и отмеченных настроек. У задания 7 входной формат JSON: проверенный заказ превращается в XML, затем разбирается обратно. У задания 8 дополнительно работает наш контракт импорта. Ошибки политики входа, синтаксиса и контракта различаются.

## Что попробовать

1. Атрибуты: ID товара и одноимённый дочерний элемент.
2. Повторы: один или два товара всегда в массиве catalog.product.
3. Типы: артикул 00125, почтовый индекс, сумма и большой ID.
4. Namespaces: сохранить префиксы или увидеть слияние item.
5. CDATA и смешанный текст: обычный объект или последовательность узлов.
6. XMLValidator: настоящие строка/столбец при перепутанном закрывающем теге.
7. XMLBuilder: экранирование значений и семантическое сравнение заказа после обратного разбора.
8. Контракт: обязательные поля, формат ID, количество и дубликаты.
9. Entities, запрет DOCTYPE и лимит входа 32 KiB по UTF-8 байтам.

## Требования и версии

Node.js 24 LTS, минимум 24.15.0 для зависимостей тестирования. Проверенные точные версии фиксируются вpackage-lock.json. fast-xml-parser 5.12.1 и Bootstrap 5.3.9 используются приложением, esbuild 0.28.2 собирает браузерный код, JSDOM 31.0.1 нужен только тесту интерфейса. Для открытия готового public npm-зависимости не нужны: server tools/serve.mjs использует встроенные модули Node. Для CLI, пересборки и тестов выполните npm ci.

## Windows / PowerShell

Распакуйте архив и перейдите в каталог проекта. Установите Node.js 24 LTS из официального источника, проверьте node --version и npm --version.

```powershell
npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run capture
npm run xml -- arrays fixtures/arrays.xml
npm run serve
```

Откройте http://127.0.0.1:8542. Встроенный сервер слушает только loopback. Остановите его Ctrl+C. Если порт занят, выберите другой, не завершая неизвестный процесс:

```powershell
$env:PORT = '8642'
npm run serve
```

Готовый публичный каталог уже включён в ZIP. При использовании только мастерской достаточно node tools/serve.mjs. Открытие index.html через file:// не является поддержанным запуском: Worker и fetch источников требуют HTTP. Кнопка скачивания полного архива предназначена для установленной мастерской на сайте; локальная копия уже находится у вас.

Чтобы проверить свой XML, сохраните его в UTF-8 и передайте путь как аргумент. Имена с пробелами заключайте в кавычки. Команда получает только путь файла, не URL. Сеть для чтения документа не используется.

```powershell
node tools/cli.mjs contract 'C:\imports\supplier.xml'
$LASTEXITCODE
```

Код 0 означает успешный результат,2 — ошибку входа, синтаксиса или контракта. JSON результата печатается вstdout, ошибка запуска — вstderr. CLI не пишет в базу и не обновляет файл поставщика. Перенаправленный результат рассматривайте как новый артефакт обработки, а не как подтверждение применения изменений.

## Linux / Bash

При установленном Node.js 24 команды установки и тестирования те же. Зависимости ставятся отдельно для каждой ОС; не переносите node_modules между Windows и Linux.

```bash
npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run capture
node tools/cli.mjs contract fixtures/contract.xml
PORT=8642 npm run serve
```

CLI можно выполнить в контейнере с закреплённой версией Node. Dockerfile устанавливает только production-зависимости, использует непривилегированного пользователя node, не открывает порты и не создаёт внешних отправок.

```bash
docker build -t aen-xml-lab:1 .
docker run --rm --network none aen-xml-lab:1 arrays fixtures/arrays.xml
docker run --rm --network none \
  --mount type=bind,source="$PWD/fixtures",target=/input,readonly \
  aen-xml-lab:1 contract /input/contract.xml
```

В PowerShell первую проверку можно выполнить без mount той же командой docker run. Для своего каталога передавайте абсолютный путь через --mount; не подставляйте Bash$PWD в чужую оболочку. На Linux UID1000 из контейнера должен иметь право чтения файла и прохода по каталогу. Контейнеру не нужна запись в исходный каталог.

## Где находится код

- src/lab.mjs: реальный адаптер XMLParser/XMLValidator/XMLBuilder и контракт.
- src/cases.mjs: девять задач, варианты и настройки.
- src/worker.mjs: браузерный Worker.
- src/node-runner.mjs и node-worker.mjs: изолированный запуск в Node.
- src/app.mjs: редактор, переключатели, результат и экспорт.
- tools/cli.mjs: файл → результат с кодом завершения.
- public: готовая статическая мастерская, локальные JS/CSS, тексты документации.
- tests: реальные проверки данных и тест собранного интерфейса.
- qa/actual-node-results.json: создаваемое командой capture доказательство Node-запусков; сайт из него результаты не берёт.
- docs/VPS.md: отдельная Linux/VPS практика.

## Границы и обновления

XMLValidator проверяет синтаксис, не XSD и не бизнес-смысл. Наш контракт — отдельная функция. Парсер сохраняет префиксы имён, но не заменяет namespace-aware обработчик, разрешающий все URI. preserveOrder помогает сохранить последовательность узлов, но не обещает прежние кавычки, переносы, комментарии и побайтовый round-trip. Сборка заказа использует собственный разрешённый набор полей; произвольные JSON-ключи не становятся XML-тегами.

Вход ограничен 32768 UTF-8 байтами, DOCTYPE/ENTITY запрещены консервативной текстовой проверкой. Запрет сработает даже на такую последовательность внутри комментария/CDATA/JSON-строки: здесь это намеренное ограничение учебного адаптера. Выбор processEntities остаётся явным; он влияет на раскрытие стандартных ссылок. Браузер и Node прерывают рабочий поток после 2 секунд ожидания. Таймер не является жёсткой гарантией реального времени при занятом планировщике.

Для больших выгрузок нужен отдельный конвейер с потоковым разбором, квотами и backpressure. Не повышайте предел редактора до размеров промышленного архива. XML из редактора показывается textContent; HTML из CDATA никогда не вставляется в DOM.

Официальные текущие документы рекомендуют отдельные пакеты fast-xml-builder и fast-xml-validator. В закреплённойv5.12.1 экспорт XMLBuilder и XMLValidator остаётся доступным и реально проверяется здесь. При обновлении major версии сначала проверяйте API, миграцию и лицензии; не меняйте lock-файл без повторных тестов.

В проверенной версии 5.12.1 processEntities:true раскрывает amp/lt, но числовая ссылка A остаётся текстом при htmlEntities:false. Переключатель «HTML и числовые entities» включает htmlEntities:true: тогда получается A. Это наблюдение текущей реализации, закреплённое тестом, а не универсальное правило XML.