@e22m4u/ts-rest-router 0.1.1 → 0.2.0

package/src/decorators/{controller/controller-decorator.spec.ts → rest-controller/rest-controller-decorator.spec.ts}

@@ -1,13 +1,13 @@
 import {expect} from 'chai';
-import {controller} from './controller-decorator.js';
-import {ControllerOptions} from './controller-decorator.js';
-import {ControllerReflector} from './controller-reflector.js';
+import {restController} from './rest-controller-decorator.js';
+import {RestControllerOptions} from './rest-controller-decorator.js';
+import {RestControllerReflector} from './rest-controller-reflector.js';
 
-describe('controller', function () {
+describe('restController', function () {
   it('does not require options', function () {
-    @controller()
+    @restController()
     class Target {}
-    const res = ControllerReflector.getMetadata(Target);
+    const res = RestControllerReflector.getMetadata(Target);
     expect(res).to.be.eql({className: 'Target'});
   });
 
@@ -18,9 +18,9 @@ describe('controller', function () {
       after: () => undefined,
       extraOption: 'extraOption',
     };
-    @controller(options)
+    @restController(options)
     class Target {}
-    const res = ControllerReflector.getMetadata(Target);
+    const res = RestControllerReflector.getMetadata(Target);
     expect(res).to.be.eql({
       ...options,
       className: 'Target',
@@ -28,31 +28,31 @@ describe('controller', function () {
   });
 
   it('overrides given "className" option by the target class name', function () {
-    @controller({className: 'myClassName'} as ControllerOptions)
+    @restController({className: 'myClassName'} as RestControllerOptions)
     class Target {}
-    const res = ControllerReflector.getMetadata(Target);
+    const res = RestControllerReflector.getMetadata(Target);
     expect(res).to.be.eql({className: 'Target'});
   });
 
   it('allows to pass the path option to the first parameter', function () {
-    @controller('myPath')
+    @restController('myPath')
     class Target {}
-    const res = ControllerReflector.getMetadata(Target);
+    const res = RestControllerReflector.getMetadata(Target);
     expect(res).to.be.eql({className: 'Target', path: 'myPath'});
   });
 
   it('merges two given arguments in the target metadata', function () {
     const before = () => undefined;
-    @controller('myPath', {before})
+    @restController('myPath', {before})
     class Target {}
-    const res = ControllerReflector.getMetadata(Target);
+    const res = RestControllerReflector.getMetadata(Target);
     expect(res).to.be.eql({className: 'Target', path: 'myPath', before});
   });
 
   it('overrides the path option by the first argument', function () {
-    @controller('myPath1', {path: 'myPath2'})
+    @restController('myPath1', {path: 'myPath2'})
     class Target {}
-    const res = ControllerReflector.getMetadata(Target);
+    const res = RestControllerReflector.getMetadata(Target);
     expect(res).to.be.eql({className: 'Target', path: 'myPath1'});
   });
 });

package/src/decorators/{controller/controller-decorator.ts → rest-controller/rest-controller-decorator.ts}

@@ -1,29 +1,33 @@
 import {Flatten} from '../../types.js';
 import {Constructor} from '../../types.js';
 import {DecoratorTargetType} from '@e22m4u/ts-reflector';
-import {ControllerMetadata} from './controller-metadata.js';
 import {getDecoratorTargetType} from '@e22m4u/ts-reflector';
-import {ControllerReflector} from './controller-reflector.js';
+import {RestControllerMetadata} from './rest-controller-metadata.js';
+import {RestControllerReflector} from './rest-controller-reflector.js';
 
 /**
- * Controller options.
+ * Rest controller options.
  */
-export type ControllerOptions = Flatten<Omit<ControllerMetadata, 'className'>>;
+export type RestControllerOptions = Flatten<
+  Omit<RestControllerMetadata, 'className'>
+>;
 
 /**
- * Controller decorator.
+ * Rest controller decorator.
  *
  * @param pathOrOptions
  * @param options
  */
-export function controller<T extends object>(
-  pathOrOptions?: string | ControllerOptions,
-  options?: ControllerOptions,
+export function restController<T extends object>(
+  pathOrOptions?: string | RestControllerOptions,
+  options?: RestControllerOptions,
 ) {
   return function (target: Constructor<T>) {
     const decoratorType = getDecoratorTargetType(target);
     if (decoratorType !== DecoratorTargetType.CONSTRUCTOR)
-      throw new Error('@controller decorator is only supported on a class.');
+      throw new Error(
+        '@restController decorator is only supported on a class.',
+      );
     // если первый аргумент является строкой,
     // то значение используется в качестве
     // базового пути контроллера
@@ -48,7 +52,7 @@ export function controller<T extends object>(
     else if (typeof pathOrOptions === 'object') {
       options = pathOrOptions;
     }
-    ControllerReflector.setMetadata(
+    RestControllerReflector.setMetadata(
       {...options, className: target.name},
       target,
     );

package/src/decorators/{controller/controller-metadata.ts → rest-controller/rest-controller-metadata.ts}

@@ -1,11 +1,11 @@
+import {MetadataKey} from '@e22m4u/ts-reflector';
 import {RoutePreHandler} from '@e22m4u/js-trie-router';
 import {RoutePostHandler} from '@e22m4u/js-trie-router';
-import {MetadataKey} from '@e22m4u/ts-reflector';
 
 /**
- * Controller metadata.
+ * Rest controller metadata.
  */
-export type ControllerMetadata = {
+export type RestControllerMetadata = {
   className: string;
   path?: string;
   before?: RoutePreHandler | RoutePreHandler[];
@@ -13,8 +13,7 @@ export type ControllerMetadata = {
 };
 
 /**
- * Controller metadata key.
+ * Rest controller metadata key.
  */
-export const CONTROLLER_METADATA_KEY = new MetadataKey<ControllerMetadata>(
-  'controllerMetadataKey',
-);
+export const REST_CONTROLLER_METADATA_KEY =
+  new MetadataKey<RestControllerMetadata>('restControllerMetadataKey');

package/src/decorators/{controller/controller-reflector.spec.ts → rest-controller/rest-controller-reflector.spec.ts}

@@ -1,16 +1,19 @@
 import {expect} from 'chai';
 import {describe} from 'mocha';
 import {Reflector} from '@e22m4u/ts-reflector';
-import {ControllerReflector} from './controller-reflector.js';
-import {CONTROLLER_METADATA_KEY} from './controller-metadata.js';
+import {RestControllerReflector} from './rest-controller-reflector.js';
+import {REST_CONTROLLER_METADATA_KEY} from './rest-controller-metadata.js';
 
-describe('ControllerReflector', function () {
+describe('RestControllerReflector', function () {
   describe('setMetadata', function () {
     it('sets a given value as target metadata', function () {
       class Target {}
       const md = {className: 'Target'};
-      ControllerReflector.setMetadata(md, Target);
-      const res = Reflector.getOwnMetadata(CONTROLLER_METADATA_KEY, Target);
+      RestControllerReflector.setMetadata(md, Target);
+      const res = Reflector.getOwnMetadata(
+        REST_CONTROLLER_METADATA_KEY,
+        Target,
+      );
       expect(res).to.be.eq(md);
     });
 
@@ -18,11 +21,17 @@ describe('ControllerReflector', function () {
       class Target {}
       const md1 = {className: 'Target', path: 'path1'};
       const md2 = {className: 'Target', path: 'path2'};
-      ControllerReflector.setMetadata(md1, Target);
-      const res1 = Reflector.getOwnMetadata(CONTROLLER_METADATA_KEY, Target);
+      RestControllerReflector.setMetadata(md1, Target);
+      const res1 = Reflector.getOwnMetadata(
+        REST_CONTROLLER_METADATA_KEY,
+        Target,
+      );
       expect(res1).to.be.eq(md1);
-      ControllerReflector.setMetadata(md2, Target);
-      const res2 = Reflector.getOwnMetadata(CONTROLLER_METADATA_KEY, Target);
+      RestControllerReflector.setMetadata(md2, Target);
+      const res2 = Reflector.getOwnMetadata(
+        REST_CONTROLLER_METADATA_KEY,
+        Target,
+      );
       expect(res2).to.be.eq(md2);
     });
   });
@@ -31,14 +40,14 @@ describe('ControllerReflector', function () {
     it('returns an existing metadata of the target', function () {
       class Target {}
       const md = {className: 'Target'};
-      Reflector.defineMetadata(CONTROLLER_METADATA_KEY, md, Target);
-      const res = ControllerReflector.getMetadata(Target);
+      Reflector.defineMetadata(REST_CONTROLLER_METADATA_KEY, md, Target);
+      const res = RestControllerReflector.getMetadata(Target);
       expect(res).to.be.eq(md);
     });
 
     it('returns undefined if no metadata', function () {
       class Target {}
-      const res = ControllerReflector.getMetadata(Target);
+      const res = RestControllerReflector.getMetadata(Target);
       expect(res).to.be.undefined;
     });
   });

package/src/decorators/rest-controller/rest-controller-reflector.ts

@@ -0,0 +1,32 @@
+import {Constructor} from '../../types.js';
+import {Reflector} from '@e22m4u/ts-reflector';
+import {RestControllerMetadata} from './rest-controller-metadata.js';
+import {REST_CONTROLLER_METADATA_KEY} from './rest-controller-metadata.js';
+
+/**
+ * Rest controller reflector.
+ */
+export class RestControllerReflector {
+  /**
+   * Set metadata.
+   *
+   * @param metadata
+   * @param target
+   */
+  static setMetadata(metadata: RestControllerMetadata, target: Constructor) {
+    return Reflector.defineMetadata(
+      REST_CONTROLLER_METADATA_KEY,
+      metadata,
+      target,
+    );
+  }
+
+  /**
+   * Get metadata.
+   *
+   * @param target
+   */
+  static getMetadata(target: Constructor): RestControllerMetadata | undefined {
+    return Reflector.getOwnMetadata(REST_CONTROLLER_METADATA_KEY, target);
+  }
+}

package/src/errors/not-a-controller-error.ts

@@ -10,6 +10,9 @@ export class NotAControllerError extends Errorf {
    * @param value
    */
   constructor(value: unknown) {
-    super('%v is not a controller, do use @controller decorator on it.', value);
+    super(
+      '%v is not a controller, do use @restController decorator on it.',
+      value,
+    );
   }
 }

package/src/types.ts

@@ -36,16 +36,6 @@ export type Identity<T> = T;
  */
 export type Flatten<T> = Identity<{[k in keyof T]: T[k]}>;
 
-/**
- * A promise or value.
- */
-export type ValueOrPromise<T> = T | PromiseLike<T>;
-
-/**
- * Plain object.
- */
-export type PlainObject = {[key: string]: unknown};
-
 /**
  * Remove null and undefined from T.
  */

package/src/utils/index.ts

@@ -1,4 +1,3 @@
 export * from './capitalize.js';
 export * from './create-error.js';
 export * from './to-camel-case.js';
-export * from './create-debugger.js';

package/README-ru.md

@@ -1,268 +0,0 @@
-# @e22m4u/ts-rest-router
-
-*[English](./README.md) | Русский*
-
-Реализация REST маршрутизатора на основе контроллеров для TypeScript.
-
-#### Основные возможности
-
-- Декларативное определение маршрутов через декораторы.
-- Типизированные параметры запросов (body, query, params).
-- Поддержка middleware до и после обработки запроса.
-- Валидация входящих данных.
-- Поддержка всех HTTP методов (GET, POST, PUT, DELETE и т.д.).
-
-## Установка
-
-```bash
-npm install @e22m4u/ts-rest-router
-```
-
-#### Поддержка декораторов
-
-Для включения поддержки декораторов, добавьте указанные
-ниже опции в файл `tsconfig.json` вашего проекта.
-
-```json
-{
-  "emitDecoratorMetadata": true,
-  "experimentalDecorators": true
-}
-```
-
-## Базовое использование
-
-Создание контроллера и методов
-
-```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
-  async login(
-    @field('username', {      // поле "username" в теле запроса
-      type: DataType.STRING,  // тип параметра допускает только строки
-      required: true,         // параметр является обязательным
-    })
-    username: string,
-    @field('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` - тело запроса
-- `@field` - поле в теле запроса
-- `@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` включает вывод логов.
-
-```bash
-DEBUG=tsRestRouter* npm run test
-```
-
-## Тесты
-
-```bash
-npm run test
-```
-
-## Лицензия
-
-MIT

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

@@ -1,52 +0,0 @@
-import { Flatten } from '../../types.js';
-import { Prototype } from '../../types.js';
-import { ActionMetadata } from './action-metadata.js';
-/**
- * Action options.
- */
-export type ActionOptions = Flatten<Omit<ActionMetadata, 'propertyKey'>>;
-/**
- * Action decorator.
- *
- * @param options
- */
-export declare function action<T extends object>(options: ActionOptions): (target: Prototype<T>, propertyKey: string, descriptor: PropertyDescriptor) => void;
-/**
- * Action method options.
- */
-export type ActionMethodOptions = Flatten<Omit<ActionOptions, 'method' | 'path'>>;
-/**
- * Get decorator.
- *
- * @param path
- * @param options
- */
-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?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
-/**
- * Put decorator.
- *
- * @param path
- * @param options
- */
-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?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;
-/**
- * Del decorator.
- *
- * @param path
- * @param options
- */
-export declare const del: (path: string, options?: ActionMethodOptions) => (target: Prototype<object>, propertyKey: string, descriptor: PropertyDescriptor) => void;

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

@@ -1,62 +0,0 @@
-import { HttpMethod } from '@e22m4u/js-trie-router';
-import { ActionReflector } from './action-reflector.js';
-import { DecoratorTargetType } from '@e22m4u/ts-reflector';
-import { getDecoratorTargetType } from '@e22m4u/ts-reflector';
-/**
- * Action decorator.
- *
- * @param options
- */
-export function action(options) {
-    return function (target, propertyKey, descriptor) {
-        const decoratorType = getDecoratorTargetType(target, propertyKey, descriptor);
-        if (decoratorType !== DecoratorTargetType.INSTANCE_METHOD)
-            throw new Error('@action decorator is only supported on an instance method.');
-        ActionReflector.setMetadata({ ...options, propertyKey }, target.constructor, propertyKey);
-    };
-}
-/**
- * Get decorator.
- *
- * @param path
- * @param options
- */
-export const get = (path, options) => {
-    return action({ ...options, path, method: HttpMethod.GET });
-};
-/**
- * Post decorator.
- *
- * @param path
- * @param options
- */
-export const post = (path, options) => {
-    return action({ ...options, path, method: HttpMethod.POST });
-};
-/**
- * Put decorator.
- *
- * @param path
- * @param options
- */
-export const put = (path, options) => {
-    return action({ ...options, path, method: HttpMethod.PUT });
-};
-/**
- * Patch decorator.
- *
- * @param path
- * @param options
- */
-export const patch = (path, options) => {
-    return action({ ...options, path, method: HttpMethod.PATCH });
-};
-/**
- * Del decorator.
- *
- * @param path
- * @param options
- */
-export const del = (path, options) => {
-    return action({ ...options, path, method: HttpMethod.DELETE });
-};