@e22m4u/ts-rest-router 0.0.7 → 0.1.0

package/README-ru.md

@@ -32,57 +32,35 @@ npm install @e22m4u/ts-rest-router
 
 ## Базовое использование
 
-Создание контроллера
+Создание контроллера и методов
 
 ```ts
-import {controller, get, post} from '@e22m4u/ts-rest-router';
-
-@controller()
-class UserController {
-  @get('/users')
-  async getUsers() {
-    return { users: [] };
-  }
-
-  @post('/users')
-  async createUser(
-    @body() userData: UserDTO,
-  ) {
-    return { success: true };
-  }
-}
-```
-
-Работа с параметрами запроса
-
-```ts
-@controller()
-class ProductController {
-  @get('/products/:id')
-  async getProduct(
-    @param('id') productId: string,
-    @query('fields') fields?: string,
-    @headers('authorization') auth?: string,
+import {get} from '@e22m4u/ts-rest-router';
+import {post} from '@e22m4u/ts-rest-router';
+import {bodyProp} from '@e22m4u/ts-rest-router';
+import {DataType} from '@e22m4u/ts-rest-router';
+import {controller} from '@e22m4u/ts-rest-router';
+
+@controller('/users')         // путь контроллера
+class UserController {        // класс контроллера
+  @post('/login')             // метод POST /users/login
+  async login(
+    @bodyProp('username', {   // свойство тела запроса "username"
+      type: DataType.STRING,  // тип параметра допускает только строки
+      required: true,         // параметр является обязательным
+    })
+    username: string,
+    @bodyProp('password', {   // свойство тела запроса "password"
+      type: DataType.STRING,  // тип параметра допускает только строки
+      required: true,         // параметр является обязательным
+    })
+    password: string,
   ) {
-    // ...
-  }
-}
-```
-
-Middleware и хуки
-
-```ts
-@controller({
-  path: '/api',
-  before: [authMiddleware],
-  after: [loggerMiddleware],
-})
-class ApiController {
-  @get('/secure', {
-    before: [checkPermissions],
-  })
-  secureEndpoint() {
-    // ...
+    return {                  // если метод возвращает объект,
+      id: '123',              // то результат будет представлен как
+      firstName: 'John',      // "Content-Type: application/json"
+      lastName: 'Doe',
+    };
   }
 }
 ```
