Merge pull request #15 from medishen/dev/v2

Fix event system and enhance decorators with unit tests

lib/common/enums/router.enum.ts

@@ -1,7 +1,7 @@
 export enum RouterMetadataKeys {
   CONTROLLER_PREFIX = 'router:controller:prefix',
   ROUTES = 'router:routes',
-  MULTI_LANG = 'router:multiLang',
+  MULTI_LANGUAGE = 'router:multiLanguage',
   TRANSFORM = 'router:transform',
   MIDDLEWARES = 'router:middlewares',
   GUARDS = 'router:guards',

lib/common/interfaces/context.interface.ts

@@ -67,12 +67,12 @@ export interface TransformContext {
   query?: ServerRequest['query'];
   body?: ServerRequest['body'];
   headers?: ServerRequest['req']['headers'];
-  method: ServerRequest['req']['method'];
-  path: RouteDefinition['path'];
-  clientIp: ServerRequest['clientIp'];
+  method?: ServerRequest['req']['method'];
+  path?: RouteDefinition['path'];
+  clientIp?: ServerRequest['clientIp'];
   userAgent?: string;
   cookies?: Record<string, string>;
-  protocol: 'http' | 'https';
+  protocol?: 'http' | 'https';
   referer?: string;
   acceptedLanguages?: string[] | string;
 }

lib/common/interfaces/module.interface.ts

@@ -25,9 +25,17 @@ export interface ExistingProvider {
   provide: InjectionToken;
   useExisting: InjectionToken; // An alias for another provider
 }
+export type ImportableModule = Constructor<any> | DynamicModule;
 
+export interface DynamicModule {
+  module: Constructor<any>;
+  providers?: Provider[];
+  exports?: InjectionToken[]; // Tokens to make available to other modules
+  imports?: ImportableModule[]; // Nested imports for the dynamic module
+}
 export interface ModuleMetadata {
   controllers?: Constructor<any>[];
-
   providers?: Provider[];
+  imports?: ImportableModule[]; // Other modules or dynamic modules imported
+  exports?: InjectionToken[];
 }

lib/common/types/app.types.ts

@@ -1,5 +1,5 @@
 export type ParsedBody = {
-  body: Record<string, any> | string | undefined | { [key: string]: any } | null;
-  bodyRaw: Buffer | undefined;
+  body: Record<string, any> | { [key: string]: any } | null;
+  bodyRaw: Buffer | null;
   bodySize: number | string;
 };

lib/common/types/event.type.ts

@@ -1,5 +1,6 @@
 import { CoreEventType, HttpStatus } from '../enums';
 import { EventHandlers, RouteDefinition, ServerRequest } from '../interfaces';
+export type EventListener<T extends CoreEventType> = { route: string; handler: EventHandler<T> } | { handler: EventHandler<T> };
 
 export type EventHandlerMap = {
   [CoreEventType.Start]: EventHandlers['StartHandler'];
@@ -24,5 +25,5 @@ export type CommonContextProps = {
   timestamp?: Date;
   statusMessage?: keyof typeof HttpStatus;
   statusCodeClass?: '1xx' | '2xx' | '3xx' | '4xx' | '5xx' | 'Unknown';
-  ctx: ServerRequest;
+  ctx?: ServerRequest;
 };

lib/core/Application.ts

@@ -1,14 +1,13 @@
 import { IncomingMessage, ServerResponse, Server, createServer } from 'http';
-import Reflector from '../metadata';
 import { CoreModule } from './CoreModule';
 import { Router } from '../router';
 import { MiddlewareStack } from '../middleware';
 import { setPoweredByHeader } from '../utils';
 import { Context, ContextFactory } from '../context';
 import { Injector } from '../decorator';
-import { AppConfig, Constructor, LifecycleEvents, RouteDefinition } from '../common/interfaces';
-import { CoreEventType, KEY_SETTINGS, ModuleMetadataKeys, RouterMetadataKeys } from '../common/enums';
-import { AppConfigKey, AppConfigValue, EventHandler, EventType, GlobalCache, MiddlewareFn, Provider } from '../common/types';
+import { AppConfig, Constructor, LifecycleEvents } from '../common/interfaces';
+import { CoreEventType, KEY_SETTINGS } from '../common/enums';
+import { AppConfigKey, AppConfigValue, EventHandler, EventType, GlobalCache, MiddlewareFn } from '../common/types';
 export class Application {
   private readonly coreModule: CoreModule;
   private readonly router: Router;

lib/decorator/Controller.ts

@@ -1,12 +1,39 @@
 import { RouterMetadataKeys } from '../common/enums';
 import Reflector from '../metadata';
-
+import { RouteNormalizer, RouteValidation } from '../utils';
+/**
+ * A decorator to define a controller with a route prefix.
+ * It combines the provided prefix with any existing controller prefix and ensures the final prefix is normalized.
+ * The decorator stores the full normalized prefix in the metadata for later use.
+ *
+ * @param prefix The prefix to be applied to the controller's route. It will be normalized.
+ * @returns A class decorator that defines the controller's route prefix.
+ *
+ * @example
+ * // Example of usage
+ * @Controller('/api')
+ * class ApiController {
+ *   // This controller will have a base route of '/api'
+ * }
+ *
+ * @example
+ * // Example with combined prefix
+ * @Controller('/api')
+ * @Controller('/v1')
+ * class VersionedApiController {
+ *   // This controller will have a base route of '/api/v1'
+ * }
+ */
 export function Controller(prefix: string): ClassDecorator {
   return (target) => {
+    // Validate prefix using RouteValidation
+    if (!RouteValidation.isValidPath(prefix)) {
+      throw new Error(`Invalid route prefix: "${prefix}". Prefix cannot be empty or contain invalid characters.`);
+    }
     const existingPrefix = Reflector.get(RouterMetadataKeys.CONTROLLER_PREFIX, target);
-    let fullPrefix = prefix;
+    let fullPrefix = RouteNormalizer.normalizePath(prefix);
     if (existingPrefix) {
-      fullPrefix = `${existingPrefix}${prefix}`.replace(/\/+$/, '');
+      fullPrefix = RouteNormalizer.combinePaths(existingPrefix, prefix);
     }
     Reflector.define(RouterMetadataKeys.CONTROLLER_PREFIX, fullPrefix, target);
   };

lib/decorator/MultiLang.ts

@@ -1,9 +1,35 @@
 import { RouterMetadataKeys } from '../common/enums';
 import { MultiLanguageContext } from '../common/interfaces';
 import Reflector from '../metadata';
-
+/**
+ * @module MultiLanguage
+ * @description
+ * The `@MultiLanguage` decorator is used to register multiple translations for a route.
+ * It automatically selects the language based on the 'accept-language' header of the request,
+ * providing the correct route or translation for that language.
+ *
+ * @param {MultiLanguageContext} translations - An object containing language mappings.
+ *
+ * @example
+ * ```typescript
+ * import { MultiLanguage } from './decorators/MultiLanguage';
+ * import { MultiLanguageContext } from './common/interfaces';
+ *
+ * class ExampleController {
+ *   @MultiLanguage({
+ *     en: '/foo',     // English route
+ *     fr: '/bar',    // French route
+ *     default: '/foo' // Default route
+ *   })
+ *   public handleRequest(ctx: ServerRequest) {
+ *     console.log(`Selected language: ${ctx.language}`);
+ *     ctx.end()
+ *   }
+ * }
+ * ```
+ */
 export function MultiLanguage(translations: MultiLanguageContext): MethodDecorator {
   return (target) => {
-    Reflector.define(RouterMetadataKeys.MULTI_LANG, translations, target.constructor);
+    Reflector.define(RouterMetadataKeys.MULTI_LANGUAGE, translations, target.constructor);
   };
 }

lib/decorator/Transform.ts

@@ -25,14 +25,15 @@ import Reflector from '../metadata';
  *       ctx.body.modified = true;
  *     }
  *   })
- *   public handleRequest() {
+ *   public handleRequest(ctx: ServerRequest) {
  *     console.log('Request handled');
+ *     ctx.res.end("Hello, World")
  *   }
  * }
  * ```
  */
 export function Transform(transformFn: (ctx: TransformContext) => void): MethodDecorator {
-  return (target: any, propertyKey) => {
+  return (target, propertyKey) => {
     Reflector.define(RouterMetadataKeys.TRANSFORM, transformFn, target.constructor, propertyKey);
   };
 }

lib/decorator/http.ts

@@ -2,17 +2,55 @@ import { RequestMethod, RouterMetadataKeys } from '../common/enums';
 import { RouteDefinition } from '../common/interfaces';
 import { MiddlewareFn } from '../common/types';
 import Reflector from '../metadata';
+import { RouteNormalizer, RouteValidation } from '../utils';
+/**
+ * @module Route Decorators
+ * @description
+ * This module provides decorators for HTTP methods (e.g., `@Get`, `@Post`, `@Put`, etc.).
+ * These decorators are used to define routes in the application and are mapped to the respective HTTP methods.
+ * They allow specifying the path for the route and optional middleware functions for request processing.
+ * The decorators also integrate with the `Reflector` to store route metadata that can be used later by the framework.
+ *
+ * The function `createDecorator` is a generator that creates HTTP method decorators like `@Get`, `@Post`, etc.
+ * Each of these decorators can be applied to controller methods to bind routes to HTTP requests.
+ *
+ * @example
+ * // Example of usage for @Get decorator:
+ * @Controller('/app')
+ * class AppController {
+ *   @Get('/hello')
+ *   getHello(ctx: ServerRequest) {
+ *     ctx.send('Hello World!');
+ *   }
+ * }
+ *
+ * @example
+ * // Example with middleware for @Post decorator:
+ * @Controller('/app')
+ * class AppController {
+ *   @Post('/create', [routeMid])
+ *   createResource(ctx: ServerRequest) {
+ *     ctx.send('Resource Created');
+ *   }
+ * }
+ */
 function createDecorator(method: RequestMethod) {
   return (path: string, middlewares?: MiddlewareFn[]): MethodDecorator => {
-    return (target, __, descriptor) => {
+    if (!Object.values(RequestMethod).includes(method)) {
+      throw new Error(`Invalid RequestMethod: ${method}`);
+    }
+    // Validate prefix using RouteValidation
+    if (!RouteValidation.isValidPath(path)) {
+      throw new Error(`Invalid route prefix: "${path}". Prefix cannot be empty or contain invalid characters.`);
+    }
+    return (target, propertyKey, descriptor) => {
       if (!descriptor || typeof descriptor.value !== 'function') {
         throw new Error(`@${method} decorator must be applied to a method.`);
       }
+      RouteNormalizer.validateMethod(target, propertyKey);
       const controllerPrefix = Reflector.get(RouterMetadataKeys.CONTROLLER_PREFIX, target.constructor);
-      let fullPath = path;
-      if (controllerPrefix) {
-        fullPath = `${controllerPrefix}${path}`.replace(/\/+$/, '');
-      }
+      const normalizedPath = RouteNormalizer.normalizePath(path);
+      const fullPath = RouteNormalizer.combinePaths(controllerPrefix, normalizedPath);
       const existingRoutes: RouteDefinition[] = Reflector.get(RouterMetadataKeys.ROUTES, target.constructor) ?? [];
       existingRoutes.push({
         method,
@@ -27,9 +65,26 @@ function createDecorator(method: RequestMethod) {
     };
   };
 }
-export function createMethodDecorators() {
-  return Object.values(RequestMethod).map((method: RequestMethod) => {
-    return createDecorator(method);
-  });
-}
-export const [Get, Post, Put, Delete, Patch, Options, Head, Search] = createMethodDecorators();
+
+/**
+ * HTTP method decorators for common HTTP methods. These decorators can be applied to controller methods
+ * to map them to specific HTTP routes. Each decorator accepts a path and optional middleware functions.
+ *
+ * - @Get: Maps the method to a GET route.
+ * - @Post: Maps the method to a POST route.
+ * - @Put: Maps the method to a PUT route.
+ * - @Delete: Maps the method to a DELETE route.
+ * - @Patch: Maps the method to a PATCH route.
+ * - @Options: Maps the method to an OPTIONS route.
+ * - @Head: Maps the method to a HEAD route.
+ * - @Search: Maps the method to a SEARCH route.
+ */
+export const Get = createDecorator(RequestMethod.Get);
+export const Post = createDecorator(RequestMethod.Post);
+export const Put = createDecorator(RequestMethod.Put);
+export const Delete = createDecorator(RequestMethod.Delete);
+export const Patch = createDecorator(RequestMethod.Patch);
+export const Options = createDecorator(RequestMethod.Options);
+export const Head = createDecorator(RequestMethod.Head);
+export const Search = createDecorator(RequestMethod.Search);
+export const All = createDecorator(RequestMethod.All);