@e22m4u/ts-rest-router 0.1.1 → 0.2.0

package/README.md

@@ -1,27 +1,25 @@
 # @e22m4u/ts-rest-router
 
-*English | [Русский](./README-ru.md)*
+REST маршрутизатор на основе контроллеров для TypeScript.
 
-Controllers-based REST router implementation for TypeScript.
+#### Основные возможности
 
-#### Key Features
+- Декларативное определение маршрутов через декораторы.
+- Типизированные параметры запросов (body, query, params).
+- Поддержка middleware до и после обработки запроса.
+- Валидация входящих данных.
+- Поддержка всех HTTP методов (GET, POST, PUT, PATCH и DELETE).
 
-- Declarative route definition using decorators.
-- Typed request parameters (body, query, params).
-- Pre and post request middleware support.
-- Input data validation.
-- Support for all HTTP methods (GET, POST, PUT, DELETE, etc.).
-
-## Installation
+## Установка
 
 ```bash
 npm install @e22m4u/ts-rest-router
 ```
 
-#### Decorators support
+#### Поддержка декораторов
 
-To enable decorators support add the following
-options to your `tsconfig.json` file.
+Для включения поддержки декораторов, добавьте указанные
+ниже опции в файл `tsconfig.json` вашего проекта.
 
 ```json
 {
@@ -30,152 +28,154 @@ options to your `tsconfig.json` file.
 }
 ```
 
-## Basic Usage
+## Базовое использование
 
-Creating a controller and methods.
+Создание контроллера и методов.
 
 ```ts
-import {get} from '@e22m4u/ts-rest-router';
-import {post} from '@e22m4u/ts-rest-router';
-import {field} from '@e22m4u/ts-rest-router';
 import {DataType} from '@e22m4u/ts-rest-router';
-import {controller} from '@e22m4u/ts-rest-router';
-
-@controller('/users')        // controller path
-class UserController {       // controller class
-  @post('/login')            // POST /users/login method
+import {getAction} from '@e22m4u/ts-rest-router';
+import {postAction} from '@e22m4u/ts-rest-router';
+import {requestField} from '@e22m4u/ts-rest-router';
+import {restController} from '@e22m4u/ts-rest-router';
+
+@restController('/users')       // путь контроллера
+class UserController {          // класс контроллера
+  @postAction('/login')         // метод POST /users/login
   async login(
-    @field('username', {     // "username" is request body field
-      type: DataType.STRING, // parameter type allows only strings
-      required: true,        // parameter is required
+    @requestField('username', { // поле "username" в теле запроса
+      type: DataType.STRING,    // тип параметра допускает только строки
+      required: true,           // параметр является обязательным
     })
     username: string,
-    @field('password', {     // "password" is request body field
-      type: DataType.STRING, // parameter type allows only strings
-      required: true,        // parameter is required
+    @requestField('password', { // поле "password" в теле запроса
+      type: DataType.STRING,    // тип параметра допускает только строки
+      required: true,           // параметр является обязательным
     })
     password: string,
   ) {
-    return {                 // if method returns an object,
-      id: '123',             // the result will be presented as
-      firstName: 'John',     // "Content-Type: application/json"
+    return {                  // если метод возвращает объект,
+      id: '123',              // то результат будет представлен как
+      firstName: 'John',      // "Content-Type: application/json"
       lastName: 'Doe',
     };
   }
 }
 ```
 
