@e22m4u/ts-rest-router 0.0.2

package/src/controller-registry.ts

@@ -0,0 +1,355 @@
+import {AnyObject} from './types.js';
+import {Constructor} from './types.js';
+import {Errorf} from '@e22m4u/js-format';
+import {TrieRouter} from '@e22m4u/js-trie-router';
+import {RouteHandler} from '@e22m4u/js-trie-router';
+import {DataValidator} from '@e22m4u/ts-data-schema';
+import {DataTypeCaster} from '@e22m4u/ts-data-schema';
+import {ActionReflector} from './decorators/index.js';
+import {NotAControllerError} from './errors/index.js';
+import {RequestContext} from '@e22m4u/js-trie-router';
+import {RoutePreHandler} from '@e22m4u/js-trie-router';
+import {RoutePostHandler} from '@e22m4u/js-trie-router';
+import {RequestDataSource} from './decorators/index.js';
+import {ControllerMetadata} from './decorators/index.js';
+import {DebuggableService} from './debuggable-service.js';
+import {ControllerReflector} from './decorators/index.js';
+import {RequestDataReflector} from './decorators/index.js';
+import {RequestContextReflector} from './decorators/index.js';
+
+/**
+ * Controller root options.
+ */
+export type ControllerRootOptions = {
+  pathPrefix?: string;
+  before?: RoutePreHandler | RoutePreHandler[];
+  after?: RoutePostHandler | RoutePostHandler[];
+};
+
+/**
+ * Controller registry.
+ */
+export class ControllerRegistry extends DebuggableService {
+  /**
+   * Controllers.
+   */
+  controllers = new Set();
+
+  /**
+   * Add controller.
+   *
+   * @param ctor
+   * @param options
+   */
+  addController<T extends object>(
+    ctor: Constructor<T>,
+    options?: ControllerRootOptions,
+  ): this {
+    // проверка повторной регистрации помогает
+    // заметить ошибку в коде, который использует
+    // интерфейс данного сервиса
+    if (this.hasController(ctor))
+      throw new Errorf('The controller %v is already registered.');
+    // так как контроллером может быть любой
+    // класс, выполняется проверка на наличие
+    // метаданных применяемых декоратором
+    const controllerMd = ControllerReflector.getMetadata(ctor);
+    if (!controllerMd) throw new NotAControllerError(ctor);
+    this.debug('Adding controller %s.', ctor.name);
+    // определение префикса применяемого
+    // к маршрутам контроллера
+    const pathPrefix = this.getPathPrefixByControllerMetadata(
+      controllerMd,
+      options,
+    );
+    this.debug('Path prefix is %v.', pathPrefix);
+    // подготовка pre-обработчиков
+    const preHandlers = this.getPreHandlersByControllerMetadata(
+      controllerMd,
+      options,
+    );
+    this.debug('%v total pre-handlers found.', preHandlers.length);
+    // подготовка post-обработчиков
+    const postHandlers = this.getPostHandlersByControllerMetadata(
+      controllerMd,
+      options,
+    );
+    this.debug('%v total post-handlers found.', postHandlers.length);
+    // обход всех операций контроллера
+    // для определения маршрутов
+    const actionsMd = ActionReflector.getMetadata(ctor);
+    this.debug('%v actions found.', actionsMd.size);
+    const router = this.getService(TrieRouter);
+    actionsMd.forEach((actionMd, actionName) => {
+      this.debug('Adding route for %s.%s.', ctor.name, actionName);
+      // подготовка пути маршрута с префиксом
+      this.debug('Route path is %v.', actionMd.path);
+      const prefixedRoutePath = `${pathPrefix}/${actionMd.path}`.replace(
+        /\/\//g,
+        '/',
+      );
+      this.debug('Prefixed route path is %v.', prefixedRoutePath);
+      // подготовка pre-обработчиков операции
+      const actionPreHandlers = Array.isArray(actionMd.before)
+        ? actionMd.before
+        : actionMd.before
+          ? [actionMd.before]
+          : [];
+      this.debug('%v action pre-handlers found.', actionPreHandlers.length);
+      const mergedPreHandlers = [...preHandlers, ...actionPreHandlers];
+      // подготовка post-обработчиков операции
+      const actionPostHandlers = Array.isArray(actionMd.after)
+        ? actionMd.after
+        : actionMd.after
+          ? [actionMd.after]
+          : [];
+      this.debug('%v action post-handlers found.', actionPostHandlers.length);
+      const mergedPostHandlers = [...postHandlers, ...actionPostHandlers];
+      // подготовка обработчика маршрута
+      const routeHandler = this.createRouteHandler(ctor, actionName);
+      router.defineRoute({
+        method: actionMd.method,
+        path: prefixedRoutePath,
+        preHandler: mergedPreHandlers,
+        handler: routeHandler,
+        postHandler: mergedPostHandlers,
+      });
+      this.debug(
+        'Route %s %v is added.',
+        actionMd.method.toUpperCase(),
+        prefixedRoutePath,
+      );
+    });
+    this.controllers.add(ctor);
+    return this;
+  }
+
+  /**
+   * Has controller.
+   *
+   * @param ctor
+   */
+  hasController<T extends object>(ctor: Constructor<T>) {
+    return this.controllers.has(ctor);
+  }
+
+  /**
+   * Get path prefix by controller metadata.
+   *
+   * @param controllerMd
+   * @param options
+   */
+  getPathPrefixByControllerMetadata(
+    controllerMd: ControllerMetadata,
+    options?: ControllerRootOptions,
+  ) {
+    const rootPathPrefix = options?.pathPrefix || '';
+    this.debug('Root path prefix is %v.', rootPathPrefix);
+    const controllerPathPrefix = controllerMd.path || '';
+    this.debug('Controller path prefix is %v.', controllerPathPrefix);
+    const mergedPathPrefix = `/${rootPathPrefix}/${controllerPathPrefix}`
+      .replace(/\/\//g, '/')
+      .replace(/\/$/, '');
+    this.debug('Merged path prefix is %v.', mergedPathPrefix);
+    return mergedPathPrefix;
+  }
+
+  /**
+   * Get pre-handlers by controller metadata.
+   *
+   * @param controllerMd
+   * @param options
+   */
+  getPreHandlersByControllerMetadata(
+    controllerMd: ControllerMetadata,
+    options?: ControllerRootOptions,
+  ) {
+    // подготовка дополнительных
+    // pre-обработчиков запроса
+    let rootPreHandlers: RoutePreHandler[] = [];
+    if (options?.before)
+      rootPreHandlers = Array.isArray(options?.before)
+        ? options.before
+        : [options.before];
+    this.debug('%v root pre-handlers found.', rootPreHandlers.length);
+    // подготовка pre-обработчиков
+    // запроса контроллера
+    let ctlPreHandlers: RoutePreHandler[] = [];
+    if (controllerMd.before)
+      ctlPreHandlers = Array.isArray(controllerMd.before)
+        ? controllerMd.before
+        : [controllerMd.before];
+    this.debug('%v controller pre-handlers found.', ctlPreHandlers.length);
+    // подготовка объединенного набора
+    // pre-обработчиков запроса
+    const mergedPreHandlers = [...rootPreHandlers, ...ctlPreHandlers];
+    this.debug('%v merged pre-handlers.', mergedPreHandlers.length);
+    return mergedPreHandlers;
+  }
+
+  /**
+   * Get post-handlers by controller metadata.
+   *
+   * @param controllerMd
+   * @param options
+   */
+  getPostHandlersByControllerMetadata(
+    controllerMd: ControllerMetadata,
+    options?: ControllerRootOptions,
+  ) {
+    // подготовка дополнительных
+    // post-обработчиков запроса
+    let rootPostHandlers: RoutePostHandler[] = [];
+    if (options?.after)
+      rootPostHandlers = Array.isArray(options.after)
+        ? options.after
+        : [options.after];
+    this.debug('%v root post-handlers found.', rootPostHandlers.length);
+    // подготовка post-обработчиков
+    // запроса контроллера
+    let ctlPostHandlers: RoutePostHandler[] = [];
+    if (controllerMd.after)
+      ctlPostHandlers = Array.isArray(controllerMd.after)
+        ? controllerMd.after
+        : [controllerMd.after];
+    this.debug('%v controller post-handlers found.', ctlPostHandlers.length);
+    // подготовка объединенного набора
+    // post-обработчиков запроса
+    const mergedPostHandlers = [...rootPostHandlers, ...ctlPostHandlers];
+    this.debug('%v merged post-handlers.', mergedPostHandlers.length);
+    return mergedPostHandlers;
+  }
+
+  /**
+   * Create route handler.
+   *
+   * @param controllerCtor
+   * @param actionName
+   * @protected
+   */
+  createRouteHandler<T extends object>(
+    controllerCtor: Constructor<T>,
+    actionName: string,
+  ): RouteHandler {
+    this.debug(
+      'Creating route handler for %s.%s.',
+      controllerCtor.name,
+      actionName,
+    );
+    const requestContextMetadataMap = RequestContextReflector.getMetadata(
+      controllerCtor,
+      actionName,
+    );
+    const requestDataMetadataMap = RequestDataReflector.getMetadata(
+      controllerCtor,
+      actionName,
+    );
+    const argsNumber = controllerCtor.prototype[actionName].length;
+    const dataTypeCaster = this.getService(DataTypeCaster);
+    const dataValidator = this.getService(DataValidator);
+    return (requestContext: RequestContext) => {
+      this.debug(
+        'Executing route handler for %s.%s.',
+        controllerCtor.name,
+        actionName,
+      );
+      const args = Array(argsNumber).map((value, index) => {
+        if (value != null) return value;
+        // заполнение аргументов операции
+        // значениями из контекста запроса
+        const requestContextMd = requestContextMetadataMap.get(index);
+        if (requestContextMd != null) {
+          this.debug('Argument %v has request context metadata.', index);
+          // если свойство контекста не определено,
+          // то используем весь объект контекста
+          // в качестве значения текущего аргумента
+          if (requestContextMd.property == null) {
+            this.debug('Request context property is not specified.');
+            this.debug('Argument %v is set to %v.', index, requestContext);
+            return requestContext;
+          }
+          // если свойство контекста определено,
+          // то используем значение этого свойства
+          // в качестве текущего аргумента
+          const propName = requestContextMd.property;
+          const propValue = requestContext[propName];
+          this.debug('Request context property is %v.', propName);
+          this.debug('Argument %v is set to %v.', index, propValue);
+          return propValue;
+        } else {
+          this.debug(
+            'No RequestContextMetadata specified for %v argument.',
+            index,
+          );
+        }
+        // заполнение аргументов операции
+        // значениями из данных запроса
+        const requestDataMd = requestDataMetadataMap.get(index);
+        if (requestDataMd != null) {
+          this.debug('Argument %v has request data metadata.', index);
+          // получение данных
+          // согласно источнику
+          let data: unknown;
+          switch (requestDataMd.source) {
+            case RequestDataSource.PARAMS:
+              data = requestContext.params;
+              break;
+            case RequestDataSource.QUERY:
+              data = requestContext.query;
+              break;
+            case RequestDataSource.HEADERS:
+              data = requestContext.headers;
+              break;
+            case RequestDataSource.COOKIE:
+              data = requestContext.cookie;
+              break;
+            case RequestDataSource.BODY:
+              data = requestContext.body;
+              break;
+          }
+          this.debug('Request data source is %v.', requestDataMd.source);
+          // при наличии схемы данных выполняется
+          // их конвертация и валидация
+          if (requestDataMd.schema) {
+            data = dataTypeCaster.cast(data, requestDataMd.schema, {
+              noTypeCastError: true,
+              sourcePath: requestDataMd.source,
+            });
+            this.debug('Data type casting is passed.');
+            dataValidator.validate(
+              data,
+              requestDataMd.schema,
+              requestDataMd.source,
+            );
+            this.debug('Data validation is passed.');
+          }
+          // если свойство данных не определено,
+          // то используем весь объекта данных
+          // в качестве значения текущего аргумента
+          if (requestDataMd.property == null) {
+            this.debug('Request data property is not specified.');
+            this.debug('Argument %v is set to %v.', index, data);
+            return data;
+          }
+          // если свойство данных определено,
+          // то используем значение этого свойства
+          // в качестве текущего аргумента
+          const dataAsObject = data as Record<string, unknown>;
+          const propName = requestDataMd.property;
+          const propValue = dataAsObject[propName];
+          this.debug('Request data property is %v.', propName);
+          this.debug('Argument %v is set to %v.', index, propValue);
+          return propValue;
+        } else {
+          this.debug(
+            'No RequestDataMetadata specified for %v argument.',
+            index,
+          );
+        }
+      });
+      // выполнение операции контроллера
+      const controller = this.getService(controllerCtor);
+      return (controller as AnyObject)[actionName](...args);
+    };
+  }
+}

package/src/debuggable-service.spec.ts

@@ -0,0 +1,18 @@
+import {expect} from 'chai';
+import {describe} from 'mocha';
+import {Service} from '@e22m4u/js-service';
+import {DebuggableService} from './debuggable-service.js';
+
+describe('DebuggableService', function () {
+  it('has the debug method', function () {
+    const res = new DebuggableService();
+    expect(typeof res.debug).to.be.eq('function');
+  });
+
+  describe('constructor', function () {
+    it('extends the Service class', function () {
+      const res = new DebuggableService();
+      expect(res).to.be.instanceof(Service);
+    });
+  });
+});

package/src/debuggable-service.ts

@@ -0,0 +1,27 @@
+import {Debugger} from './utils/index.js';
+import {Service} from '@e22m4u/js-service';
+import {toCamelCase} from './utils/index.js';
+import {createDebugger} from './utils/index.js';
+import {ServiceContainer} from '@e22m4u/js-service';
+
+/**
+ * Service.
+ */
+export class DebuggableService extends Service {
+  /**
+   * Debug.
+   */
+  debug: Debugger;
+
+  /**
+   * Constructor.
+   *
+   * @param container
+   */
+  constructor(container?: ServiceContainer) {
+    super(container);
+    const serviceName = toCamelCase(this.constructor.name);
+    this.debug = createDebugger(serviceName);
+    this.debug('%v is created.', this.constructor);
+  }
+}

package/src/decorators/action/action-decorator.spec.ts

@@ -0,0 +1,42 @@
+import {expect} from 'chai';
+import {action} from './action-decorator.js';
+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';
+    class Target {
+      @action({method, path, before, after, customOption})
+      method() {}
+    }
+    const res = ActionReflector.getMetadata(Target);
+    expect(res.get('method')).to.be.eql({
+      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';
+    class Target {
+      @action({propertyKey: 'myMethod', method, path})
+      method() {}
+    }
+    const res = ActionReflector.getMetadata(Target);
+    expect(res.get('method')).to.be.eql({
+      propertyKey: 'method',
+      method,
+      path,
+    });
+  });
+});