@@ -110,7 +88,7 @@ server.listen('8080', '0.0.0.0', () => {
 
 ## Декораторы
 
-Контроллер и методы
+Контроллер и методы:
 
 - `@controller` - определяет класс как контроллер
 - `@action` - базовый декоратор для методов
@@ -120,14 +98,19 @@ server.listen('8080', '0.0.0.0', () => {
 - `@patch` - PATCH запросы
 - `@del` - DELETE запросы
 
-Параметры запроса
+Хуки запроса:
+
+- `@before` - middleware перед обработкой запроса
+- `@after` - middleware после обработки запроса
+
+Параметры запроса:
 
 - `@param` - один параметр URL
 - `@params` - все параметры URL как объект
 - `@query` - один query параметр
 - `@queries` - все query параметры как объект
 - `@body` - тело запроса
-- `@bodyParam` - конкретное поле из тела запроса
+- `@bodyProp` - свойство из тела запроса
 - `@header` - один заголовок
 - `@headers` - все заголовки как объект
 - `@cookie` - одна cookie
@@ -137,82 +120,122 @@ server.listen('8080', '0.0.0.0', () => {
 
 #### `@controller(options?: ControllerOptions)`
 
-Декоратор для определения класса как REST API контроллера.
+Определение контроллера.
 
-```typescript
+```ts
 @controller()
 class UserController {
   // методы контроллера
 }
 ```
 
+Определение пути контроллера.
+
+```ts
+@controller('/users')  // путь контроллера
+class UserController {
+  // методы контроллера
+}
+```
+
 Дополнительные параметры декоратора.
 
-```typescript
+```ts
 @controller({
-  path: '/api'
-  before: [authMiddleware],
-  after: [loggerMiddleware],
+  path: '/api',              // путь контроллера
+  before: [authMiddleware],  // middleware до обработки запроса
+  after: [loggerMiddleware], // middleware после обработки запроса
 })
 class UserController {
   // методы контроллера
 }
 ```
 
-### `@get(path: string, options?: ActionOptions)`
+#### `@get(path: string, options?: ActionOptions)`
 
-Декоратор для определения метода GET.
+Определение метода GET.
 
-```typescript
-@controller()
-class UserController {
-  @get('/users')
-  async getUsers() {
-    return {users: []};
-  }
-
-  @get('/users/:id') 
-  getUser(
-    @param('id') userId: string,
-  ) {
-    return {user: {id: userId}};
+```ts
+@controller('/users')  // путь контроллера
+class UserController { // класс контроллера
+  @get('/whoAmI')      // маршрут GET /users/whoAmI
+  async whoAmI() {
+    return {           // если метод возвращает объект,
+      name: 'John',    // то результат будет представлен
+      surname: 'Doe',  // как "Content-Type: application/json"
+    };
   }
 }
 ```
 
 Дополнительные параметры декоратора.
 
-```typescript
-@controller()
-class UserController {
-  @get('/users', {
-    before: [authMiddleware],
-    after: [loggerMiddleware],
+```ts
+@controller('/users')          // путь контроллера
+class UserController {         // класс контроллера
+  @get('/whoAmI', {            // маршрут GET /users/whoAmI
+    before: [authMiddleware],  // middleware до обработки запроса
+    after: [loggerMiddleware], // middleware после обработки запроса
   })
-  async getUsers() {
-    return {users: []};
+  async whoAmI() {
+    return {
+      name: 'John',
+      surname: 'Doe',
+    };
   }
 }
 ```
 
-### `@requestContext(propertyName?: string)`
+#### `@requestContext(propertyName?: string)`
 
-Декоратор для доступа к контексту запроса.
+Доступ к контексту запроса.
 
-```typescript
-@controller()
-class UserController {
-  @get('/users')
-  getUsers(
-    @requestContext('req') req: IncomingMessage,
-    @requestContext('res') res: ServerResponse,
+```ts
+import {RequestContext} from '@e22m4u/js-trie-router';
+
+@controller('/users')          // путь контроллера
+class UserController {         // класс контроллера
+  @get('/:id')                 // маршрут GET /users/:id
+  findById(
+    @requestContext()          // включениее контекста запроса
+    ctx: RequestContext,       // в качестве параметра метода
+  ) {
+    console.log(ctx.req);      // IncomingMessage
+    console.log(ctx.res);      // ServerResponse
+    console.log(ctx.params);   // {id: 10}
+    console.log(ctx.query);    // {include: 'city'}
+    console.log(ctx.headers);  // {cookie: 'foo=bar; baz=qux;'}
+    console.log(ctx.cookie);   // {foo: 'bar', baz: 'qux'}
+    console.log(ctx.method);   // "GET"
+    console.log(ctx.path);     // "/users/10?include=city"
+    console.log(ctx.pathname); // "/users/10"
+    // ...
+  }
+}
+```
+
+Доступ к свойствам контекста.
+
+```ts
+import {ServerResponse} from 'http';
+import {IncomingMessage} from 'http';
+
+@controller('/users')      // путь контроллера
+class UserController {     // класс контроллера
+  @get('/:id')             // маршрут GET /users/:id
+  findById(
+    @requestContext('req') // декоратор контекста запроса
+    req: IncomingMessage,  // включающий свойство "req"
+    @requestContext('res') // декоратор контекста запроса
+    res: ServerResponse,   // включающий свойство "res"
   ) {
-    // Доступ к оригинальным объектам запроса/ответа
+    console.log(req);      // IncomingMessage
+    console.log(res);      // ServerResponse
   }
 }
 ```
 
-Допустимые свойства:
+Свойства контекста:
 
 - `container: ServiceContainer` экземпляр [сервис-контейнера](https://npmjs.com/package/@e22m4u/js-service)
 - `req: IncomingMessage` нативный поток входящего запроса

package/README.md

@@ -32,57 +32,35 @@ options to your `tsconfig.json` file.
 
 ## Basic Usage
 
-Creating a controller.
+Creating a controller and methods.
 
 ```ts
-import {controller, get, post} from '@e22m4u/ts-rest-router';
-
-@controller()
-class UserController {
-  @get('/users')
-  async getUsers() {
-    return { users: [] };
-  }
-
-  @post('/users')
-  async createUser(
-    @body() userData: UserDTO,
+import {get} from '@e22m4u/ts-rest-router';
+import {post} from '@e22m4u/ts-rest-router';
+import {bodyProp} 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
+  async login(
+    @bodyProp('username', {  // "username" is request body property
+      type: DataType.STRING, // parameter type allows only strings
+      required: true,        // parameter is required
+    })
+    username: string,
+    @bodyProp('password', {  // "password" is request body property
+      type: DataType.STRING, // parameter type allows only strings
+      required: true,        // parameter is required
+    })
+    password: string,
   ) {
-    return { success: true };
-  }
-}
-```
-
-Request parameters.
-
-```ts
-@controller()
-class ProductController {
-  @get('/products/:id')
-  async getProduct(
-    @param('id') productId: string,
-    @query('fields') fields?: string,
-    @headers('authorization') auth?: string,
-  ) {
-    // ...
-  }
-}
-```
-
-Middleware and hooks.
-
-```ts
-@controller({
-  path: '/api',
-  before: [authMiddleware],
-  after: [loggerMiddleware],
-})
-class ApiController {
-  @get('/secure', {
-    before: [checkPermissions],
-  })
-  secureEndpoint() {
-    // ...
+    return {                 // if method returns an object,
+      id: '123',             // the result will be presented as
+      firstName: 'John',     // "Content-Type: application/json"
+      lastName: 'Doe',
+    };
   }
 }
 ```
@@ -120,6 +98,11 @@ Controller and methods:
 - `@patch` - PATCH requests
 - `@del` - DELETE requests
 
+Request hooks:
+
+- `@before` - middleware before request handling
+- `@after` - middleware after request handling
+
 Request parameters:
 
 - `@param` - single URL parameter
@@ -127,7 +110,7 @@ Request parameters:
 - `@query` - single query parameter
 - `@queries` - all query parameters as an object
 - `@body` - request body
-- `@bodyParam` - specific field from request body
+- `@bodyProp` - property from request body
 - `@header` - single header
 - `@headers` - all headers as an object
 - `@cookie` - single cookie
@@ -137,7 +120,7 @@ Request parameters:
 
 #### `@controller(options?: ControllerOptions)`
 
-Decorator for defining a class as a REST API controller.
+Defining a controller.
 
 ```ts
 @controller()
@@ -146,36 +129,41 @@ class UserController {
 }
 ```
 
+Defining controller path.
+
+```ts
+@controller('/users')  // controller path
+class UserController {
+  // controller methods
+}
+```
+
 Additional decorator parameters.
 
 ```ts
 @controller({
-  path: '/api'
-  before: [authMiddleware],
-  after: [loggerMiddleware],
+  path: '/api',              // controller path
+  before: [authMiddleware],  // middleware before request processing
+  after: [loggerMiddleware], // middleware after request processing
 })
 class UserController {
   // controller methods
 }
 ```
 
-### `@get(path: string, options?: ActionOptions)`
+#### `@get(path: string, options?: ActionOptions)`
 
-Decorator for defining GET method.
+Defining GET method.
 
 ```ts
-@controller()
-class UserController {
-  @get('/users')
-  async getUsers() {
-    return {users: []};
-  }
-
-  @get('/users/:id') 
-  getUser(
-    @param('id') userId: string,
-  ) {
-    return {user: {id: userId}};
+@controller('/users')  // controller path
+class UserController { // controller class
+  @get('/whoAmI')      // GET /users/whoAmI route
+  async whoAmI() {
+    return {           // if method returns an object,
+      name: 'John',    // the result will be presented
+      surname: 'Doe',  // as "Content-Type: application/json"
+    };
   }
 }
 ```
@@ -183,38 +171,71 @@ class UserController {
 Additional decorator parameters.
 
 ```ts
-@controller()
-class UserController {
-  @get('/users', {
-    before: [authMiddleware],
-    after: [loggerMiddleware],
+@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
   })
-  async getUsers() {
-    return {users: []};
+  async whoAmI() {
+    return {
+      name: 'John',
+      surname: 'Doe',
+    };
   }
 }
 ```
 
-### `@requestContext(propertyName?: string)`
+#### `@requestContext(propertyName?: string)`
 
-Decorator for accessing request context.
+Access to request context.
 
 ```ts
-import {IncomingMessage, ServerResponse} from 'http';
+import {RequestContext} from '@e22m4u/js-trie-router';
+
+@controller('/users')          // controller path
+class UserController {         // controller class
+  @get('/:id')                 // GET /users/:id route
+  findById(
+    @requestContext()          // including request context
+    ctx: RequestContext,       // as method parameter
+  ) {
+    console.log(ctx.req);      // IncomingMessage
+    console.log(ctx.res);      // ServerResponse
+    console.log(ctx.params);   // {id: 10}
+    console.log(ctx.query);    // {include: 'city'}
+    console.log(ctx.headers);  // {cookie: 'foo=bar; baz=qux;'}
+    console.log(ctx.cookie);   // {foo: 'bar', baz: 'qux'}
+    console.log(ctx.method);   // "GET"
+    console.log(ctx.path);     // "/users/10?include=city"
+    console.log(ctx.pathname); // "/users/10"
+    // ...
+  }
+}
+```
 
-@controller()
-class UserController {
-  @get('/users')
-  getUsers(
-    @requestContext('req') req: IncomingMessage,
-    @requestContext('res') res: ServerResponse,
+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
+  findById(
+    @requestContext('req') // request context decorator
+    req: IncomingMessage,  // including "req" property
+    @requestContext('res') // request context decorator
+    res: ServerResponse,   // including "res" property
   ) {
-    // Access to original request/response objects
+    console.log(req);      // IncomingMessage
+    console.log(res);      // ServerResponse
   }
 }
 ```
 
-Available properties:
+Context properties:
 
 - `container: ServiceContainer` instance of [service container](https://npmjs.com/package/@e22m4u/js-service)
 - `req: IncomingMessage` native incoming request stream