-Registering controllers and starting the server.
+Регистрация контроллеров и запуск сервера.
 
 ```ts
 import http from 'http';
 import {RestRouter} from '@e22m4u/ts-rest-router';
 
-// create router and register controllers
+// создание маршрутизатора и регистрация контроллеров
 const router = new RestRouter();
 router.registerController(UserController);
 router.registerController(ProductController);
 
-// create server and register request handler
+// создание сервера и регистрация обработчика запросов
 const server = new http.Server();
 server.on('request', router.requestListener);
 
-// start server
+// запуск сервера
 server.listen('8080', '0.0.0.0', () => {
   console.log(`Server is running on http://localhost:8080`);
 });
 ```
 
-## Decorators
+## Декораторы
 
-Controller and methods:
+Контроллер и методы:
 
-- `@controller` - defines a class as a controller
-- `@action` - base decorator for methods
-- `@get` - GET requests
-- `@post` - POST requests
-- `@put` - PUT requests
-- `@patch` - PATCH requests
-- `@del` - DELETE requests
+- `@restController` - определяет класс как контроллер;
+- `@restAction` - базовый декоратор для методов;
+- `@getAction` - метод GET;
+- `@postAction` - метод POST;
+- `@putAction` - метод PUT;
+- `@patchAction` - метод PATCH;
+- `@deleteAction` - метод DELETE;
 
-Request hooks:
+Хуки запроса:
 
-- `@before` - middleware before request handling
-- `@after` - middleware after request handling
+- `@beforeAction` - middleware перед обработкой запроса;
+- `@afterAction` - middleware после обработки запроса;
 
-Request parameters:
+Параметры запроса:
 
-- `@param` - single URL parameter
-- `@params` - all URL parameters as an object
-- `@query` - single query parameter
-- `@queries` - all query parameters as an object
-- `@body` - request body
-- `@field` - field in request body
-- `@header` - single header
-- `@headers` - all headers as an object
-- `@cookie` - single cookie
-- `@cookies` - all cookies as an object
-- `@requestContext` - access to request context
-- `@requestData` - universal decorator for accessing request data
+- `@requestParam` - определенный URL параметр;
+- `@requestParams` - все параметры URL как объект;
+- `@requestQuery` - определенный query параметр;
+- `@requestQueries` - все query параметры как объект;
+- `@requestBody` - тело запроса;
+- `@requestField` - поле в теле запроса;
+- `@requestHeader` - определенный заголовок запроса;
+- `@requestHeaders` - все заголовки запроса как объект;
+- `@requestCookie` - определенный cookie запроса;
+- `@requestCookies` - все cookies запроса как объект;
+- `@requestContext` - доступ к контексту запроса;
+- `@requestData` - доступ к данным запроса;
+- `@httpRequest` - экземпляр `IncomingMessage`;
+- `@httpResponse` - экземпляр `ServerResponse`;
 
-#### `@controller(options?: ControllerOptions)`
+#### `@restController(options?: ControllerOptions)`
 
-Defining a controller.
+Определение контроллера.
 
 ```ts
-@controller()
+@restController()
 class UserController {
-  // controller methods
+  // методы контроллера
 }
 ```
 
-Defining controller path.
+Определение пути контроллера.
 
 ```ts
-@controller('/users')  // controller path
+@restController('/users')  // путь контроллера
 class UserController {
-  // controller methods
+  // методы контроллера
 }
 ```
 
-Additional decorator parameters.
+Дополнительные параметры декоратора.
 
 ```ts