package/src/decorators/action/action-decorator.ts

@@ -0,0 +1,100 @@
+import {Flatten} from '../../types.js';
+import {Prototype} from '../../types.js';
+import {Constructor} from '../../types.js';
+import {HttpMethod} from '@e22m4u/js-trie-router';
+import {ActionMetadata} from './action-metadata.js';
+import {ActionReflector} from './action-reflector.js';
+import {DecoratorTargetType} from '@e22m4u/ts-reflector';
+import {getDecoratorTargetType} from '@e22m4u/ts-reflector';
+
+/**
+ * Action options.
+ */
+export type ActionOptions = Flatten<Omit<ActionMetadata, 'propertyKey'>>;
+
+/**
+ * Action decorator.
+ *
+ * @param options
+ */
+export function action<T extends object>(options: ActionOptions) {
+  return function (
+    target: Prototype<T>,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    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,
+    } as ActionMetadata;
+    ActionReflector.setMetadata(
+      metadata,
+      target.constructor as Constructor<T>,
+      propertyKey,
+    );
+  };
+}
+
+/**
+ * Action alias options.
+ */
+type ActionAliasOptions = Flatten<Omit<ActionOptions, 'method' | 'path'>>;
+
+/**
+ * Get decorator.
+ *
+ * @param path
+ * @param options
+ */
+export const get = (path: string, options?: ActionAliasOptions) => {
+  return action({...options, path, method: HttpMethod.GET});
+};
+
+/**
+ * Post decorator.
+ *
+ * @param path
+ * @param options
+ */
+export const post = (path: string, options?: ActionAliasOptions) => {
+  return action({...options, path, method: HttpMethod.POST});
+};
+
+/**
+ * Put decorator.
+ *
+ * @param path
+ * @param options
+ */
+export const put = (path: string, options?: ActionAliasOptions) => {
+  return action({...options, path, method: HttpMethod.PUT});
+};
+
+/**
+ * Patch decorator.
+ *
+ * @param path
+ * @param options
+ */
+export const patch = (path: string, options?: ActionAliasOptions) => {
+  return action({...options, path, method: HttpMethod.PATCH});
+};
+
+/**
+ * Del decorator.
+ *
+ * @param path
+ * @param options
+ */
+export const del = (path: string, options?: ActionAliasOptions) => {
+  return action({...options, path, method: HttpMethod.DELETE});
+};

