@e22m4u/ts-rest-router 0.6.6 → 0.6.8

package/README.md

@@ -1,53 +1,31 @@
 # @e22m4u/ts-rest-router
 
-**REST-маршрутизатор на основе контроллеров и TypeScript декораторов.**
-
-Модуль `@e22m4u/ts-rest-router` позволяет создавать структурированное
-и масштабируемое REST API. В его основе лежит декларативный подход
-с использованием TypeScript декораторов для определения маршрутов,
-обработки входящих данных и управления жизненным циклом запроса.
-
-### Особенности
-
-- **Декларативная маршрутизация**  
-  Определение маршрутов непосредственно над методами контроллера с помощью
-  декораторов (`@getAction`, `@postAction` и т.д.).
-- **Типобезопасная обработка данных**  
-  Автоматическое извлечение, преобразование и валидация данных из `body`,
-  `query`, `params`, `headers` и `cookie` с привязкой к типизированным
-  аргументам методов.
-- **Встроенная валидация**  
-  Использование схем данных из
-  [@e22m4u/js-data-schema](https://www.npmjs.com/package/@e22m4u/js-data-schema)
-  для описания сложных правил проверки.
-- **Хуки (`@beforeAction`, `@afterAction`)**  
-  Поддержка хуков для выполнения сквозной логики (например, аутентификация
-  или логирование) на уровне контроллера и отдельных методов.
-- **Изоляция запросов**  
-  Обработка каждого запроса в отдельном DI-контейнере, что гарантирует
-  отсутствие конфликтов состояний и повышает надежность приложения.
-- **Производительность и гибкая архитектура**  
-  Основан на
-  [@e22m4u/js-trie-router](https://www.npmjs.com/package/@e22m4u/js-trie-router)
-  для маршрутизации на базе *префиксного дерева* и
-  [@e22m4u/js-service](https://www.npmjs.com/package/@e22m4u/js-service)
-  для внедрения зависимостей.
+![npm version](https://badge.fury.io/js/@e22m4u%2Fts-rest-router.svg)
+![license](https://img.shields.io/badge/license-mit-blue.svg)
+
+REST-маршрутизатор на основе контроллеров и TypeScript декораторов.
+
+Данный модуль позволяет создавать структурированное и масштабируемое REST API.
+В его основе лежит декларативный подход с использованием TypeScript декораторов
+для определения маршрутов, обработки входящих данных и управления жизненным
+циклом запроса.
 
 ## Содержание
 
 - [Установка](#установка)
-- [Быстрый старт: Пример сервера](#быстрый-старт-пример-сервера)
-- [Обработка данных запроса](#обработка-данных-запроса)
-  - [URL-параметры (`@requestParam`)](#url-параметры-requestparam)
-  - [Query-параметры (`@requestQuery`)](#query-параметры-requestquery)
-  - [Тело запроса (`@requestBody`, `@requestField`)](#тело-запроса-requestbody-requestfield)
-  - [Заголовки и Cookies](#заголовки-и-cookies)
-  - [Контекст запроса (`@requestContext`)](#контекст-запроса-requestcontext)
-- [Валидация и схемы данных](#валидация-и-схемы-данных)
-- [Хуки (`@beforeAction`, `@afterAction`)](#хуки-beforeaction-afteraction)
-- [Архитектура: Жизненный цикл контроллера и DI](#архитектура-жизненный-цикл-контроллера-и-di)
-- [Производительность: Префиксное дерево](#производительность-префиксное-дерево)
-- [Полный список декораторов](#полный-список-декораторов)
+- [Базовый пример](#базовый-пример)
+- [Данные запроса](#данные-запроса)
+  - [URL-параметры](#url-параметры)
+  - [Query-параметры](#query-параметры)
+  - [Тело запроса](#тело-запроса)
+  - [Заголовки](#заголовки)
+  - [Cookies](#cookies)
+  - [Контекст запроса](#контекст-запроса)
+- [Валидация данных](#валидация-данных)
+- [Хуки](#хуки)
+- [Архитектура](#архитектура)
+- [Производительность](#производительность)
+- [Декораторы](#декораторы)
 - [Отладка](#отладка)
 - [Тесты](#тесты)
 - [Лицензия](#лицензия)
@@ -70,7 +48,7 @@ npm install @e22m4u/ts-rest-router
 }
 ```
 
-## Быстрый старт: Пример сервера
+## Базовый пример
 
 Пример создания простого сервера для управления списком пользователей.
 
@@ -78,42 +56,40 @@ npm install @e22m4u/ts-rest-router
 
 ```ts
 import {
-  restController,
+  DataType,
   getAction,
   postAction,
   requestBody,
-  DataType,
+  restController,
 } from '@e22m4u/ts-rest-router';
 
-// Временное хранилище данных
-const users = [
-  {id: 1, name: 'John Doe'},
-];
+// временное хранилище данных
+const users = [{id: 1, name: 'John Doe'}];
 
-// 1. Декоратор @restController определяет класс как контроллер
-//    и устанавливает базовый путь для всех его маршрутов.
+// декоратор @restController определяет класс как контроллер
+// и устанавливает базовый путь для всех его маршрутов
 @restController('users')
 export class UserController {
-  // 2. Декоратор @getAction создает маршрут для GET-запросов.
-  //    Полный путь: GET /users
+  // декоратор @getAction создает маршрут для GET-запросов,
+  // полный путь: GET /users
   @getAction()
   getAllUsers() {
-    // Результат автоматически сериализуется в JSON
+    // результат автоматически сериализуется в JSON
     return users;
   }
 
-  // 3. Декоратор @postAction создает маршрут для POST-запросов.
-  //    Полный путь: POST /users
+  // декоратор @postAction создает маршрут для POST-запросов,
+  // полный путь: POST /users
   @postAction()
   createUser(
-    // 4. Декоратор @requestBody извлекает тело запроса,
-    //    проверяет его по схеме и передает в аргумент `newUser`.
+    // декоратор @requestBody извлекает тело запроса,
+    // проверяет его по схеме и передает в аргумент `newUser`
     @requestBody({
       type: DataType.OBJECT,
       properties: {
         name: {
           type: DataType.STRING,
-          required: true
+          required: true,
         },
       },
     })
@@ -121,7 +97,7 @@ export class UserController {
   ) {
     const user = {id: users.length + 1, ...newUser};
     users.push(user);
-    // Возвращаемый объект будет отправлен клиенту как JSON.
+    // возвращаемый объект будет отправлен клиенту как JSON
     return user;
   }
 }
@@ -135,20 +111,19 @@ import {UserController} from './user.controller';
 import {RestRouter} from '@e22m4u/ts-rest-router';
 
 async function bootstrap() {
-  // Создание экземпляра роутера
+  // создание экземпляра роутера
   const router = new RestRouter();
-  // Регистрация контроллера
+  // регистрация контроллера
   router.addController(UserController);
-
-  // Создание HTTP-сервера с обработчиком запросов из роутера
+  // создание HTTP-сервера с обработчиком запросов из роутера
   const server = http.createServer(router.requestListener);
 
-  // Запуск сервера
+  // запуск сервера
   server.listen(3000, () => {
     console.log('Server is running on http://localhost:3000');
     console.log('Try GET http://localhost:3000/users');
     console.log(
-      'Try POST http://localhost:3000/users with body {"name": "Jane Doe"}'
+      'Try POST http://localhost:3000/users with body {"name": "Jane Doe"}',
     );
   });
 }
@@ -156,50 +131,74 @@ async function bootstrap() {
 bootstrap();
 ```
 
-## Обработка данных запроса
+## Данные запроса
+
+Модуль предоставляет TypeScript декораторы для инъекции данных входящего
+запроса через аргументы метода контроллера.
+
+### URL-параметры
+
+Извлечение динамических частей URL (например, `:id`).  
+
+Декораторы:
 
-Модуль предоставляет удобные и типобезопасные механизмы для доступа
-к данным входящего запроса.
+- `@requestParam(name, schema)`  
+  \- извлечение одного параметра;
 
-### URL-параметры (`@requestParam`)
+- `@requestParams(schema)`  
+  \- извлечение всех URL-параметров в виде объекта;
 
-Используются для извлечения динамических частей URL (например, `:id`).
+Пример:
 
 ```ts
-import {getAction, requestParam, DataType} from '@e22m4u/ts-rest-router';
+import {
+  DataType,
+  getAction,
+  requestParam,
+  restController,
+} from '@e22m4u/ts-rest-router';
 
 @restController('articles')
 class ArticleController {
-  // Маршрут: GET /articles/42
+  // GET /articles/42
   @getAction(':id')
   getArticleById(
-    // Извлечение параметра 'id' с проверкой на соответствие
-    // типу "number"
+    // извлечение параметра 'id' с проверкой
+    // на соответствие типу "number"
     @requestParam('id', DataType.NUMBER) id: number,
   ) {
-    // Если id не является числом, фреймворк вернет ошибку
-    // 400 Bad Request
+    // если id не является числом,
+    // то выбрасывается ошибка 400 Bad Request
     return {articleId: id, content: '...'};
   }
 }
 ```
 
-**Декораторы:**
+### Query-параметры
+
+Извлечение параметров из строки запроса (например, `?sort=desc`).  
 
-- `@requestParam(name, schema)` - извлечение одного параметра;
-- `@requestParams(schema)` - извлечение всех URL-параметров в виде объекта;
+Декораторы:
 
-### Query-параметры (`@requestQuery`)
+- `@requestQuery(name, schema)`  
+  \- извлечение одного query-параметра;
 
-Применяются для извлечения параметров из строки запроса
-(например, `?sort=desc`).
+- `@requestQueries(schema)`  
+  \- извлечение всех query-параметров в виде объекта;
+
+Пример:
 
 ```ts
-import {getAction, requestQuery, DataType} from '@e22m4u/ts-rest-router';
+import {
+  DataType,
+  getAction,
+  requestQuery,
+  restController,
+} from '@e22m4u/ts-rest-router';
 
 @restController('products')
 class ProductController {
-  // Маршрут: GET /products/search?q=phone&limit=10
+  // GET /products/search?q=phone&limit=10
   @getAction('search')
   searchProducts(
     @requestQuery('q', {
@@ -213,19 +212,14 @@ class ProductController {
     })
     limit: number,
   ) {
-    // searchTerm будет 'phone', limit будет 10.
-    // При отсутствии 'q' будет ошибка. При отсутствии 'limit'
-    // будет использовано значение по умолчанию 20.
+    // searchTerm будет 'phone', limit будет 10;
+    // при отсутствии 'q' будет ошибка;
+    // при отсутствии 'limit' будет использовано значение по умолчанию 20;
     return {results: [], query: {searchTerm, limit}};
   }
 }
 ```
 
-**Декораторы:**
-
-- `@requestQuery(name, schema)` - извлечение одного query-параметра;
-- `@requestQueries(schema)` - извлечение всех query-параметров в виде объекта;
-
 **Именование Query-декораторов**
 
 Разделение на декораторы в единственном `@requestQuery` и множественном
@@ -235,21 +229,32 @@ class ProductController {
 извлечения и валидации отдельных значений, в то время как множественное число
 служит для получения всех данных в виде единого объекта.
 
-### Тело запроса (`@requestBody`, `@requestField`)
+### Тело запроса
+
+Извлечение тела запроса POST, PUT, PATCH методов.
+
+Декораторы:
+
+- `@requestBody(schema)`  
+  \- извлечение тела запроса;
+
+- `@requestField(name, schema)`  
+  \- извлечение отдельного поля из тела запроса;
 
-Для работы с данными, отправленными в теле POST, PUT, PATCH запросов.
+Пример:
 
 ```ts
 import {
+  DataType,
   postAction,
   requestBody,
   requestField,
-  DataType,
+  restController,
 } from '@e22m4u/ts-rest-router';
 
 @restController('users')
 class UserController {
-  // Пример с @requestBody: получение и валидация всего тела запроса
+  // пример с @requestBody: получение и валидация всего тела запроса
   @postAction()
   createUser(
     @requestBody({
@@ -265,12 +270,15 @@ class UserController {
         },
       },
     })
-    body: {username: string; email: string},
+    body: {
+      username: string;
+      email: string;
+    },
   ) {
     return {id: 1, ...body};
   }
 
-  // Пример с @requestField: получение только одного поля из тела
+  // пример с @requestField: получение только одного поля из тела
   @postAction('login')
   login(
     @requestField('username', DataType.STRING) username: string,
@@ -282,19 +290,89 @@ class UserController {
 }
 ```
 
-**Декораторы:**
+### Заголовки
+
+Извлечение HTTP-заголовков запроса.
+
+Декораторы:
+
+- `@requestHeader(name, schema)`  
+  \- извлечение отдельного заголовка;
+
+- `@requestHeaders(schema)`  
+  \- извлечение всех заголовков;
+
+Пример:
+
+```ts
+import {
+  DataType,
+  getAction,
+  requestHeader,
+} from '@e22m4u/ts-rest-router';
+
+@restController('content')
+class ContentController {
+  // GET /content
+  @getAction()
+  getContentForLanguage(
+    // извлечение заголовка 'Accept-Language'
+    // со значением по умолчанию 'en'
+    @requestHeader('Accept-Language', {
+      type: DataType.STRING,
+      default: 'en',
+    })
+    lang: string,
+  ) {
+    // lang будет 'en', если заголовок отсутствует,
+    // или будет содержать значение заголовка, например 'ru-RU'
+    return {content: `Content in ${lang} language`};
+  }
+}
+```
+
+### Cookies
 
-- `@requestBody(schema)` - извлечение тела запроса;
-- `@requestField(name, schema)` - извлечение отдельного поля из тела запроса;
+Извлечение разобранного заголовка Cookies входящего запроса.
 
-### Заголовки и Cookies
+Декораторы:
 
-Работа с заголовками и cookies осуществляется аналогичным образом:
+- `@requestCookie(name, schema)`  
+  \- извлечение отдельного Cookie по ключу;
+
+- `@requestCookies(schema)`  
+  \- извлечение всех Cookies;
+
+Пример:
+
+```ts
+import {
+  DataType,
+  getAction,
+  requestCookie,
+} from '@e22m4u/ts-rest-router';
 
-- `@requestHeader(name, schema)` / `@requestHeaders(schema)`
-- `@requestCookie(name, schema)` / `@requestCookies(schema)`
+@restController('session')
+class SessionController {
+  // GET /session/info
+  @getAction('info')
+  getSessionInfo(
+    // извлечение cookie с именем 'sessionId'
+    // и проверка, что значение является строкой
+    @requestCookie('sessionId', {
+      type: DataType.STRING,
+      required: true,
+    })
+    sessionId: string,
+  ) {
+    // если cookie 'sessionId' отсутствует,
+    // будет выброшена ошибка 400 Bad Request
+    return {sessionId, info: 'User session data...'};
+  }
+}
+```
 
-### Контекст запроса (`@requestContext`)
+### Контекст запроса
 
 Для доступа к "сырым" объектам запроса/ответа Node.js или другим частям
 контекста используются следующие декораторы:
@@ -303,11 +381,14 @@ class UserController {
 - `@requestContext('req')` - инъекция нативного `IncomingMessage`;
 - `@requestContext('res')` - инъекция нативного `ServerResponse`;
 - `@requestContext('container')` - инъекция DI-контейнера запроса;
-- **Алиасы:** `@httpRequest()`, `@httpResponse()`, `@requestContainer()`;
+- Псевдонимы: `@httpRequest()`, `@httpResponse()`, `@requestContainer()`;
 
 ```ts
-import {getAction, requestContext} from '@e22m4u/ts-rest-router';
-import {RequestContext} from '@e22m4u/js-trie-router';
+import {
+  getAction,
+  requestContext,
+  RequestContext,
+} from '@e22m4u/ts-rest-router';
 
 @restController('system')
 class SystemController {
@@ -323,14 +404,14 @@ class SystemController {
 }
 ```
 
-## Валидация и схемы данных
+## Валидация данных
 
 Модуль интегрирован с
 [@e22m4u/js-data-schema](https://www.npmjs.com/package/@e22m4u/js-data-schema)
 для гибкой проверки данных. Это дает возможность определять типы данных
 и сложные правила.
 
-**Базовые типы `DataType`:**
+Базовые типы:
 
 - `DataType.ANY`
 - `DataType.STRING`
@@ -339,23 +420,28 @@ class SystemController {
 - `DataType.ARRAY`
 - `DataType.OBJECT`
 
-Для более сложных проверок используется объект `DataSchema`:
+Для более сложных проверок используется объект схемы:
 
 ```ts
 type DataSchema = {
-  type: DataType; // Обязательное поле
-  required?: boolean; // Значение не может быть null или undefined
-  default?: unknown; // Значение по умолчанию, если `required: false`
-  items?: DataSchema; // Схема для элементов массива (для type: DataType.ARRAY)
-  properties?: {[key: string]: DataSchema}; // Схема для свойств объекта
-  validate?: (value: any) => boolean | string; // Пользовательская функция
-}
+  type: DataType; // обязательное поле
+  required?: boolean; // значение не может быть null или undefined
+  default?: unknown; // значение по умолчанию, если `required: false`
+  items?: DataSchema; // схема для элементов массива (для type: DataType.ARRAY)
+  properties?: {[key: string]: DataSchema}; // схема для свойств объекта
+  validate?: (value: any) => boolean | string; // пользовательская функция
+};
 ```
 
-**Пример сложной валидации:**
+Пример сложной валидации:
 
 ```ts
-import {postAction, requestBody, DataType} from '@e22m4u/ts-rest-router';
+import {
+  DataType,
+  postAction,
+  requestBody,
+  restController,
+} from '@e22m4u/ts-rest-router';
 
 @restController('orders')
 class OrderController {
@@ -371,68 +457,74 @@ class OrderController {
         products: {
           type: DataType.ARRAY,
           required: true,
-          // Описание схемы для каждого элемента массива:
+          // описание схемы для каждого элемента массива
           items: {
             type: DataType.OBJECT,
             properties: {
               id: {
                 type: DataType.NUMBER,
-                required: true
+                required: true,
               },
               quantity: {
                 type: DataType.NUMBER,
                 required: true,
-                // Валидатор: количество должно быть больше 0
-                validate: (qty) => qty > 0 || 'Quantity must be positive',
+                // валидатор: количество должно быть больше 0
+                validate: qty => qty > 0 || 'Quantity must be positive',
               },
             },
           },
         },
       },
     })
-    orderData: { /* ... */ },
+    orderData: {
+      /* ... */
+    },
   ) {
     // ...
   }
 }
 ```
 
-## Хуки (`@beforeAction`, `@afterAction`)
+## Хуки
+
+Функции, выполняющиеся до или после основного метода контроллера именуются
+«Хуками». Они предназначены для сквозной логики, такой как аутентификация,
+логирование или модификация ответа. Применение хуков возможно как ко всему
+контроллеру, так и к отдельному методу.
 
-Хуки - это функции, выполняющиеся до (`@beforeAction`) или после
-(`@afterAction`) основного метода контроллера. Они предназначены для
-сквозной логики, такой как аутентификация, логирование или модификация
-ответа.
+Декораторы:
 
-Применение хуков возможно как ко всему контроллеру, так и к отдельному
-методу.
+- `@beforeAction(preHandler)` - выполняется перед методом контроллера;
+- `@afterAction(postHandler)` - выполняется после метода контроллера;
+
+Пример:
 
 ```ts
-import {RequestContext} from '@e22m4u/js-trie-router';
 import createError from 'http-errors';
+import {RequestContext} from '@e22m4u/ts-rest-router';
 
-// Хук для проверки аутентификации
+// хук для проверки аутентификации
 async function authHook(ctx: RequestContext) {
   const token = ctx.headers.authorization;
   if (!token /* || !isValidToken(token) */) {
-    // Выброс ошибки прерывает выполнение и отправляет клиенту
-    // соответствующий HTTP-статус.
+    // выброс ошибки прерывает выполнение и отправляет
+    // клиенту соответствующий HTTP-статус
     throw createError(401, 'Unauthorized');
   }
 }
 
-// Хук для логирования и модификации ответа
+// хук для логирования и модификации ответа
 async function loggerHook(ctx: RequestContext, data: any) {
   console.log(`Response for ${ctx.pathname}:`, data);
-  // Хуки @afterAction могут модифицировать ответ
+  // хуки @afterAction могут модифицировать ответ
   return {...data, timestamp: new Date()};
 }
 
-@beforeAction(authHook) // Применение ко всем методам контроллера
+@beforeAction(authHook) // применение ко всем методам контроллера
 @restController('profile')
 class ProfileController {
   @getAction('me')
-  @afterAction(loggerHook) // Применение только к этому методу
+  @afterAction(loggerHook) // применение только к этому методу
   getMyProfile() {
     return {id: 1, name: 'Current User'};
   }
@@ -444,23 +536,23 @@ class ProfileController {
 }
 ```
 
-## Архитектура: Жизненный цикл контроллера и DI
+## Архитектура
 
 Понимание архитектурных принципов `ts-rest-router` является ключом
 к созданию надежных и масштабируемых приложений. Модуль построен на
 базе библиотеки `@e22m4u/js-service`, реализующей паттерн
 Service Locator / Dependency Injection.
 
-#### Принцип №1: Изоляция запросов
+#### Изоляция запросов
 
-Для **каждого** входящего HTTP-запроса создается **новый, изолированный
-экземпляр контроллера**. Этот фундаментальный принцип гарантирует, что
+Для каждого входящего HTTP-запроса создается новый, изолированный
+экземпляр контроллера. Этот фундаментальный принцип гарантирует, что
 состояние одного запроса (например, данные аутентифицированного
 пользователя) никогда не будет разделено с другим, одновременно
 обрабатываемым запросом. Это устраняет целый класс потенциальных
 ошибок, связанных с состоянием гонки.
 
-#### Принцип №2: Request-Scoped Service Container
+#### Внедрение зависимостей
 
 Каждый экземпляр контроллера создается с помощью своего собственного
 DI-контейнера, который существует только в рамках одного запроса. Чтобы
@@ -471,31 +563,31 @@ DI-контейнера, который существует только в р
 
 **Практический пример с сервисом аутентификации:**
 
-**Шаг 1: Создание хука для подготовки сервиса**
+1\. Создание хука для подготовки сервиса.
 
-Хуки - идеальное место для подготовки сервисов, специфичных для запроса.
-В этом примере хук `@beforeAction` создает экземпляр `AuthService`,
+С помощью хука можно подготовить сервис, специфичный для каждого запроса.
+В данном примере хук `@beforeAction` создает экземпляр `AuthService`,
 выполняет аутентификацию и регистрирует его в контейнере запроса.
 
 ```ts
 // src/auth.hook.ts
 import {AuthService} from './auth.service';
-import {RequestContext} from '@e22m4u/js-trie-router';
+import {RequestContext} from '@e22m4u/ts-rest-router';
 
 export async function authHook(context: RequestContext) {
   const requestContainer = context.container;
-  // Создание сервиса с передачей ему контейнера запроса
+  // создание сервиса с передачей ему контейнера запроса
   const authService = new AuthService(requestContainer);
-  // Регистрация созданного экземпляра в контейнере.
-  // Теперь любой другой сервис в рамках этого запроса
-  // сможет получить этот конкретный экземпляр.
+  // регистрация созданного экземпляра в контейнере
+  // (теперь любой другой сервис в рамках текущего
+  // запроса сможет получить данный экземпляр)
   requestContainer.set(AuthService, authService);
-  // Выполнение логики аутентификации
+  // выполнение логики аутентификации
   await authService.authenticate(context.headers.authorization);
 }
 ```
 
-**Шаг 2: Создание `AuthService`**
+2\. Создание `AuthService`.
 
 `AuthService` наследуется от `Service`, что позволяет ему запрашивать другие
 зависимости (например, `this.getService(DatabaseService)`).
@@ -505,18 +597,19 @@ export async function authHook(context: RequestContext) {
 import {Service} from '@e22m4u/js-service';
 
 export class AuthService extends Service {
-  public currentUser?: {id: number; name: string;};
+  public currentUser?: {id: number; name: string};
 
   async authenticate(token?: string) {
-    // Логика проверки токена и поиска пользователя в БД...
+    // логика проверки токена и поиска
+    // пользователя в базе данных...
     if (token === 'valid-token') {
-      this.currentUser = { id: 1, name: 'John Doe' };
+      this.currentUser = {id: 1, name: 'John Doe'};
     }
   }
 }
 ```
 
-**Шаг 3: Использование сервиса в контроллере**
+3\. Использование сервиса в контроллере.
 
 Контроллер, унаследованный от `Service`, теперь может получить
 доступ к предварительно настроенному экземпляру `AuthService`
@@ -528,24 +621,21 @@ import {authHook} from './auth.hook';
 import createError from 'http-errors';
 import {Service} from '@e22m4u/js-service';
 import {AuthService} from './auth.service';
-import {
-  getAction,
-  restController,
-  beforeAction,
-} from '@e22m4u/ts-rest-router';
+import {getAction, beforeAction, restController} from '@e22m4u/ts-rest-router';
 
 @beforeAction(authHook)
 @restController('profile')
 export class ProfileController extends Service {
   @getAction('me')
   getProfile() {
-    // Получение request-scoped экземпляра AuthService,
-    // который был создан и зарегистрирован в хуке.
+    // получение request-scoped экземпляра AuthService,
+    // который был создан и зарегистрирован в хуке
     const authService = this.getService(AuthService);
 
-    if (!authService.currentUser)
+    if (!authService.currentUser) {
       throw createError(401, 'Unauthorized');
-      
+    }
+
     return authService.currentUser;
   }
 }
@@ -555,12 +645,12 @@ export class ProfileController extends Service {
 и контроллером, позволяя безопасно передавать состояние, изолированное
 в рамках одного HTTP-запроса.
 
-## Производительность: Префиксное дерево
+## Производительность
 
 В основе данного модуля лежит
 [@e22m4u/js-trie-router](https://www.npmjs.com/package/@e22m4u/js-trie-router),
 который использует структуру данных
-**префиксного дерева** ([Trie](https://en.wikipedia.org/wiki/Trie))
+*префиксного дерева ([Trie](https://en.wikipedia.org/wiki/Trie))*
 для хранения маршрутов и их сопоставления. Такое архитектурное решение
 обеспечивает высокую производительность, особенно в приложениях
 с большим количеством маршрутов.
@@ -576,41 +666,39 @@ export class ProfileController extends Service {
 маршрутизатор не перебирает все существующие маршруты. Вместо этого
 он последовательно спускается по дереву:
 
-1.  Находит корневой узел для метода `GET`.
-2.  От него переходит к дочернему узлу `users`.
-3.  Далее, не найдя статического узла `123`, он ищет динамический
-    узел (`:id`) и сопоставляет его, сохраняя `123` как значение
-    параметра `id`.
-4.  Наконец, он переходит к узлу `posts` и находит совпадение.
-
-#### Преимущества для производительности
-
-1.  **Эффективный поиск (O(k))**  
-    Самое главное преимущество — скорость поиска. Вместо того чтобы
-    перебирать массив из `N` маршрутов и проверять каждый с помощью
-    регулярного выражения (сложность `O(N)`), префиксное дерево
-    находит совпадение за время, пропорциональное количеству сегментов
-    `k` в URL-пути (сложность `O(k)`). Это означает, что производительность
-    поиска **не падает** с ростом общего числа маршрутов в приложении.
-
-2.  **Быстрая обработка 404 (ранний выход)**  
-    Если приходит запрос на несуществующий путь, например
-    `/users/123/comments`, поиск по дереву прекратится сразу после
-    того, как маршрутизатор не найдет дочерний узел `comments`
-    у узла `:id`. Ему не нужно проверять остальные сотни маршрутов,
-    чтобы убедиться, что совпадений нет. Это делает обработку
-    ненайденных маршрутов (404) почти мгновенной.
-
-3.  **Оптимизация для статических и динамических маршрутов**  
-    При поиске маршрутизатор всегда отдает приоритет статическим
-    сегментам перед динамическими. Маршрут `/users/me` всегда будет
-    найден раньше и быстрее, чем `/users/:id` при запросе `/users/me`,
-    поскольку не требуется проверка на соответствие шаблону.
-
-Этот подход делает `ts-rest-router` производительным решением для крупных
-приложений с большим количеством маршрутов.
-
-## Полный список декораторов
+1. Находит корневой узел для метода `GET`.
+2. От него переходит к дочернему узлу `users`.
+3. Далее, не найдя статического узла `123`, он ищет динамический
+   узел (`:id`) и сопоставляет его, сохраняя `123` как значение
+   параметра `id`.
+4. Наконец, он переходит к узлу `posts` и находит совпадение.
+
+**Эффективный поиск маршрута O(k)**
+
+Самое главное преимущество - скорость поиска. Вместо того чтобы
+перебирать массив из `N` маршрутов и проверять каждый с помощью
+регулярного выражения (сложность `O(N)`), префиксное дерево
+находит совпадение за время, пропорциональное количеству сегментов
+`K` в URL-пути (сложность `O(K)`). Это означает, что производительность
+поиска не падает с ростом общего числа маршрутов в приложении.
+
+**Быстрая обработка 404 (ранний выход)**
+
+Если приходит запрос на несуществующий путь, например
+`/users/123/comments`, поиск по дереву прекратится сразу после
+того, как маршрутизатор не найдет дочерний узел `comments`
+у узла `:id`. Ему не нужно проверять остальные сотни маршрутов,
+чтобы убедиться, что совпадений нет. Это делает обработку
+неопределенных маршрутов (404) почти мгновенной.
+
+**Оптимизация для статических и динамических маршрутов**  
+
+При поиске маршрутизатор всегда отдает приоритет статическим
+сегментам перед динамическими. Маршрут `/users/me` всегда будет
+найден раньше и быстрее, чем `/users/:id` при запросе `/users/me`,
+поскольку не требуется проверка на соответствие шаблону.
+
+## Декораторы
 
 #### Контроллер и методы:
 
@@ -667,4 +755,4 @@ npm run test
 
 ## Лицензия
 
-MIT
+MIT

package/dist/cjs/index.cjs

@@ -32,7 +32,7 @@ __export(index_exports, {
   RESPONSE_BODY_METADATA_KEY: () => RESPONSE_BODY_METADATA_KEY,
   REST_ACTIONS_METADATA_KEY: () => REST_ACTIONS_METADATA_KEY,
   REST_CONTROLLER_METADATA_KEY: () => REST_CONTROLLER_METADATA_KEY,
-  RequestContext: () => import_js_trie_router4.RequestContext,
+  RequestContext: () => import_js_trie_router5.RequestContext,
   RequestContextReflector: () => RequestContextReflector,
   RequestDataReflector: () => RequestDataReflector,
   RequestDataSource: () => RequestDataSource,
@@ -40,6 +40,7 @@ __export(index_exports, {
   RestActionReflector: () => RestActionReflector,
   RestControllerReflector: () => RestControllerReflector,
   RestRouter: () => RestRouter,
+  RouterHookType: () => import_js_trie_router4.RouterHookType,
   afterAction: () => afterAction,
   beforeAction: () => beforeAction,
   deleteAction: () => deleteAction,
@@ -204,7 +205,7 @@ var RequestDataSource;
   RequestDataSource2["PARAMS"] = "params";
   RequestDataSource2["QUERY"] = "query";
   RequestDataSource2["HEADERS"] = "headers";
-  RequestDataSource2["COOKIE"] = "cookie";
+  RequestDataSource2["COOKIES"] = "cookies";
   RequestDataSource2["BODY"] = "body";
 })(RequestDataSource || (RequestDataSource = {}));
 var REQUEST_DATA_METADATA_KEY = new import_ts_reflector5.MetadataKey("requestDataMetadataKey");
@@ -304,8 +305,8 @@ var requestQueries = createRequestDataDecoratorWithSource(RequestDataSource.QUER
 var requestQuery = createRequestDataPropertyDecoratorWithSource(RequestDataSource.QUERY);
 var requestHeaders = createRequestDataDecoratorWithSource(RequestDataSource.HEADERS);
 var requestHeader = createRequestDataPropertyDecoratorWithSource(RequestDataSource.HEADERS);
-var requestCookies = createRequestDataDecoratorWithSource(RequestDataSource.COOKIE);
-var requestCookie = createRequestDataPropertyDecoratorWithSource(RequestDataSource.COOKIE);
+var requestCookies = createRequestDataDecoratorWithSource(RequestDataSource.COOKIES);
+var requestCookie = createRequestDataPropertyDecoratorWithSource(RequestDataSource.COOKIES);
 var requestBody = createRequestDataDecoratorWithSource(RequestDataSource.BODY);
 var requestField = createRequestDataPropertyDecoratorWithSource(RequestDataSource.BODY);
 
@@ -895,7 +896,7 @@ var _ControllerRegistry = class _ControllerRegistry extends DebuggableService {
             case RequestDataSource.HEADERS:
               data = requestContext2.headers;
               break;
-            case RequestDataSource.COOKIE:
+            case RequestDataSource.COOKIES:
               data = requestContext2.cookies;
               break;
             case RequestDataSource.BODY:
@@ -980,6 +981,7 @@ var RestRouter = _RestRouter;
 
 // dist/esm/index.js
 var import_js_trie_router4 = require("@e22m4u/js-trie-router");
+var import_js_trie_router5 = require("@e22m4u/js-trie-router");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AFTER_ACTION_METADATA_KEY,
@@ -1001,6 +1003,7 @@ var import_js_trie_router4 = require("@e22m4u/js-trie-router");
   RestActionReflector,
   RestControllerReflector,
   RestRouter,
+  RouterHookType,
   afterAction,
   beforeAction,
   deleteAction,

package/dist/esm/controller-registry.js

@@ -372,7 +372,7 @@ export class ControllerRegistry extends DebuggableService {
                         case RequestDataSource.HEADERS:
                             data = requestContext.headers;
                             break;
-                        case RequestDataSource.COOKIE:
+                        case RequestDataSource.COOKIES:
                             data = requestContext.cookies;
                             break;
                         case RequestDataSource.BODY:

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

@@ -82,7 +82,7 @@ export const requestQueries = createRequestDataDecoratorWithSource(RequestDataSo
 export const requestQuery = createRequestDataPropertyDecoratorWithSource(RequestDataSource.QUERY);
 export const requestHeaders = createRequestDataDecoratorWithSource(RequestDataSource.HEADERS);
 export const requestHeader = createRequestDataPropertyDecoratorWithSource(RequestDataSource.HEADERS);
-export const requestCookies = createRequestDataDecoratorWithSource(RequestDataSource.COOKIE);
-export const requestCookie = createRequestDataPropertyDecoratorWithSource(RequestDataSource.COOKIE);
+export const requestCookies = createRequestDataDecoratorWithSource(RequestDataSource.COOKIES);
+export const requestCookie = createRequestDataPropertyDecoratorWithSource(RequestDataSource.COOKIES);
 export const requestBody = createRequestDataDecoratorWithSource(RequestDataSource.BODY);
 export const requestField = createRequestDataPropertyDecoratorWithSource(RequestDataSource.BODY);

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

@@ -126,7 +126,7 @@ describe('requestData', function () {
                 ], Target.prototype, "myMethod", null);
                 const res = RequestDataReflector.getMetadata(Target, 'myMethod');
                 expect(res.get(0)).to.be.eql({
-                    source: RequestDataSource.COOKIE,
+                    source: RequestDataSource.COOKIES,
                     schema: { type: DataType.ANY },
                 });
             });
@@ -554,7 +554,7 @@ describe('requestData', function () {
                 ], Target.prototype, "myMethod", null);
                 const res = RequestDataReflector.getMetadata(Target, 'myMethod');
                 expect(res.get(0)).to.be.eql({
-                    source: RequestDataSource.COOKIE,
+                    source: RequestDataSource.COOKIES,
                     schema: {
                         type: DataType.OBJECT,
                         properties: {
@@ -580,7 +580,7 @@ describe('requestData', function () {
                 ], Target.prototype, "myMethod", null);
                 const res = RequestDataReflector.getMetadata(Target, 'myMethod');
                 expect(res.get(0)).to.be.eql({
-                    source: RequestDataSource.COOKIE,
+                    source: RequestDataSource.COOKIES,
                     schema: {
                         type: DataType.OBJECT,
                         properties: {
@@ -609,7 +609,7 @@ describe('requestData', function () {
                 ], Target.prototype, "myMethod", null);
                 const res = RequestDataReflector.getMetadata(Target, 'myMethod');
                 expect(res.get(0)).to.be.eql({
-                    source: RequestDataSource.COOKIE,
+                    source: RequestDataSource.COOKIES,
                     schema: {
                         type: DataType.OBJECT,
                         properties: {
@@ -637,7 +637,7 @@ describe('requestData', function () {
                 ], Target.prototype, "myMethod", null);
                 const mdMap = RequestDataReflector.getMetadata(Target, 'myMethod');
                 const md = mdMap.get(0);
-                expect(md.source).to.be.eq(RequestDataSource.COOKIE);
+                expect(md.source).to.be.eq(RequestDataSource.COOKIES);
                 expect(md.schema).to.be.a('function');
                 expect(md.property).to.be.eq(propertyKey);
                 const res1 = md.schema;

package/dist/esm/decorators/request-data/request-data-metadata.d.ts

@@ -7,7 +7,7 @@ export declare enum RequestDataSource {
     PARAMS = "params",
     QUERY = "query",
     HEADERS = "headers",
-    COOKIE = "cookie",
+    COOKIES = "cookies",
     BODY = "body"
 }
 /**

package/dist/esm/decorators/request-data/request-data-metadata.js

@@ -7,7 +7,7 @@ export var RequestDataSource;
     RequestDataSource["PARAMS"] = "params";
     RequestDataSource["QUERY"] = "query";
     RequestDataSource["HEADERS"] = "headers";
-    RequestDataSource["COOKIE"] = "cookie";
+    RequestDataSource["COOKIES"] = "cookies";
     RequestDataSource["BODY"] = "body";
 })(RequestDataSource || (RequestDataSource = {}));
 /**

package/dist/esm/index.d.ts

@@ -4,6 +4,7 @@ export * from './decorators/index.js';
 export * from './data-schema-types.js';
 export * from './controller-registry.js';
 export { RouteHandler } from '@e22m4u/js-trie-router';
+export { RouterHookType } from '@e22m4u/js-trie-router';
 export { RequestContext } from '@e22m4u/js-trie-router';
 export { RoutePreHandler } from '@e22m4u/js-trie-router';
 export { RoutePostHandler } from '@e22m4u/js-trie-router';

package/dist/esm/index.js

@@ -3,4 +3,5 @@ export * from './errors/index.js';
 export * from './decorators/index.js';
 export * from './data-schema-types.js';
 export * from './controller-registry.js';
+export { RouterHookType } from '@e22m4u/js-trie-router';
 export { RequestContext } from '@e22m4u/js-trie-router';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/ts-rest-router",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Декларативный REST-маршрутизатор на основе контроллеров для TypeScript",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -44,7 +44,7 @@
     "@e22m4u/js-data-schema": "~0.4.6",
     "@e22m4u/js-debug": "~0.3.2",
     "@e22m4u/js-format": "~0.2.0",
-    "@e22m4u/js-service": "~0.4.4",
+    "@e22m4u/js-service": "~0.4.5",
     "@e22m4u/js-trie-router": "~0.3.4",
     "@e22m4u/ts-reflector": "~0.1.8",
     "http-errors": "~2.0.0"
@@ -52,25 +52,25 @@
   "devDependencies": {
     "@commitlint/cli": "~20.1.0",
     "@commitlint/config-conventional": "~20.0.0",
-    "@eslint/js": "~9.38.0",
+    "@eslint/js": "~9.39.1",
     "@types/chai": "~5.2.3",
     "@types/debug": "~4.1.12",
     "@types/http-errors": "~2.0.5",
     "@types/mocha": "~10.0.10",
-    "@types/node": "~24.9.2",
+    "@types/node": "~24.10.0",
     "c8": "~10.1.3",
     "chai": "~6.2.0",
-    "esbuild": "~0.25.11",
-    "eslint": "~9.38.0",
+    "esbuild": "~0.25.12",
+    "eslint": "~9.39.1",
     "eslint-config-prettier": "~10.1.8",
     "eslint-plugin-chai-expect": "~3.1.0",
     "eslint-plugin-mocha": "~11.2.0",
     "husky": "~9.1.7",
-    "mocha": "~11.7.4",
+    "mocha": "~11.7.5",
     "prettier": "~3.6.2",
-    "rimraf": "~6.0.1",
+    "rimraf": "~6.1.0",
     "tsx": "~4.20.6",
     "typescript": "~5.9.3",
-    "typescript-eslint": "~8.46.2"
+    "typescript-eslint": "~8.46.3"
   }
 }

package/src/controller-registry.ts

@@ -450,7 +450,7 @@ export class ControllerRegistry extends DebuggableService {
               case RequestDataSource.HEADERS:
                 data = requestContext.headers;
                 break;
-              case RequestDataSource.COOKIE:
+              case RequestDataSource.COOKIES:
                 data = requestContext.cookies;
                 break;
               case RequestDataSource.BODY:

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

@@ -108,7 +108,7 @@ describe('requestData', function () {
         }
         const res = RequestDataReflector.getMetadata(Target, 'myMethod');
         expect(res.get(0)).to.be.eql({
-          source: RequestDataSource.COOKIE,
+          source: RequestDataSource.COOKIES,
           schema: {type: DataType.ANY},
         });
       });
@@ -502,7 +502,7 @@ describe('requestData', function () {
         }
         const res = RequestDataReflector.getMetadata(Target, 'myMethod');
         expect(res.get(0)).to.be.eql({
-          source: RequestDataSource.COOKIE,
+          source: RequestDataSource.COOKIES,
           schema: {
             type: DataType.OBJECT,
             properties: {
@@ -526,7 +526,7 @@ describe('requestData', function () {
         }
         const res = RequestDataReflector.getMetadata(Target, 'myMethod');
         expect(res.get(0)).to.be.eql({
-          source: RequestDataSource.COOKIE,
+          source: RequestDataSource.COOKIES,
           schema: {
             type: DataType.OBJECT,
             properties: {
@@ -553,7 +553,7 @@ describe('requestData', function () {
         }
         const res = RequestDataReflector.getMetadata(Target, 'myMethod');
         expect(res.get(0)).to.be.eql({
-          source: RequestDataSource.COOKIE,
+          source: RequestDataSource.COOKIES,
           schema: {
             type: DataType.OBJECT,
             properties: {
@@ -579,7 +579,7 @@ describe('requestData', function () {
         }
         const mdMap = RequestDataReflector.getMetadata(Target, 'myMethod');
         const md = mdMap.get(0) as RequestDataMetadata;
-        expect(md.source).to.be.eq(RequestDataSource.COOKIE);
+        expect(md.source).to.be.eq(RequestDataSource.COOKIES);
         expect(md.schema).to.be.a('function');
         expect(md.property).to.be.eq(propertyKey);
         const res1 = md.schema as DataSchemaFactory;

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

@@ -118,10 +118,10 @@ export const requestHeader = createRequestDataPropertyDecoratorWithSource(
   RequestDataSource.HEADERS,
 );
 export const requestCookies = createRequestDataDecoratorWithSource(
-  RequestDataSource.COOKIE,
+  RequestDataSource.COOKIES,
 );
 export const requestCookie = createRequestDataPropertyDecoratorWithSource(
-  RequestDataSource.COOKIE,
+  RequestDataSource.COOKIES,
 );
 export const requestBody = createRequestDataDecoratorWithSource(
   RequestDataSource.BODY,

package/src/decorators/request-data/request-data-metadata.ts

@@ -8,7 +8,7 @@ export enum RequestDataSource {
   PARAMS = 'params',
   QUERY = 'query',
   HEADERS = 'headers',
-  COOKIE = 'cookie',
+  COOKIES = 'cookies',
   BODY = 'body',
 }
 

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './data-schema-types.js';
 export * from './controller-registry.js';
 
 export {RouteHandler} from '@e22m4u/js-trie-router';
+export {RouterHookType} from '@e22m4u/js-trie-router';
 export {RequestContext} from '@e22m4u/js-trie-router';
 export {RoutePreHandler} from '@e22m4u/js-trie-router';
 export {RoutePostHandler} from '@e22m4u/js-trie-router';