@e22m4u/ts-rest-router 0.4.3 → 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,
   ) {
@@ -209,6 +210,7 @@ class UserController {
 - `@requestCookie` - определенный cookie запроса;
 - `@requestCookies` - все cookies запроса как объект;
 - `@requestContext` - доступ к контексту запроса;
+- `@requestContainer` - сервис-контейнер запроса;
 - `@requestData` - доступ к данным запроса;
 - `@httpRequest` - экземпляр `IncomingMessage`;
 - `@httpResponse` - экземпляр `ServerResponse`;
@@ -344,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/dist/cjs/index.cjs

@@ -51,6 +51,7 @@ __export(index_exports, {
   postAction: () => postAction,
   putAction: () => putAction,
   requestBody: () => requestBody,
+  requestContainer: () => requestContainer,
   requestContext: () => requestContext,
   requestCookie: () => requestCookie,
   requestCookies: () => requestCookies,
@@ -602,6 +603,10 @@ function httpResponse() {
   return requestContext("res");
 }
 __name(httpResponse, "httpResponse");
+function requestContainer() {
+  return requestContext("container");
+}
+__name(requestContainer, "requestContainer");
 
 // dist/esm/controller-registry.js
 var import_ts_data_schema4 = require("@e22m4u/ts-data-schema");
@@ -955,7 +960,9 @@ var _ControllerRegistry = class _ControllerRegistry extends DebuggableService {
           debug("No RequestDataMetadata specified for %v argument.", index);
         }
       });
-      const controller = this.getService(controllerCtor);
+      if (requestContext2.container.has(controllerCtor))
+        throw new import_js_format3.Errorf("The controller %v is already registered, which breaks controller isolation per request.", controllerCtor.name);
+      const controller = requestContext2.container.get(controllerCtor);
       return controller[actionName](...args);
     };
   }
@@ -1016,6 +1023,7 @@ var RestRouter = _RestRouter;
   postAction,
   putAction,
   requestBody,
+  requestContainer,
   requestContext,
   requestCookie,
   requestCookies,

package/dist/esm/controller-registry.js

@@ -417,7 +417,10 @@ export class ControllerRegistry extends DebuggableService {
                 }
             });
             // выполнение операции контроллера
-            const controller = this.getService(controllerCtor);
+            if (requestContext.container.has(controllerCtor))
+                throw new Errorf('The controller %v is already registered, which breaks ' +
+                    'controller isolation per request.', controllerCtor.name);
+            const controller = requestContext.container.get(controllerCtor);
             return controller[actionName](...args);
         };
     }

package/dist/esm/decorators/request-context/request-context-decorator.d.ts

