@teqfw/di: Coding JavaScript like a Java boss

## Свод правил DI для TeqFW (v1.0)  - Код делится на:     - **Данные**: enum, DTO, фабрики.     - **Логика**: обработчики, координаторы.     - Один модуль = одна роль.  - Все зависимости передаются как **единый объект `deps`**, деструктурируемый сразу и плоско.     - Внутри модулей `import` запрещён.  - Допустимые экспорты:     - `default`-объект (например, enum),     - фабричная функция,     - класс с `constructor({deps})`.  - Идентификаторы зависимостей (ключи в `deps`):     - `Ns_Component$`: default-экспорт, синглтон.     - `Ns_Component$$`: default-экспорт, новый экземпляр.     - `Ns_Component.name$`: именованный экспорт, синглтон.     - `node:pkg`, `node:pkg.name`: внешние пакеты, как есть.  - Контейнер резолвит: `Ns_` → путь; `A_B_C` → `A/B/C.js`.  - Контейнер использует `import()` для загрузки; модули сами `import` не используют.  - Разрешён только `import` контейнера:   ```js   import Container from '@teqfw/di';   ```  - Зависимости должны быть:     - Явными,     - Названы по соглашению,     - Не сокращены (до `:` — имя для контейнера).  - Синглтоны кэшируются контейнером.  - Модули должны быть валидными ESM через `export`, даже без `import`.  - Весь код должен соответствовать этим правилам для совместимости с TeqFW. 