package/src/decorators/action/action-metadata.ts

@@ -0,0 +1,28 @@
+import {MetadataKey} from '@e22m4u/ts-reflector';
+import {HttpMethod} from '@e22m4u/js-trie-router';
+import {RoutePreHandler} from '@e22m4u/js-trie-router';
+import {RoutePostHandler} from '@e22m4u/js-trie-router';
+
+/**
+ * Action metadata.
+ */
+export type ActionMetadata = {
+  propertyKey: string;
+  method: HttpMethod;
+  path: string;
+  before?: RoutePreHandler | RoutePreHandler[];
+  after?: RoutePostHandler | RoutePostHandler[];
+  [option: string]: unknown | undefined;
+};
+
+/**
+ * Action metadata map.
+ */
+export type ActionMetadataMap = Map<string, ActionMetadata>;
+
+/**
+ * Actions metadata key.
+ */
+export const ACTIONS_METADATA_KEY = new MetadataKey<ActionMetadataMap>(
+  'actionsMetadataKey',
+);

package/src/decorators/action/action-reflector.spec.ts

@@ -0,0 +1,84 @@
+import {expect} from 'chai';
+import {describe} from 'mocha';
+import {Reflector} from '@e22m4u/ts-reflector';
+import {HttpMethod} from '@e22m4u/js-trie-router';
+import {ActionReflector} from './action-reflector.js';
+import {ACTIONS_METADATA_KEY} from './action-metadata.js';
+
+describe('ActionReflector', function () {
+  describe('setMetadata', function () {
+    it('sets a given value as target metadata', function () {
+      class Target {}
+      const md1 = {
+        propertyKey: 'propertyKey1',
+        method: HttpMethod.GET,
+        path: '/foo',
+      };
+      const md2 = {
+        propertyKey: 'propertyKey2',
+        method: HttpMethod.GET,
+        path: '/bar',
+      };
+      ActionReflector.setMetadata(md1, Target, 'propertyKey1');
+      ActionReflector.setMetadata(md2, Target, 'propertyKey2');
+      const res = Reflector.getOwnMetadata(ACTIONS_METADATA_KEY, Target);
+      expect(res).to.be.instanceof(Map);
+      expect(res!.get('propertyKey1')).to.be.eq(md1);
+      expect(res!.get('propertyKey2')).to.be.eq(md2);
+    });
+
+    it('overrides existing metadata', function () {
+      class Target {}
+      const md1 = {
+        propertyKey: 'propertyKey',
+        method: HttpMethod.GET,
+        path: '/foo',
+      };
+      const md2 = {
+        propertyKey: 'propertyKey',
+        method: HttpMethod.POST,
+        path: '/bar',
+      };
+      ActionReflector.setMetadata(md1, Target, 'propertyKey');
+      const res1 = Reflector.getOwnMetadata(ACTIONS_METADATA_KEY, Target);
+      expect(res1).to.be.instanceof(Map);
+      expect(res1!.get('propertyKey')).to.be.eq(md1);
+      ActionReflector.setMetadata(md2, Target, 'propertyKey');
+      const res2 = Reflector.getOwnMetadata(ACTIONS_METADATA_KEY, Target);
+      expect(res2).to.be.instanceof(Map);
+      expect(res2!.get('propertyKey')).to.be.eq(md2);
+    });
+  });
+
+  describe('getMetadata', function () {
+    it('returns an existing metadata of the target', function () {
+      class Target {}
+      const md1 = {
+        propertyKey: 'propertyKey1',
+        method: HttpMethod.GET,
+        path: '/foo',
+      };
+      const md2 = {
+        propertyKey: 'propertyKey2',
+        method: HttpMethod.GET,
+        path: '/bar',
+      };
+      const mdMap = new Map([
+        ['propertyKey1', md1],
+        ['propertyKey2', md2],
+      ]);
+      Reflector.defineMetadata(ACTIONS_METADATA_KEY, mdMap, Target);
+      const res = ActionReflector.getMetadata(Target);
+      expect(res).to.be.instanceof(Map);
+      expect(res!.get('propertyKey1')).to.be.eq(md1);
+      expect(res!.get('propertyKey2')).to.be.eq(md2);
+    });
+
+    it('returns an empty map if no metadata', function () {
+      class Target {}
+      const res = ActionReflector.getMetadata(Target);
+      expect(res).to.be.instanceof(Map);
+      expect(res).to.be.empty;
+    });
+  });
+});