@@ -14,3 +14,7 @@ export declare function httpRequest(): (target: Prototype<object>, propertyKey:
  * HttpResponse decorator.
  */
 export declare function httpResponse(): (target: Prototype<object>, propertyKey: string, indexOrDescriptor: number) => void;
+/**
+ * RequestContainer decorator.
+ */
+export declare function requestContainer(): (target: Prototype<object>, propertyKey: string, indexOrDescriptor: number) => void;

package/dist/esm/decorators/request-context/request-context-decorator.js

@@ -27,3 +27,9 @@ export function httpRequest() {
 export function httpResponse() {
     return requestContext('res');
 }
+/**
+ * RequestContainer decorator.
+ */
+export function requestContainer() {
+    return requestContext('container');
+}

package/dist/esm/decorators/request-context/request-context-decorator.spec.js

@@ -15,13 +15,10 @@ import { expect } from 'chai';
 import { httpRequest } from './request-context-decorator.js';
 import { httpResponse } from './request-context-decorator.js';
 import { requestContext } from './request-context-decorator.js';
+import { requestContainer } from './request-context-decorator.js';
 import { RequestContextReflector } from './request-context-reflector.js';
 describe('requestContext', function () {
-    it('has aliases', function () {
-        expect(httpRequest).to.be.instanceOf(Function);
-        expect(httpResponse).to.be.instanceOf(Function);
-    });
-    it('does not require options', function () {
+    it('should not require options', function () {
         class Target {
             method(prop) { }
         }
@@ -34,7 +31,7 @@ describe('requestContext', function () {
         const res = RequestContextReflector.getMetadata(Target, 'method');
         expect(res.get(0)).to.be.eql({ property: undefined });
     });
-    it('sets a given property to the target metadata', function () {
+    it('should set the given property to target metadata', function () {
         class Target {
             method(prop) { }
         }
@@ -47,4 +44,49 @@ describe('requestContext', function () {
         const res = RequestContextReflector.getMetadata(Target, 'method');
         expect(res.get(0)).to.be.eql({ property: 'res' });
     });
+    describe('httpRequest', function () {
+        it('should set the "req" property to target metadata', function () {
+            class Target {
+                method(prop) { }
+            }
+            __decorate([
+                __param(0, httpRequest()),
+                __metadata("design:type", Function),
+                __metadata("design:paramtypes", [Object]),
+                __metadata("design:returntype", void 0)
+            ], Target.prototype, "method", null);
+            const res = RequestContextReflector.getMetadata(Target, 'method');
+            expect(res.get(0)).to.be.eql({ property: 'req' });
+        });
+    });
+    describe('httpResponse', function () {
+        it('should set the "res" property to target metadata', function () {
+            class Target {
+                method(prop) { }
+            }
+            __decorate([
+                __param(0, httpResponse()),
+                __metadata("design:type", Function),
+                __metadata("design:paramtypes", [Object]),
+                __metadata("design:returntype", void 0)
+            ], Target.prototype, "method", null);
+            const res = RequestContextReflector.getMetadata(Target, 'method');
+            expect(res.get(0)).to.be.eql({ property: 'res' });
+        });
+    });
+    describe('requestContainer', function () {
+        it('should set the "container" property to target metadata', function () {
+            class Target {
+                method(prop) { }
+            }
+            __decorate([
+                __param(0, requestContainer()),
+                __metadata("design:type", Function),
+                __metadata("design:paramtypes", [Object]),
+                __metadata("design:returntype", void 0)
+            ], Target.prototype, "method", null);
+            const res = RequestContextReflector.getMetadata(Target, 'method');
+            expect(res.get(0)).to.be.eql({ property: 'container' });
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/ts-rest-router",
-  "version": "0.4.3",
+  "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"
   }
 }

package/src/controller-registry.spec.ts

@@ -13,6 +13,7 @@ import {
   RouteRegistry,
   TrieRouter,
 } from '@e22m4u/js-trie-router';
+
 import {
   afterAction,
   beforeAction,
@@ -34,6 +35,7 @@ import {
 import {expect} from 'chai';
 import {DataType} from '@e22m4u/ts-data-schema';
 import {ControllerRegistry} from './controller-registry.js';
+import {Service, ServiceContainer} from '@e22m4u/js-service';
 
 const PRE_HANDLER_1 = () => undefined;
 const PRE_HANDLER_2 = () => undefined;
@@ -969,5 +971,73 @@ describe('ControllerRegistry', function () {
       await handler(ctx);
       expect(invoked).to.be.true;
     });
+
+    it('should create a new controller instance for each request', async function () {
+      @restController()
+      class MyStatefulController {
+        public readonly instanceId: number;
+        constructor() {
+          this.instanceId = Math.random();
+        }
+        @getAction('/test')
+        myAction() {
+          return this;
+        }
+      }
+      const S = new ControllerRegistry();
+      S.addController(MyStatefulController);
+      // поиск обработчика
+      const router = S.getService(RouteRegistry);
+      const req = createRequestMock({method: HttpMethod.GET, path: '/test'});
+      const matching = router.matchRouteByRequest(req);
+      const handler = matching!.route.handler;
+      // симуляция первого запроса
+      const req1 = createRequestMock();
+      const res1 = createResponseMock();
+      const cont1 = new ServiceContainer(S.container);
+      const ctx1 = new RequestContext(cont1, req1, res1);
+      const controllerInstance1 = (await handler(ctx1)) as MyStatefulController;
+      // симуляция второго запроса
+      const req2 = createRequestMock();
+      const res2 = createResponseMock();
+      const cont2 = new ServiceContainer(S.container);
+      const ctx2 = new RequestContext(cont2, req2, res2);
+      const controllerInstance2 = (await handler(ctx2)) as MyStatefulController;
+      // проверка, что это два разных экземпляра
+      expect(controllerInstance1).to.be.instanceOf(MyStatefulController);
+      expect(controllerInstance2).to.be.instanceOf(MyStatefulController);
+      expect(controllerInstance1).to.not.equal(controllerInstance2);
+      expect(controllerInstance1.instanceId).to.not.equal(
+        controllerInstance2.instanceId,
+        'Controller instance IDs should be different',
+      );
+    });
+
+    it('should create controller using a request-scoped container parented by the application container', async function () {
+      let counter = 0;
+      const appContainer = new ServiceContainer();
+      @restController()
+      class MyStatefulController extends Service {
+        @getAction('/test')
+        myAction() {
+          expect(this.container).to.be.not.eq(appContainer);
+          expect(this.container.getParent()).to.be.eq(appContainer);
+          counter++;
+        }
+      }
+      const S = new ControllerRegistry(appContainer);
+      S.addController(MyStatefulController);
+      // поиск обработчика
+      const router = S.getService(RouteRegistry);
+      const req = createRequestMock({method: HttpMethod.GET, path: '/test'});
+      const matching = router.matchRouteByRequest(req);
+      const handler = matching!.route.handler;
+      // симуляция запроса
+      const res = createResponseMock();
+      const cont1 = new ServiceContainer(S.container);
+      const ctx1 = new RequestContext(cont1, req, res);
+      await handler(ctx1);
+      expect(counter).to.be.eq(1);
+    });
   });
 });

package/src/controller-registry.ts

@@ -501,7 +501,13 @@ export class ControllerRegistry extends DebuggableService {
           }
         });
       // выполнение операции контроллера
-      const controller = this.getService(controllerCtor);
+      if (requestContext.container.has(controllerCtor))
+        throw new Errorf(
+          'The controller %v is already registered, which breaks ' +
+            'controller isolation per request.',
+          controllerCtor.name,
+        );
+      const controller = requestContext.container.get(controllerCtor);
       return (controller as AnyObject)[actionName](...args);
     };
   }

package/src/decorators/request-context/request-context-decorator.spec.ts

@@ -3,15 +3,11 @@ import {expect} from 'chai';
 import {httpRequest} from './request-context-decorator.js';
 import {httpResponse} from './request-context-decorator.js';
 import {requestContext} from './request-context-decorator.js';
+import {requestContainer} from './request-context-decorator.js';
 import {RequestContextReflector} from './request-context-reflector.js';
 
 describe('requestContext', function () {
-  it('has aliases', function () {
-    expect(httpRequest).to.be.instanceOf(Function);
-    expect(httpResponse).to.be.instanceOf(Function);
-  });
-
-  it('does not require options', function () {
+  it('should not require options', function () {
     class Target {
       method(
         @requestContext()
@@ -22,7 +18,7 @@ describe('requestContext', function () {
     expect(res.get(0)).to.be.eql({property: undefined});
   });
 
-  it('sets a given property to the target metadata', function () {
+  it('should set the given property to target metadata', function () {
     class Target {
       method(
         @requestContext('res')
@@ -32,4 +28,43 @@ describe('requestContext', function () {
     const res = RequestContextReflector.getMetadata(Target, 'method');
     expect(res.get(0)).to.be.eql({property: 'res'});
   });
+
+  describe('httpRequest', function () {
+    it('should set the "req" property to target metadata', function () {
+      class Target {
+        method(
+          @httpRequest()
+          prop: unknown,
+        ) {}
+      }
+      const res = RequestContextReflector.getMetadata(Target, 'method');
+      expect(res.get(0)).to.be.eql({property: 'req'});
+    });
+  });
+
+  describe('httpResponse', function () {
+    it('should set the "res" property to target metadata', function () {
+      class Target {
+        method(
+          @httpResponse()
+          prop: unknown,
+        ) {}
+      }
+      const res = RequestContextReflector.getMetadata(Target, 'method');
+      expect(res.get(0)).to.be.eql({property: 'res'});
+    });
+  });
+
+  describe('requestContainer', function () {
+    it('should set the "container" property to target metadata', function () {
+      class Target {
+        method(
+          @requestContainer()
+          prop: unknown,
+        ) {}
+      }
+      const res = RequestContextReflector.getMetadata(Target, 'method');
+      expect(res.get(0)).to.be.eql({property: 'container'});
+    });
+  });
 });

package/src/decorators/request-context/request-context-decorator.ts

@@ -50,3 +50,10 @@ export function httpRequest() {
 export function httpResponse() {
   return requestContext('res');
 }
+
+/**
+ * RequestContainer decorator.
+ */
+export function requestContainer() {
+  return requestContext('container');
+}