@e22m4u/ts-rest-router 0.1.2 → 0.2.1

package/README.md

@@ -8,7 +8,17 @@ REST маршрутизатор на основе контроллеров дл
 - Типизированные параметры запросов (body, query, params).
 - Поддержка middleware до и после обработки запроса.
 - Валидация входящих данных.
-- Поддержка всех HTTP методов (GET, POST, PUT, DELETE и т.д.).
+- Поддержка всех HTTP методов (GET, POST, PUT, PATCH и DELETE).
+
+## Содержание
+
+- [Установка](#установка)
+  - [Поддержка декораторов](#поддержка-декораторов)
+- [Базовый пример](#базовый-пример)
+- [Валидация](#валидация)
+- [Декораторы](#декораторы)
+- [Отладка](#отладка)
+- [Тесты](#тесты)
 
 ## Установка
 
@@ -28,48 +38,49 @@ npm install @e22m4u/ts-rest-router
 }
 ```
 
-## Базовое использование
+## Базовый пример
 
-Создание контроллера и методов
+Создание контроллера и методов.
 
 ```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')         // путь контроллера
-class UserController {        // класс контроллера
-  @post('/login')             // метод POST /users/login
+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';
+
+// объявление контроллера
+// и базового пути /users
+@restController('users')
+class UserController {
+  // объявление метода POST /users/login
+  // (использует базовый путь контроллера)
+  @postAction('login')
   async login(
-    @field('username', {      // поле "username" в теле запроса
-      type: DataType.STRING,  // тип параметра допускает только строки
-      required: true,         // параметр является обязательным
-    })
-    username: string,
-    @field('password', {      // поле "password" в теле запроса
-      type: DataType.STRING,  // тип параметра допускает только строки
-      required: true,         // параметр является обязательным
-    })
-    password: string,
+    // инъекция значений указанных полей
+    // извлеизвлекаемых из тела запроса
+    @requestField('username') username?: string,
+    @requestField('password') password?: string,
   ) {
-    return {                  // если метод возвращает объект,
-      id: '123',              // то результат будет представлен как
-      firstName: 'John',      // "Content-Type: application/json"
+    // так как метод возвращает объект,
+    // результат будет представлен как
+    // "Content-Type: application/json"
+    return {
+      id: 1,
+      firstName: 'John',
       lastName: 'Doe',
     };
   }
 }
 ```
 
-Регистрация контроллеров и запуск сервера
+Регистрация контроллеров и запуск сервера.
 
 ```ts
 import http from 'http';
 import {RestRouter} from '@e22m4u/ts-rest-router';
 
-// создание роутера и регистрация контроллеров
+// создание маршрутизатора и регистрация контроллеров
 const router = new RestRouter();
 router.registerController(UserController);
 router.registerController(ProductController);
@@ -84,83 +95,169 @@ server.listen('8080', '0.0.0.0', () => {
 });
 ```
 
+## Валидация
+
+Указанные ниже декораторы используются для инъекции соответствующих параметров
+запроса в качестве аргументов метода контроллера. Каждый из указанных декораторов
+имеет параметр `schemaOrType`, в котором определяется тип ожидаемого значения
+или схема для проверки данных.
+
+- `@requestParam(name: string, schemaOrType?: DataSchema | DataType)`  
+  *- извлечение URL параметра по названию;*
+- `@requestQuery(name: string, schemaOrType?: DataSchema | DataType)`  
+  *- извлечение query параметра по названию;*
+- `@requestBody(schemaOrType?: DataSchema | DataType)`  
+  *- извлечение тела запроса;*
+- `@requestField(name: string, schemaOrType?: DataSchema | DataType)`  
+  *- извлечение свойства из тела запроса;*
+- `@requestHeader(name: string, schemaOrType?: DataSchema | DataType)`  
+  *- извлечение заголовка запроса по названию;*
+- `@requestCookie(name: string, schemaOrType?: DataSchema | DataType)`  
+  *- извлечение cookie запроса по названию;*
+
+Проверка входящих данных выполняется встроенным модулем
+[@e22m4u/ts-data-schema](https://www.npmjs.com/package/@e22m4u/ts-data-schema)
+(не требует установки). Ниже приводятся константы для определения допустимых
+типов извлекаемого значения.
+
+- `DataType.ANY` - принимает любой тип
+- `DataType.STRING` - строковые значения
+- `DataType.NUMBER` - числовые значения
+- `DataType.BOOLEAN` - логические значения
+- `DataType.ARRAY` - массивы
+- `DataType.OBJECT` - объекты (не экземпляры)
+
+Для определения дополнительных условий, используется объект `DataSchema`,
+с помощью которого можно определить структуру ожидаемого объекта, допустимые
+элементы массива, функции-валидаторы и другие ограничения входящих данных.
+
+```ts
+type DataSchema = {
+  type: DataType;
+  items?: DataSchema;
+  properties?: {[key: string]: DataSchema};
+  required?: boolean;
+  validate?: CallableValidator | CallableValidator[];
+  default?: unknown;
+}
+```
+
+Пример проверки передаваемого объекта методом POST:
+
+```ts
+import {DataType} from '@e22m4u/ts-rest-router';
+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()                        // POST /users
+  async create(
+    @requestBody({                     // декоратор тела запроса
+      type: DataType.OBJECT,           // в теле запроса ожидается объект
+      properties: {
+        name: {                        // схема свойства "name"
+          type: DataType.STRING,       // свойство должно содержать строку
+          required: true,              // свойство не может содержать undefined или null
+          validate: v => v.length > 2, // проверка длины строки
+        },
+        age: {                         // схема свойства "age"
+          type: DataType.NUMBER,       // свойство должно являться числом
+        }
+      },
+    })
+    body: {name: string, age?: number},
+  ) {
+    return {
+      id: 1,
+      name: body.name,
+      age: body.age,
+    };
+  }
+}
+```
+
 ## Декораторы
 
 Контроллер и методы:
 
-- `@controller` - определяет класс как контроллер
-- `@action` - базовый декоратор для методов
-- `@get` - GET запросы
-- `@post` - POST запросы
-- `@put` - PUT запросы
-- `@patch` - PATCH запросы
-- `@del` - DELETE запросы
+- `@restController` - определяет класс как контроллер;
+- `@restAction` - базовый декоратор для методов;
+- `@getAction` - метод GET;
+- `@postAction` - метод POST;
+- `@putAction` - метод PUT;
+- `@patchAction` - метод PATCH;
+- `@deleteAction` - метод DELETE;
 
 Хуки запроса:
 
-- `@before` - middleware перед обработкой запроса
-- `@after` - middleware после обработки запроса
+- `@beforeAction` - middleware перед обработкой запроса;
+- `@afterAction` - middleware после обработки запроса;
 
 Параметры запроса:
 
-- `@param` - один параметр URL
-- `@params` - все параметры URL как объект
-- `@query` - один query параметр
-- `@queries` - все query параметры как объект
-- `@body` - тело запроса
-- `@field` - поле в теле запроса
-- `@header` - один заголовок
-- `@headers` - все заголовки как объект
-- `@cookie` - одна cookie
-- `@cookies` - все cookies как объект
-- `@requestContext` - доступ к контексту запроса
-- `@requestData` - универсальный декоратор для доступа к данным запроса
-
-#### `@controller(options?: ControllerOptions)`
+- `@requestParam` - определенный URL параметр;
+- `@requestParams` - все параметры URL как объект;
+- `@requestQuery` - определенный query параметр;
+- `@requestQueries` - все query параметры как объект;
+- `@requestBody` - тело запроса;
+- `@requestField` - поле в теле запроса;
+- `@requestHeader` - определенный заголовок запроса;
+- `@requestHeaders` - все заголовки запроса как объект;
+- `@requestCookie` - определенный cookie запроса;
+- `@requestCookies` - все cookies запроса как объект;
+- `@requestContext` - доступ к контексту запроса;
+- `@requestData` - доступ к данным запроса;
+- `@httpRequest` - экземпляр `IncomingMessage`;
+- `@httpResponse` - экземпляр `ServerResponse`;
+
+#### `@restController(options?: ControllerOptions)`
 
 Определение контроллера.
 
 ```ts
-@controller()
+@restController()
 class UserController {
-  // методы контроллера
+  // ...
 }
 ```
 
-Определение пути контроллера.
+Определение базового пути.
 
 ```ts
-@controller('/users')  // путь контроллера
+@restController('users')
 class UserController {
-  // методы контроллера
+  // ...
 }
 ```
 
 Дополнительные параметры декоратора.
 
 ```ts
-@controller({
-  path: '/api',              // путь контроллера
+@restController({
+  path: 'api',               // базовый путь
   before: [authMiddleware],  // middleware до обработки запроса
   after: [loggerMiddleware], // middleware после обработки запроса
 })
 class UserController {
-  // методы контроллера
+  // ...
 }
 ```
 
-#### `@get(path: string, options?: ActionOptions)`
+#### `@getAction(path: string, options?: ActionOptions)`
 
 Определение метода GET.
 
 ```ts
-@controller('/users')  // путь контроллера
-class UserController { // класс контроллера
-  @get('/whoAmI')      // маршрут GET /users/whoAmI
+@restController('users')
+class UserController {
+  @getAction('whoAmI')   // маршрут GET /users/whoAmI
   async whoAmI() {
-    return {           // если метод возвращает объект,
-      name: 'John',    // то результат будет представлен
-      surname: 'Doe',  // как "Content-Type: application/json"
+    return {              // если метод возвращает объект,
+      name: 'John',       // то результат будет представлен
+      surname: 'Doe',     // как "Content-Type: application/json"
     };
   }
 }
@@ -169,9 +266,9 @@ class UserController { // класс контроллера
 Дополнительные параметры декоратора.
 
 ```ts
-@controller('/users')          // путь контроллера
-class UserController {         // класс контроллера
-  @get('/whoAmI', {            // маршрут GET /users/whoAmI
+@restController('users')
+class UserController {
+  @getAction('whoAmI', {      // маршрут GET /users/whoAmI
     before: [authMiddleware],  // middleware до обработки запроса
     after: [loggerMiddleware], // middleware после обработки запроса
   })
@@ -191,12 +288,12 @@ class UserController {         // класс контроллера
 ```ts
 import {RequestContext} from '@e22m4u/js-trie-router';
 
-@controller('/users')          // путь контроллера
-class UserController {         // класс контроллера
-  @get('/:id')                 // маршрут GET /users/:id
+@restController('users')
+class UserController {
+  @getAction(':id')
   findById(
-    @requestContext()          // включениее контекста запроса
-    ctx: RequestContext,       // в качестве параметра метода
+    @requestContext()          // инъекция контекста запроса
+    ctx: RequestContext,       // в качестве аргумента
   ) {
     console.log(ctx.req);      // IncomingMessage
     console.log(ctx.res);      // ServerResponse
@@ -218,9 +315,9 @@ class UserController {         // класс контроллера
 import {ServerResponse} from 'http';
 import {IncomingMessage} from 'http';
 
-@controller('/users')      // путь контроллера
+@restController('/users')  // путь контроллера
 class UserController {     // класс контроллера
-  @get('/:id')             // маршрут GET /users/:id
+  @getAction('/:id')       // маршрут GET /users/:id
   findById(
     @requestContext('req') // декоратор контекста запроса
     req: IncomingMessage,  // включающий свойство "req"