@e22m4u/ts-rest-router 0.5.0 → 0.5.1

package/README.md

@@ -17,6 +17,7 @@ REST маршрутизатор на основе контроллеров дл
 - [Базовый пример](#базовый-пример)
 - [Валидация](#валидация)
 - [Декораторы](#декораторы)
+- [Жизненный цикл контроллера](#жизненный-цикл-контроллера)
 - [Отладка](#отладка)
 - [Тесты](#тесты)
 
@@ -58,7 +59,7 @@ class UserController {
   @postAction('login')
   async login(
     // инъекция значений указанных полей
-    // извлеизвлекаемых из тела запроса
+    // извлекаемых из тела запроса
     @requestField('username') username?: string,
     @requestField('password') password?: string,
   ) {
@@ -345,6 +346,118 @@ class UserController {     // класс контроллера
 - `pathname: string` путь запроса, например `/myMath`
 - `body: unknown` тело запроса
 
+## Жизненный цикл контроллера
+
+Важной архитектурной особенностью модуля является управление жизненным циклом
+контроллеров, основанное на библиотеке
+[@e22m4u/js-service](https://www.npmjs.com/package/@e22m4u/js-service).
+
+#### Изоляция запросов
+
+Для каждого входящего HTTP-запроса фреймворк создает **новый, изолированный
+экземпляр контроллера**. Это гарантирует, что состояние одного запроса
+(например, данные пользователя или временные вычисления) никогда не "протечет"
+в другой, одновременно обрабатываемый запрос. Такой подход устраняет целый
+класс потенциальных ошибок, связанных с состоянием гонки (race conditions).
+
+#### Сервис-контейнер запроса
+
+Каждый экземпляр контроллера создается с помощью сервис-контейнера, который
+"живет" только в рамках одного запроса. Чтобы контроллер мог взаимодействовать
+с другими сервисами, он должен наследоваться от базового класса `Service`.
+Это дает ему доступ к методу `this.getService()` для получения зависимостей.
+
+Рассмотрим пример с сервисом аутентификации. Наша задача - идентифицировать
+пользователя в Middleware и сделать информацию о нем доступной в контроллере.
+
+**1. Создание Middleware для подготовки сервиса**
+
+Middleware - идеальное место для подготовки сервисов, специфичных для запроса.
+В данном примере мы вручную создаем экземпляр `AuthService`, выполняем
+аутентификацию, а затем регистрируем этот экземпляр в контейнере запроса
+с помощью метода `.set()`.
+
+```ts
+// src/auth.middleware.ts
+import {AuthService} from './auth.service.ts';
+import {RequestContext} from '@e22m4u/js-trie-router';
+
+export async function authMiddleware(context: RequestContext) {
+  // Получение контейнера текущего запроса
+  const requestContainer = context.container;
+  // Создание нового экземпляра AuthService
+  const authService = new AuthService();
+  // Регистрация созданного экземпляра в контейнере.
+  // Теперь любой другой сервис в рамках этого запроса
+  // сможет получить этот конкретный экземпляр.
+  requestContainer.set(AuthService, authService);
+  // Выполнение логики аутентификации (например, по токену)
+  await authService.authenticate(context.headers.authorization);
+}
+```
+
+**2. Создание `AuthService`**
+
+В этом примере `AuthService` - это простой класс. Он хранит состояние
+(`currentUser`), которое будет установлено в middleware.
+
+```ts
+// src/auth.service.ts
+export class AuthService {
+  public currentUser?: { id: number; name: string; };
+  
+  async authenticate(token?: string) {
+    // Здесь ваша логика проверки токена и поиска пользователя в БД...
+    if (token === 'valid-token') {
+      this.currentUser = { id: 1, name: 'John Doe' };
+    }
+  }
+}
+```
+
+*Примечание: если бы `AuthService` сам наследовал `Service` (чтобы, например,
+использовать `this.getService()` внутри), то его конструктор нужно было бы
+вызывать с передачей контейнера: `new AuthService(requestContainer)`.*
+
+**3. Использование сервиса в контроллере**
+
+Контроллер, унаследованный от `Service`, теперь может получить доступ
+к предварительно настроенному экземпляру `AuthService` через `this.getService()`.
+Поскольку middleware уже выполнил `.set(AuthService, authService)`,
+вызов `this.getService(AuthService)` вернет именно тот экземпляр, который
+был создан и настроен на предыдущем шаге.
+
+```ts
+// src/profile.controller.ts
+import {createError} from 'http-errors';
+import {Service} from '@e22m4u/js-service';
+import {AuthService} from './auth.service.ts';
+import {getAction} from '@e22m4u/ts-rest-router';
+import {beforeAction} from '@e22m4u/ts-rest-router';
+import {authMiddleware} from './auth.middleware.ts';
+import {restController} from '@e22m4u/ts-rest-router';
+
+@restController('profile')
+@beforeAction(authMiddleware) // применение middleware ко всем методам контроллера
+export class ProfileController extends Service {
+  @getAction('me')
+  getProfile() {
+    // Получение request-scoped экземпляра AuthService,
+    // который был создан и зарегистрирован в middleware.
+    const authService = this.getService(AuthService);
+
+    if (!authService.currentUser)
+      throw createError(401, 'Unauthorized');
+      
+    return authService.currentUser;
+  }
+}
+```
+
+Таким образом, контейнер запроса выступает в роли моста между middleware
+и контроллером, позволяя безопасно передавать состояние, изолированное
+в рамках одного HTTP-запроса.
+
 ## Отладка
 
 Установка переменной `DEBUG` включает вывод логов.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/ts-rest-router",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "REST маршрутизатор на основе контроллеров для TypeScript",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -42,9 +42,9 @@
   },
   "dependencies": {
     "@e22m4u/js-debug": "~0.2.2",
-    "@e22m4u/js-format": "~0.1.8",
-    "@e22m4u/js-service": "~0.3.6",
-    "@e22m4u/js-trie-router": "~0.1.3",
+    "@e22m4u/js-format": "~0.2.0",
+    "@e22m4u/js-service": "~0.3.7",
+    "@e22m4u/js-trie-router": "~0.1.4",
     "@e22m4u/ts-data-schema": "~0.3.1",
     "@e22m4u/ts-reflector": "~0.1.7",
     "http-errors": "~2.0.0"
@@ -52,25 +52,25 @@
   "devDependencies": {
     "@commitlint/cli": "~19.8.1",
     "@commitlint/config-conventional": "~19.8.1",
-    "@eslint/js": "~9.34.0",
+    "@eslint/js": "~9.35.0",
     "@types/chai": "~5.2.2",
     "@types/debug": "~4.1.12",
     "@types/http-errors": "~2.0.5",
     "@types/mocha": "~10.0.10",
-    "@types/node": "~24.3.0",
+    "@types/node": "~24.5.2",
     "c8": "~10.1.3",
     "chai": "~6.0.1",
-    "esbuild": "~0.25.9",
-    "eslint": "~9.34.0",
+    "esbuild": "~0.25.10",
+    "eslint": "~9.35.0",
     "eslint-config-prettier": "~10.1.8",
     "eslint-plugin-chai-expect": "~3.1.0",
     "eslint-plugin-mocha": "~11.1.0",
     "husky": "~9.1.7",
-    "mocha": "~11.7.1",
+    "mocha": "~11.7.2",
     "prettier": "~3.6.2",
     "rimraf": "~6.0.1",
     "tsx": "~4.20.5",
     "typescript": "~5.9.2",
-    "typescript-eslint": "~8.41.0"
+    "typescript-eslint": "~8.44.0"
   }
 }