@e22m4u/ts-rest-router 0.0.6 → 0.0.7

package/README-ru.md

@@ -4,6 +4,14 @@
 
 Реализация REST маршрутизатора на основе контроллеров для TypeScript.
 
+#### Основные возможности
+
+- Декларативное определение маршрутов через декораторы.
+- Типизированные параметры запросов (body, query, params).
+- Поддержка middleware до и после обработки запроса.
+- Валидация входящих данных.
+- Поддержка всех HTTP методов (GET, POST, PUT, DELETE и т.д.).
+
 ## Установка
 
 ```bash
@@ -22,6 +30,202 @@ 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,
+  ) {
+    // ...
+  }
+}
+```
+
+Middleware и хуки
+
+```ts
+@controller({
+  path: '/api',
+  before: [authMiddleware],
+  after: [loggerMiddleware],
+})
+class ApiController {
+  @get('/secure', {
+    before: [checkPermissions],
+  })
+  secureEndpoint() {
+    // ...
+  }
+}
+```
+
+Регистрация контроллеров и запуск сервера
+
+```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 запросы
+
+Параметры запроса
+
+- `@param` - один параметр URL
+- `@params` - все параметры URL как объект
+- `@query` - один query параметр
+- `@queries` - все query параметры как объект
+- `@body` - тело запроса
+- `@bodyParam` - конкретное поле из тела запроса
+- `@header` - один заголовок
+- `@headers` - все заголовки как объект
+- `@cookie` - одна cookie
+- `@cookies` - все cookies как объект
+- `@requestContext` - доступ к контексту запроса
+- `@requestData` - универсальный декоратор для доступа к данным запроса
+
+#### `@controller(options?: ControllerOptions)`
+
+Декоратор для определения класса как REST API контроллера.
+
+```typescript
+@controller()
+class UserController {
+  // методы контроллера
+}
+```
+
+Дополнительные параметры декоратора.
+
+```typescript
+@controller({
+  path: '/api'
+  before: [authMiddleware],
+  after: [loggerMiddleware],
+})
+class UserController {
+  // методы контроллера
+}
+```
+
+### `@get(path: string, options?: ActionOptions)`
+
+Декоратор для определения метода GET.
+
+```typescript
+@controller()
+class UserController {
+  @get('/users')
+  async getUsers() {
+    return {users: []};
+  }
+
+  @get('/users/:id') 
+  getUser(
+    @param('id') userId: string,
+  ) {
+    return {user: {id: userId}};
+  }
+}
+```
+
+Дополнительные параметры декоратора.
+
+```typescript
+@controller()
+class UserController {
+  @get('/users', {
+    before: [authMiddleware],
+    after: [loggerMiddleware],
+  })
+  async getUsers() {
+    return {users: []};
+  }
+}
+```
+
+### `@requestContext(propertyName?: string)`
+
+Декоратор для доступа к контексту запроса.
+
+```typescript
+@controller()
+class UserController {
+  @get('/users')
+  getUsers(
+    @requestContext('req') req: IncomingMessage,
+    @requestContext('res') 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,204 @@ options to your `tsconfig.json` file.
 }
 ```
 
+## Basic Usage
+
+Creating a controller.
+
+```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 };
+  }
+}
+```
+
+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() {
+    // ...
+  }
+}
+```
+
+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 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
+- `@bodyParam` - specific field 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)`
+
+Decorator for defining a class as a REST API controller.
+
+```ts
+@controller()
+class UserController {
+  // controller methods
+}
+```
+
+Additional decorator parameters.
+
+```ts
+@controller({
+  path: '/api'
+  before: [authMiddleware],
+  after: [loggerMiddleware],
+})
+class UserController {
+  // controller methods
+}
+```
+
+### `@get(path: string, options?: ActionOptions)`
+
+Decorator for 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}};
+  }
+}
+```
+
+Additional decorator parameters.
+
+```ts
+@controller()
+class UserController {
+  @get('/users', {
+    before: [authMiddleware],
+    after: [loggerMiddleware],
+  })
+  async getUsers() {
+    return {users: []};
+  }
+}
+```
+
+### `@requestContext(propertyName?: string)`
+
+Decorator for accessing request context.
+
+```ts
+import {IncomingMessage, ServerResponse} from 'http';
+
+@controller()
+class UserController {
+  @get('/users')
+  getUsers(
+    @requestContext('req') req: IncomingMessage,
+    @requestContext('res') res: ServerResponse,
+  ) {
+    // Access to original request/response objects
+  }
+}
+```
+
+Available 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.

package/dist/cjs/index.cjs

