TeqFW: организация верхнего уровня кода

Дата публикации: 2024-02-15

TeqFW позволяет использовать часть JavaScript-кода без изменений и на сервере, и в браузере — например, константы и DTO. Но фронтенд и бэкенд решают разные задачи: фронтенд взаимодействует с человеком, бэкенд — с базами, очередями и другими приложениями. Поэтому границы нужно сделать очевидными уже в структуре пакета.

Три области исходников

В обычном npm-пакете это могло бы выглядеть так:

src/
  back/
  front/
  shared/

TeqFW использует CamelCase в именах каталогов и файлов:

src/
  Back/
  Front/
  Shared/
    Dto/
      UserAuth/

Back содержит только серверный код; Front — только браузерный; Shared — код, пригодный в обеих средах. Если в пакете нет кода одной области, соответствующий каталог не нужен.

Имена модулей и DI

По пути к ES-модулю TeqFW формирует логическое имя, которым оперирует контейнер зависимостей. Например, файл src/Shared/Dto/UserAuth/Permission.js может получить имя:

Vendor_App_Shared_Dto_UserAuth_Permission

Контейнер использует такое имя для адресации и внедрения зависимости. Разделение каталогов помогает одновременно читать архитектуру глазами и сохранять одинаковый механизм связи для модулей.

Почему это обязательное правило

Платформа отдаёт браузеру исходники из Front и Shared. Значит, в них нельзя помещать зависимости, которые доступны только в Node.js. Например:

import { existsSync, mkdirSync, rmSync } from 'node:fs';

Браузер не умеет выполнять API файловой системы Node.js. Такой импорт законен в Back, но сломает загрузку в клиенте. Граница на верхнем уровне пакета предотвращает эту ошибку раньше, чем она попадёт к пользователю.

Примеры пакетов с этой структурой: demo-webauthn-pubkey, spa-remote-console и teqfw/core.

Вывод

Корневой каталог можно назвать src, source или иначе. Но для Teq-плагина разделение на Back, Front и Shared обязательно. Внутри этих областей структура свободна, а на верхнем уровне правило фиксирует сферы использования модуля и делает общий JavaScript между браузером и Node.js управляемым.