-@controller({
-  path: '/api',              // controller path
-  before: [authMiddleware],  // middleware before request processing
-  after: [loggerMiddleware], // middleware after request processing
+@restController({
+  path: '/api',              // путь контроллера
+  before: [authMiddleware],  // middleware до обработки запроса
+  after: [loggerMiddleware], // middleware после обработки запроса
 })
 class UserController {
-  // controller methods
+  // методы контроллера
 }
 ```
 
-#### `@get(path: string, options?: ActionOptions)`
+#### `@getAction(path: string, options?: ActionOptions)`
 
-Defining GET method.
+Определение метода GET.
 
 ```ts
-@controller('/users')  // controller path
-class UserController { // controller class
-  @get('/whoAmI')      // GET /users/whoAmI route
+@restController('/users') // путь контроллера
+class UserController {    // класс контроллера
+  @getAction('/whoAmI')   // маршрут GET /users/whoAmI
   async whoAmI() {
-    return {           // if method returns an object,
-      name: 'John',    // the result will be presented
-      surname: 'Doe',  // as "Content-Type: application/json"
+    return {              // если метод возвращает объект,
+      name: 'John',       // то результат будет представлен
+      surname: 'Doe',     // как "Content-Type: application/json"
     };
   }
 }
 ```
 
-Additional decorator parameters.
+Дополнительные параметры декоратора.
 
 ```ts
-@controller('/users')          // controller path
-class UserController {         // controller class
-  @get('/whoAmI', {            // GET /users/whoAmI route
-    before: [authMiddleware],  // middleware before request processing
-    after: [loggerMiddleware], // middleware after request processing
+@restController('/users')      // путь контроллера
+class UserController {         // класс контроллера
+  @getAction('/whoAmI', {      // маршрут GET /users/whoAmI
+    before: [authMiddleware],  // middleware до обработки запроса
+    after: [loggerMiddleware], // middleware после обработки запроса
   })
   async whoAmI() {
     return {
@@ -188,17 +188,17 @@ class UserController {         // controller class
 
 #### `@requestContext(propertyName?: string)`
 
-Access to request context.
+Доступ к контексту запроса.
 
 ```ts
 import {RequestContext} from '@e22m4u/js-trie-router';
 
-@controller('/users')          // controller path
-class UserController {         // controller class
-  @get('/:id')                 // GET /users/:id route
+@restController('/users')      // путь контроллера
+class UserController {         // класс контроллера
+  @getAction('/:id')           // маршрут GET /users/:id
   findById(
-    @requestContext()          // including request context
-    ctx: RequestContext,       // as method parameter
+    @requestContext()          // включениее контекста запроса
+    ctx: RequestContext,       // в качестве параметра метода
   ) {
     console.log(ctx.req);      // IncomingMessage
     console.log(ctx.res);      // ServerResponse
@@ -214,20 +214,20 @@ class UserController {         // controller class
 }
 ```
 
-Access to context properties.
+Доступ к свойствам контекста.
 
 ```ts
 import {ServerResponse} from 'http';
 import {IncomingMessage} from 'http';
 
-@controller('/users')      // controller path
-class UserController {     // controller class
-  @get('/:id')             // GET /users/:id route
+@restController('/users')  // путь контроллера
+class UserController {     // класс контроллера
+  @getAction('/:id')       // маршрут GET /users/:id
   findById(
-    @requestContext('req') // request context decorator
-    req: IncomingMessage,  // including "req" property
-    @requestContext('res') // request context decorator
-    res: ServerResponse,   // including "res" property
+    @requestContext('req') // декоратор контекста запроса
+    req: IncomingMessage,  // включающий свойство "req"
+    @requestContext('res') // декоратор контекста запроса
+    res: ServerResponse,   // включающий свойство "res"
   ) {
     console.log(req);      // IncomingMessage
     console.log(res);      // ServerResponse
@@ -235,34 +235,34 @@ class UserController {     // controller class
 }
 ```
 
-Context properties:
+Свойства контекста:
 
-- `container: ServiceContainer` instance of [service container](https://npmjs.com/package/@e22m4u/js-service)
-- `req: IncomingMessage` native incoming request stream
-- `res: ServerResponse` native server response stream
-- `params: ParsedParams` key-value object with path parameters
-- `query: ParsedQuery` key-value object with query string parameters
-- `headers: ParsedHeaders` key-value object with request headers
-- `cookie: ParsedCookie` key-value object of parsed `cookie` header
-- `method: string` request method in uppercase, e.g. `GET`, `POST`, etc.
-- `path: string` path including query string, e.g. `/myPath?foo=bar`
-- `pathname: string` request path, e.g. `/myMath`
-- `body: unknown` request body
+- `container: ServiceContainer` экземпляр [сервис-контейнера](https://npmjs.com/package/@e22m4u/js-service)
+- `req: IncomingMessage` нативный поток входящего запроса
+- `res: ServerResponse` нативный поток ответа сервера
+- `params: ParsedParams` объект ключ-значение с параметрами пути
+- `query: ParsedQuery` объект ключ-значение с параметрами строки запроса
+- `headers: ParsedHeaders` объект ключ-значение с заголовками запроса 
+- `cookie: ParsedCookie` объект ключ-значение разобранного заголовка `cookie`
+- `method: string` метод запроса в верхнем регистре, например `GET`, `POST` и т.д.
+- `path: string` путь включающий строку запроса, например `/myPath?foo=bar`
+- `pathname: string` путь запроса, например `/myMath`
+- `body: unknown` тело запроса
 
-## Debugging
+## Отладка
 
-Set the `DEBUG` variable to enable log output.
+Установка переменной `DEBUG` включает вывод логов.
 
 ```bash
 DEBUG=tsRestRouter* npm run test
 ```
 
-## Tests
+## Тесты
 
 ```bash
 npm run test
 ```
 
-## License
+## Лицензия
 
 MIT