@@ -29,8 +29,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // dist/esm/index.js
-var esm_exports = {};
-__export(esm_exports, {
+var index_exports = {};
+__export(index_exports, {
   ACTIONS_METADATA_KEY: () => ACTIONS_METADATA_KEY,
   ActionReflector: () => ActionReflector,
   CONTROLLER_METADATA_KEY: () => CONTROLLER_METADATA_KEY,
@@ -69,7 +69,7 @@ __export(esm_exports, {
   response: () => response,
   toCamelCase: () => toCamelCase
 });
-module.exports = __toCommonJS(esm_exports);
+module.exports = __toCommonJS(index_exports);
 
 // dist/esm/utils/capitalize.js
 function capitalize(input) {
@@ -176,11 +176,7 @@ function action(options) {
     const decoratorType = (0, import_ts_reflector4.getDecoratorTargetType)(target, propertyKey, descriptor);
     if (decoratorType !== import_ts_reflector3.DecoratorTargetType.INSTANCE_METHOD)
       throw new Error("@action decorator is only supported on an instance method.");
-    const metadata = {
-      ...options,
-      propertyKey
-    };
-    ActionReflector.setMetadata(metadata, target.constructor, propertyKey);
+    ActionReflector.setMetadata({ ...options, propertyKey }, target.constructor, propertyKey);
   };
 }
 __name(action, "action");
@@ -238,11 +234,7 @@ function controller(options) {
     const decoratorType = (0, import_ts_reflector8.getDecoratorTargetType)(target);
     if (decoratorType !== import_ts_reflector7.DecoratorTargetType.CONSTRUCTOR)
       throw new Error("@controller decorator is only supported on a class.");
-    const metadata = {
-      ...options,
-      className: target.name
-    };
-    ControllerReflector.setMetadata(metadata, target);
+    ControllerReflector.setMetadata({ ...options, className: target.name }, target);
   };
 }
 __name(controller, "controller");
@@ -296,23 +288,23 @@ __name(_RequestDataReflector, "RequestDataReflector");
 var RequestDataReflector = _RequestDataReflector;
 
 // dist/esm/decorators/request-data/request-data-decorator.js
-function requestData(metadata) {
+function requestData(options) {
   return function(target, propertyKey, indexOrDescriptor) {
     const decoratorType = (0, import_ts_reflector12.getDecoratorTargetType)(target, propertyKey, indexOrDescriptor);
     if (decoratorType !== import_ts_reflector11.DecoratorTargetType.INSTANCE_METHOD_PARAMETER)
       throw new Error("@requestData decorator is only supported on an instance method parameter.");
-    RequestDataReflector.setMetadata(metadata, target.constructor, indexOrDescriptor, propertyKey);
+    RequestDataReflector.setMetadata(options, target.constructor, indexOrDescriptor, propertyKey);
   };
 }
 __name(requestData, "requestData");
-function createDataDecorator(source) {
+function createRequestDataDecoratorWithSource(source) {
   return function() {
     const schema = { type: import_ts_data_schema.DataType.OBJECT };
     return requestData({ schema, source });
   };
 }
-__name(createDataDecorator, "createDataDecorator");
-function createPropertyDecorator(source) {
+__name(createRequestDataDecoratorWithSource, "createRequestDataDecoratorWithSource");
+function createRequestDataPropertyDecoratorWithSource(source) {
   return function(propertyKey, schemaOrType) {
     const properties = {};
     const rootSchema = { type: import_ts_data_schema.DataType.OBJECT };
@@ -330,16 +322,16 @@ function createPropertyDecorator(source) {
     });
   };
 }
-__name(createPropertyDecorator, "createPropertyDecorator");
-var params = createDataDecorator(RequestDataSource.PARAMS);
-var param = createPropertyDecorator(RequestDataSource.PARAMS);
-var queries = createDataDecorator(RequestDataSource.QUERY);
-var query = createPropertyDecorator(RequestDataSource.QUERY);
-var headers = createDataDecorator(RequestDataSource.HEADERS);
-var header = createPropertyDecorator(RequestDataSource.HEADERS);
-var cookies = createDataDecorator(RequestDataSource.COOKIE);
-var cookie = createPropertyDecorator(RequestDataSource.COOKIE);
-var bodyParam = createPropertyDecorator(RequestDataSource.BODY);
+__name(createRequestDataPropertyDecoratorWithSource, "createRequestDataPropertyDecoratorWithSource");
+var params = createRequestDataDecoratorWithSource(RequestDataSource.PARAMS);
+var param = createRequestDataPropertyDecoratorWithSource(RequestDataSource.PARAMS);
+var queries = createRequestDataDecoratorWithSource(RequestDataSource.QUERY);
+var query = createRequestDataPropertyDecoratorWithSource(RequestDataSource.QUERY);
+var headers = createRequestDataDecoratorWithSource(RequestDataSource.HEADERS);
+var header = createRequestDataPropertyDecoratorWithSource(RequestDataSource.HEADERS);
+var cookies = createRequestDataDecoratorWithSource(RequestDataSource.COOKIE);
+var cookie = createRequestDataPropertyDecoratorWithSource(RequestDataSource.COOKIE);
+var bodyParam = createRequestDataPropertyDecoratorWithSource(RequestDataSource.BODY);
 function body(schemaOrType) {
   let schema;
   if (typeof schemaOrType === "object") {
@@ -393,13 +385,12 @@ __name(_RequestContextReflector, "RequestContextReflector");
 var RequestContextReflector = _RequestContextReflector;
 
 // dist/esm/decorators/request-context/request-context-decorator.js
-function requestContext(propertyOrMetadata) {
+function requestContext(propertyName) {
   return function(target, propertyKey, indexOrDescriptor) {
     const decoratorType = (0, import_ts_reflector16.getDecoratorTargetType)(target, propertyKey, indexOrDescriptor);
     if (decoratorType !== import_ts_reflector15.DecoratorTargetType.INSTANCE_METHOD_PARAMETER)
       throw new Error("@requestContext decorator is only supported on an instance method parameter.");
-    const metadata = typeof propertyOrMetadata !== "object" ? { property: propertyOrMetadata } : propertyOrMetadata;
-    RequestContextReflector.setMetadata(metadata, target.constructor, indexOrDescriptor, propertyKey);
+    RequestContextReflector.setMetadata({ property: propertyName }, target.constructor, indexOrDescriptor, propertyKey);
   };
 }
 __name(requestContext, "requestContext");

package/dist/esm/decorators/action/action-decorator.d.ts

@@ -12,42 +12,41 @@ export type ActionOptions = Flatten<Omit<ActionMetadata, 'propertyKey'>>;
  */
 export declare function action<T extends object>(options: ActionOptions): (target: Prototype<T>, propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
- * Action alias options.
+ * Action method options.
  */
-type ActionAliasOptions = Flatten<Omit<ActionOptions, 'method' | 'path'>>;
+export type ActionMethodOptions = Flatten<Omit<ActionOptions, 'method' | 'path'>>;
 /**
  * Get decorator.
  *
  * @param path
  * @param options
  */
-export declare const get: (path: string, options?: ActionAliasOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare const get: (path: string, options?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
  * Post decorator.
  *
  * @param path
  * @param options
  */
-export declare const post: (path: string, options?: ActionAliasOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare const post: (path: string, options?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
  * Put decorator.
  *
  * @param path
  * @param options
  */
-export declare const put: (path: string, options?: ActionAliasOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare const put: (path: string, options?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
  * Patch decorator.
  *
  * @param path
  * @param options
  */
-export declare const patch: (path: string, options?: ActionAliasOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare const patch: (path: string, options?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
  * Del decorator.
  *
  * @param path
  * @param options
  */
-export declare const del: (path: string, options?: ActionAliasOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
-export {};
+export declare const del: (path: string, options?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;

package/dist/esm/decorators/action/action-decorator.js

@@ -12,11 +12,7 @@ export function action(options) {
         const decoratorType = getDecoratorTargetType(target, propertyKey, descriptor);
         if (decoratorType !== DecoratorTargetType.INSTANCE_METHOD)
             throw new Error('@action decorator is only supported on an instance method.');
-        const metadata = {
-            ...options,
-            propertyKey,
-        };
-        ActionReflector.setMetadata(metadata, target.constructor, propertyKey);
+        ActionReflector.setMetadata({ ...options, propertyKey }, target.constructor, propertyKey);
     };
 }
 /**

package/dist/esm/decorators/action/action-decorator.spec.js

@@ -13,47 +13,47 @@ import { HttpMethod } from '@e22m4u/js-trie-router';
 import { ActionReflector } from './action-reflector.js';
 describe('action', function () {
     it('sets given options to the target metadata', function () {
-        const method = HttpMethod.GET;
-        const path = 'myPath';
-        const before = () => undefined;
-        const after = () => undefined;
-        const customOption = 'customOption';
+        const options = {
+            method: HttpMethod.GET,
+            path: 'myPath',
+            before: () => undefined,
+            after: () => undefined,
+            customOption: 'customOption',
+        };
         class Target {
             method() { }
         }
         __decorate([
-            action({ method, path, before, after, customOption }),
+            action(options),
             __metadata("design:type", Function),
             __metadata("design:paramtypes", []),
             __metadata("design:returntype", void 0)
         ], Target.prototype, "method", null);
         const res = ActionReflector.getMetadata(Target);
         expect(res.get('method')).to.be.eql({
+            ...options,
             propertyKey: 'method',
-            method,
-            path,
-            before,
-            after,
-            customOption,
         });
     });
     it('overrides a given "propertyKey" option by the target method name', function () {
-        const method = HttpMethod.GET;
-        const path = 'myPath';
+        const options = {
+            propertyKey: 'myMethod',
+            method: HttpMethod.GET,
+            path: 'myPath',
+        };
         class Target {
             method() { }
         }
         __decorate([
-            action({ propertyKey: 'myMethod', method, path }),
+            action(options),
             __metadata("design:type", Function),
             __metadata("design:paramtypes", []),
             __metadata("design:returntype", void 0)
         ], Target.prototype, "method", null);
         const res = ActionReflector.getMetadata(Target);
         expect(res.get('method')).to.be.eql({
+            ...options,
             propertyKey: 'method',
-            method,
-            path,
         });
     });
 });

package/dist/esm/decorators/action/action-metadata.d.ts

@@ -11,7 +11,6 @@ export type ActionMetadata = {
     path: string;
     before?: RoutePreHandler | RoutePreHandler[];
     after?: RoutePostHandler | RoutePostHandler[];
-    [option: string]: unknown | undefined;
 };
 /**
  * Action metadata map.