@e22m4u/ts-rest-router 0.0.6 → 0.1.0

package/README-ru.md

@@ -4,6 +4,14 @@
 
 Реализация REST маршрутизатора на основе контроллеров для TypeScript.
 
+#### Основные возможности
+
+- Декларативное определение маршрутов через декораторы.
+- Типизированные параметры запросов (body, query, params).
+- Поддержка middleware до и после обработки запроса.
+- Валидация входящих данных.
+- Поддержка всех HTTP методов (GET, POST, PUT, DELETE и т.д.).
+
 ## Установка
 
 ```bash
@@ -22,6 +30,225 @@ npm install @e22m4u/ts-rest-router
 }
 ```
 
+## Базовое использование
+
+Создание контроллера и методов
+
+```ts
+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,
+  ) {
+    return {                  // если метод возвращает объект,
+      id: '123',              // то результат будет представлен как
+      firstName: 'John',      // "Content-Type: application/json"
+      lastName: 'Doe',
+    };
+  }
+}
+```
+
+Регистрация контроллеров и запуск сервера
+
+```ts
+import http from 'http';
+import {RestRouter} from '@e22m4u/ts-rest-router';
+
+// создание роутера и регистрация контроллеров
+const router = new RestRouter();
+router.registerController(UserController);
+router.registerController(ProductController);
+
+// создание сервера и регистрация обработчика запросов
+const server = new http.Server();
+server.on('request', router.requestListener);
+
+// запуск сервера
+server.listen('8080', '0.0.0.0', () => {
+  console.log(`Server is running on http://localhost:8080`);
+});
+```
+
+## Декораторы
+
+Контроллер и методы:
+
+- `@controller` - определяет класс как контроллер
+- `@action` - базовый декоратор для методов
+- `@get` - GET запросы
+- `@post` - POST запросы
+- `@put` - PUT запросы
+- `@patch` - PATCH запросы
+- `@del` - DELETE запросы
+
+Хуки запроса:
+
+- `@before` - middleware перед обработкой запроса
+- `@after` - middleware после обработки запроса
+
+Параметры запроса:
+
+- `@param` - один параметр URL
+- `@params` - все параметры URL как объект
+- `@query` - один query параметр
+- `@queries` - все query параметры как объект
+- `@body` - тело запроса
+- `@bodyProp` - свойство из тела запроса
+- `@header` - один заголовок
+- `@headers` - все заголовки как объект
+- `@cookie` - одна cookie
+- `@cookies` - все cookies как объект
+- `@requestContext` - доступ к контексту запроса
+- `@requestData` - универсальный декоратор для доступа к данным запроса
+
+#### `@controller(options?: ControllerOptions)`
+
+Определение контроллера.
+
+```ts
+@controller()
+class UserController {
+  // методы контроллера
+}
+```
+
+Определение пути контроллера.
+
+```ts
+@controller('/users')  // путь контроллера
+class UserController {
+  // методы контроллера
+}
+```
+
+Дополнительные параметры декоратора.
+
+```ts
+@controller({
+  path: '/api',              // путь контроллера
+  before: [authMiddleware],  // middleware до обработки запроса
+  after: [loggerMiddleware], // middleware после обработки запроса
+})
+class UserController {
+  // методы контроллера
+}
+```
+
+#### `@get(path: string, options?: ActionOptions)`
+
+Определение метода GET.
+
+```ts
+@controller('/users')  // путь контроллера
+class UserController { // класс контроллера
+  @get('/whoAmI')      // маршрут GET /users/whoAmI
+  async whoAmI() {
+    return {           // если метод возвращает объект,
+      name: 'John',    // то результат будет представлен
+      surname: 'Doe',  // как "Content-Type: application/json"
+    };
+  }
+}
+```
+
+Дополнительные параметры декоратора.
+
+```ts
+@controller('/users')          // путь контроллера
+class UserController {         // класс контроллера
+  @get('/whoAmI', {            // маршрут GET /users/whoAmI
+    before: [authMiddleware],  // middleware до обработки запроса
+    after: [loggerMiddleware], // middleware после обработки запроса
+  })
+  async whoAmI() {
+    return {
+      name: 'John',
+      surname: 'Doe',
+    };
+  }
+}
+```
+
+#### `@requestContext(propertyName?: string)`
+
+Доступ к контексту запроса.
+
+```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` нативный поток входящего запроса
+- `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` тело запроса
+
 ## Отладка
 
 Установка переменной `DEBUG` включает вывод логов.

package/README.md

@@ -4,6 +4,14 @@
 
 Controllers-based REST router implementation for TypeScript.
 
+#### Key Features
+
+- 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
@@ -22,6 +30,225 @@ 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 {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 {                 // if method returns an object,
+      id: '123',             // the result will be presented as
+      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
+
+Request hooks:
+
+- `@before` - middleware before request handling
+- `@after` - middleware after request handling
+
+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
+- `@bodyProp` - property from 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
+
+#### `@controller(options?: ControllerOptions)`
+
+Defining a controller.
+
+```ts
+@controller()
+class UserController {
+  // controller methods
+}
+```
+
+Defining controller path.
+
+```ts
+@controller('/users')  // controller path
+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
+})
+class UserController {
+  // controller methods
+}
+```
+
+#### `@get(path: string, options?: ActionOptions)`
+
+Defining GET method.
+
+```ts
+@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"
+    };
+  }
+}
+```
+
+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
+  })
+  async whoAmI() {
+    return {
+      name: 'John',
+      surname: 'Doe',
+    };
+  }
+}
+```
+
+#### `@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
+  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"
+    // ...
+  }
+}
+```
+
+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
+  ) {
+    console.log(req);      // IncomingMessage
+    console.log(res);      // ServerResponse
+  }
+}
+```
+
+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
+
 ## Debugging
 
 Set the `DEBUG` variable to enable log output.