package/src/decorators/action/action-reflector.ts

@@ -0,0 +1,38 @@
+import {Constructor} from '../../types.js';
+import {Reflector} from '@e22m4u/ts-reflector';
+import {ActionMetadata} from './action-metadata.js';
+import {ActionMetadataMap} from './action-metadata.js';
+import {ACTIONS_METADATA_KEY} from './action-metadata.js';
+
+/**
+ * Action reflector.
+ */
+export class ActionReflector {
+  /**
+   * Set metadata.
+   *
+   * @param metadata
+   * @param target
+   * @param propertyKey
+   */
+  static setMetadata(
+    metadata: ActionMetadata,
+    target: Constructor,
+    propertyKey: string,
+  ) {
+    const oldMap = Reflector.getOwnMetadata(ACTIONS_METADATA_KEY, target);
+    const newMap = new Map(oldMap);
+    newMap.set(propertyKey, metadata);
+    Reflector.defineMetadata(ACTIONS_METADATA_KEY, newMap, target);
+  }
+
+  /**
+   * Get metadata.
+   *
+   * @param target
+   */
+  static getMetadata(target: Constructor): ActionMetadataMap {
+    const metadata = Reflector.getOwnMetadata(ACTIONS_METADATA_KEY, target);
+    return metadata ?? new Map();
+  }
+}