## Правила внедрения зависимостей (DI) в TeqFW (v1.0)  Этот документ формализует правила внедрения зависимостей (Dependency Injection, DI) в архитектуре TeqFW.   Документ предназначен для обработки языковыми моделями (LLM) и использования при генерации кода.  Материал структурирован в виде принципов и примеров, иллюстрирующих допустимые формы кода. Особое внимание уделяется совместимости с DI-контейнером TeqFW, предсказуемости адресации зависимостей, модульной изоляции и отказу от прямого импорта.  ---  ### 📌 Принцип 1. Функциональное разделение кода  > Код делится на две независимые группы: > > - **Данные (структуры)** — описывают *что это за данные* (enum, DTO, фабрики, значения по умолчанию). > - **Обработчики** — описывают *что делать с данными* (логика, команды, координация).  📌 Один модуль — одна роль.   Нельзя совмещать структуру и поведение в одном модуле.  #### ✅ Пример: enum-структура  ```js // ✅ ES-модуль, без import, подходит для DI const Smtp_Log_Enum_Command = {     INIT_DB: 'init-db',     LOG: 'log', }; export default Smtp_Log_Enum_Command; ```  #### ✅ Пример: DTO + фабрика  ```js // ✅ Поддерживает DI через параметры конструктора export default class Smtp_Log_Dto_Config {     constructor({Smtp_Log_Enum_Command$: CMD}) {         this.create = function (data) {             const res = Object.assign(new Dto(), data);             res.command = data?.command ?? CMD.LOG;             return res;         };     } }  class Dto {     command;     dbName;     dbPass;     dbUser; } ```  #### ✅ Пример: обработчик  ```js // ✅ Обработчик с внедрением всех зависимостей через deps export default class Smtp_Log_App {     constructor({                     Smtp_Log_App_Configurator$: configurator,                     Smtp_Log_Cmd_Init$: cmdInit,                     Smtp_Log_Cmd_Log$: cmdLog,                     Smtp_Log_Enum_Command$: CMD,                 }) {         this.run = async function (opts) {             // use dependencies         };     } } ```  ---  ### 📌 Принцип 2. Совместимость экспортов с DI-контейнером  > Каждый модуль должен экспортировать сущность, пригодную для создания через DI-контейнер и повторного использования.  Допустимые варианты экспортов:  - **Объект** — используется напрямую (например, `enum`). - **Фабричная функция** — получает зависимости через параметры, возвращает объект. - **Класс** — получает зависимости через конструктор.  📌 Все зависимости передаются только через параметры — `import` запрещён.   📌 DI-контейнер сам создаёт зависимости и передаёт их в модуль.  ---  ### 📌 Принцип 3. Жизненный цикл: один модуль — один экземпляр  > Каждый модуль создаётся один раз и работает как изолированный экземпляр.  #### ✅ Пример: класс  ```js export default class Smtp_Log_App {     constructor({configurator}) {         this.run = async function (opts) {             const cfg = configurator.build();             // ...         };     } } ```  #### ✅ Пример: фабрика  ```js export default function createSmtpLogApp({configurator}) {     return {         async run(opts) {             const cfg = configurator.build();             // ...         }     }; } ```  📌 Все экземпляры создаются контейнером один раз.   📌 Такие модули можно использовать вручную, передавая зависимости явно.   📌 Если модуль используется как синглтон (`$`), контейнер кэширует экземпляр после первого создания.   ---  ### 📌 Принцип 4. Зависимости передаются через `deps`  > Все зависимости передаются в виде **одного объекта `deps`**, который деструктурируется при создании модуля.  📌 Деструктуризация должна быть:  - **сразу при входе** (в конструкторе или фабрике); - **плоской** — без вложенных структур; - **явной** — без `import`.  #### ✅ Пример  ```js export default class Some_Module {     constructor({logger, config}) {         // Используем logger и config     } } ```  ---  ### 📌 Принцип 5. Именование и адресация зависимостей  > Все зависимости в объекте `deps` обозначаются по соглашению `Namespace_Component$`.  #### 📌 Форматы:  - `Namespace_Component$` — default-экспорт, singleton - `Namespace_Component$$` — default-экспорт, новый экземпляр - `Namespace_Component.name$` — именованный экспорт, singleton - `node:pkg` — весь npm-модуль, as-is - `node:pkg.export` — именованный экспорт из npm-модуля, as-is  #### ✅ Пример внедрения  ```js export default class Smtp_Log_App {     constructor(         {             Smtp_Log_App_Configurator$: configurator,             Smtp_Log_Cmd_Init$: cmdInit,             Smtp_Log_Cmd_Log$: cmdLog,         }     ) {         // ...     } } ```  📌 Все зависимости видимы DI-контейнеру по имени свойства (до `:`), а в коде работают через локальные переменные (после `:`).  #### ⚠️ Важно для моделей:  - Не сокращай имена (`Configurator$` — недостаточно). - Не модифицируй имена до `:` — они важны для контейнера. - Не используй `import` — даже для одной зависимости. - Всегда используй деструктуризацию `deps`.  ---  ### 📌 Принцип 6. Резолвинг зависимостей через пространства имён  > Контейнер разрешает зависимости по идентификатору `Namespace_Component$`, сопоставляя `Namespace_` с путём в файловой системе.  #### ✅ Пример настройки контейнера  ```js #!/usr/bin/env node 'use strict'; import Container from '@teqfw/di';  const container = new Container(); const resolver = container.getResolver(); resolver.addNamespaceRoot('Smtp_Log_', import.meta.resolve('./src'));  const app = await container.get('Smtp_Log_App$'); app.run().catch(console.error); ```  #### 📌 Как работает резолвинг  - `Smtp_Log_` → `./src/` - `Dto_Config` → `Dto/Config.js`  📌 `A_B_C` → `A/B/C.js`  #### 📁 Примеры:  | Идентификатор          | Пространство | Компонент    | Путь к файлу          | |------------------------|--------------|--------------|-----------------------| | `Smtp_Log_App$`        | `Smtp_Log_`  | `App`        | `./src/App.js`        | | `Smtp_Log_Dto_Config$` | `Smtp_Log_`  | `Dto_Config` | `./src/Dto/Config.js` | | `Ns_Group_Web_App$`    | `Ns_Group_`  | `Web_App`    | `./group/Web/App.js`  |  ---  ### 📌 Принцип 7. Соответствие стандартам ESM  > Модули TeqFW не используют `import`, но остаются валидными ES-модулями благодаря использованию `export`.  #### ⚠️ Разрешён только `import` при инициализации контейнера:  ```js import Container from '@teqfw/di'; ```  📌 Все прочие зависимости внедряются через `deps`. 📌 Контейнер использует динамическую загрузку (`import()`), чтобы найти и создать зависимости.   Это позволяет избегать жёстких связей и исключает необходимость использования `import` в прикладных модулях. 📌 Это архитектурное ограничение, а не технический запрет. Оно обеспечивает изоляцию и предсказуемость.  ---  ### ✅ Итог  Все приведённые принципы направлены на унификацию структуры модулей, автоматизируемость создания и анализа кода, а также минимизацию неявных зависимостей. Документ формирует строгое техническое основание для корректной работы DI-контейнера и предсказуемого поведения при генерации кода с использованием LLM.  Отклонения от описанных правил приводят к потере совместимости с архитектурой TeqFW.