@noxfly/noxus 1.1.1 → 1.1.4

package/src/router.ts

@@ -16,8 +16,11 @@ import { Logger } from 'src/utils/logger';
 import { RadixTree } from 'src/utils/radix-tree';
 import { Type } from 'src/utils/types';
 
-// types & interfaces
-
+/**
+ * IRouteDefinition interface defines the structure of a route in the application.
+ * It includes the HTTP method, path, controller class, handler method name,
+ * guards, and middlewares associated with the route.
+ */
 export interface IRouteDefinition {
     method: string;
     path: string;
@@ -27,23 +30,34 @@ export interface IRouteDefinition {
     middlewares: Type<IMiddleware>[];
 }
 
+/**
+ * This type defines a function that represents an action in a controller.
+ * It takes a Request and an IResponse as parameters and returns a value or a Promise.
+ */
 export type ControllerAction = (request: Request, response: IResponse) => any;
 
 
+/**
+ * Router class is responsible for managing the application's routing.
+ * It registers controllers, handles requests, and manages middlewares and guards.
+ */
 @Injectable('singleton')
 export class Router {
     private readonly routes = new RadixTree<IRouteDefinition>();
     private readonly rootMiddlewares: Type<IMiddleware>[] = [];
 
     /**
-     * 
+     * Registers a controller class with the router.
+     * This method extracts the route metadata from the controller class and registers it in the routing tree.
+     * It also handles the guards and middlewares associated with the controller.
+     * @param controllerClass - The controller class to register.
      */
     public registerController(controllerClass: Type<unknown>): Router {
         const controllerMeta = getControllerMetadata(controllerClass);
 
         const controllerGuards = getGuardForController(controllerClass.name);
         const controllerMiddlewares = getMiddlewaresForController(controllerClass.name);
-        
+
         if(!controllerMeta)
             throw new Error(`Missing @Controller decorator on ${controllerClass.name}`);
 
@@ -66,7 +80,7 @@ export class Router {
                 guards: [...guards],
                 middlewares: [...middlewares],
             };
-            
+
             this.routes.insert(fullPath + '/' + def.method, routeDef);
 
             const hasActionGuards = routeDef.guards.length > 0;
@@ -79,7 +93,7 @@ export class Router {
         }
 
         const hasCtrlGuards = controllerMeta.guards.length > 0;
-        
+
         const controllerGuardsInfo = hasCtrlGuards
             ? '<' + controllerMeta.guards.map(g => g.name).join('|') + '>'
             : '';
@@ -90,7 +104,10 @@ export class Router {
     }
 
     /**
-     * 
+     * Defines a middleware for the root of the application.
+     * This method allows you to register a middleware that will be applied to all requests
+     * to the application, regardless of the controller or action.
+     * @param middleware - The middleware class to register.
      */
     public defineRootMiddleware(middleware: Type<IMiddleware>): Router {
         Logger.debug(`Registering root middleware: ${middleware.name}`);
@@ -99,13 +116,16 @@ export class Router {
     }
 
     /**
-     * 
+     * Shuts down the message channel for a specific sender ID.
+     * This method closes the IPC channel for the specified sender ID and
+     * removes it from the messagePorts map.
+     * @param channelSenderId - The ID of the sender channel to shut down.
      */
     public async handle(request: Request): Promise<IResponse> {
         Logger.log(`> Received request: {${request.method} /${request.path}}`);
 
         const t0 = performance.now();
-        
+
         const response: IResponse = {
             requestId: request.id,
             status: 200,
@@ -156,7 +176,11 @@ export class Router {
     }
 
     /**
-     * 
+     * Finds the route definition for a given request.
+     * This method searches the routing tree for a matching route based on the request's path and method.
+     * If no matching route is found, it throws a NotFoundException.
+     * @param request - The Request object containing the method and path to search for.
+     * @returns The IRouteDefinition for the matched route.
      */
     private findRoute(request: Request): IRouteDefinition {
         const matchedRoutes = this.routes.search(request.path);
@@ -175,7 +199,14 @@ export class Router {
     }
 
     /**
-     * 
+     * Resolves the controller for a given route definition.
+     * This method creates an instance of the controller class and prepares the request parameters.
+     * It also runs the request pipeline, which includes executing middlewares and guards.
+     * @param request - The Request object containing the request data.
+     * @param response - The IResponse object to populate with the response data.
+     * @param routeDef - The IRouteDefinition for the matched route.
+     * @return A Promise that resolves when the controller action has been executed.
+     * @throws UnauthorizedException if the request is not authorized by the guards.
      */
     private async resolveController(request: Request, response: IResponse, routeDef: IRouteDefinition): Promise<void> {
         const controllerInstance = request.context.resolve(routeDef.controller);
@@ -186,7 +217,15 @@ export class Router {
     }
 
     /**
-     * 
+     * Runs the request pipeline for a given request.
+     * This method executes the middlewares and guards associated with the route,
+     * and finally calls the controller action.
+     * @param request - The Request object containing the request data.
+     * @param response - The IResponse object to populate with the response data.
+     * @param routeDef - The IRouteDefinition for the matched route.
+     * @param controllerInstance - The instance of the controller class.
+     * @return A Promise that resolves when the request pipeline has been executed.
+     * @throws ResponseException if the response status is not successful.
      */
     private async runRequestPipeline(request: Request, response: IResponse, routeDef: IRouteDefinition, controllerInstance: any): Promise<void> {
         const middlewares = [...new Set([...this.rootMiddlewares, ...routeDef.middlewares])];
@@ -199,7 +238,7 @@ export class Router {
         const dispatch = async (i: number): Promise<void> => {
             if(i <= index)
                 throw new Error("next() called multiple times");
-            
+
             index = i;
 
             // middlewares
@@ -213,7 +252,7 @@ export class Router {
 
                 return;
             }
-            
+
             // guards
             if(i <= guardsMaxIndex) {
                 const guardIndex = i - middlewares.length;
@@ -232,7 +271,14 @@ export class Router {
     }
 
     /**
-     * 
+     * Runs a middleware function in the request pipeline.
+     * This method creates an instance of the middleware and invokes its `invoke` method,
+     * passing the request, response, and next function.
+     * @param request - The Request object containing the request data.
+     * @param response - The IResponse object to populate with the response data.
+     * @param next - The NextFunction to call to continue the middleware chain.
+     * @param middlewareType - The type of the middleware to run.
+     * @return A Promise that resolves when the middleware has been executed.
      */
     private async runMiddleware(request: Request, response: IResponse, next: NextFunction, middlewareType: Type<IMiddleware>): Promise<void> {
         const middleware = request.context.resolve(middlewareType);
@@ -240,7 +286,13 @@ export class Router {
     }
 
     /**
-     * 
+     * Runs a guard to check if the request is authorized.
+     * This method creates an instance of the guard and calls its `canActivate` method.
+     * If the guard returns false, it throws an UnauthorizedException.
+     * @param request - The Request object containing the request data.
+     * @param guardType - The type of the guard to run.
+     * @return A Promise that resolves if the guard allows the request, or throws an UnauthorizedException if not.
+     * @throws UnauthorizedException if the guard denies access to the request.
      */
     private async runGuard(request: Request, guardType: Type<IGuard>): Promise<void> {
         const guard = request.context.resolve(guardType);
@@ -251,19 +303,24 @@ export class Router {
     }
 
     /**
-     * 
+     * Extracts parameters from the actual request path based on the template path.
+     * This method splits the actual path and the template path into segments,
+     * then maps the segments to parameters based on the template.
+     * @param actual - The actual request path.
+     * @param template - The template path to extract parameters from.
+     * @returns An object containing the extracted parameters.
      */
     private extractParams(actual: string, template: string): Record<string, string> {
         const aParts = actual.split('/');
         const tParts = template.split('/');
         const params: Record<string, string> = {};
-        
+
         tParts.forEach((part, i) => {
             if(part.startsWith(':')) {
                 params[part.slice(1)] = aParts[i] ?? '';
             }
         });
-        
+
         return params;
     }
 }

package/src/utils/logger.ts

@@ -4,12 +4,27 @@
  * @author NoxFly
  */
 
+/**
+ * Logger is a utility class for logging messages to the console.
+ */
+export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+
+/**
+ * Returns a formatted timestamp for logging.
+ */
 function getPrettyTimestamp(): string {
     const now = new Date();
     return `${now.getDate().toString().padStart(2, '0')}/${(now.getMonth() + 1).toString().padStart(2, '0')}/${now.getFullYear()}`
         + ` ${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}`;
 }
 
+/**
+ * Generates a log prefix for the console output.
+ * @param callee - The name of the function or class that is logging the message.
+ * @param messageType - The type of message being logged (e.g., 'log', 'info', 'warn', 'error', 'debug').
+ * @param color - The color to use for the log message.
+ * @returns A formatted string that includes the timestamp, process ID, message type, and callee name.
+ */
 function getLogPrefix(callee: string, messageType: string, color: string): string {
     const timestamp = getPrettyTimestamp();
 
@@ -21,9 +36,16 @@ function getLogPrefix(callee: string, messageType: string, color: string): strin
         + `${Logger.colors.yellow}[${callee}]${Logger.colors.initial}`;
 }
 
+/**
+ * Formats an object into a string representation for logging.
+ * It converts the object to JSON and adds indentation for readability.
+ * @param prefix - The prefix to use for the formatted object.
+ * @param arg - The object to format.
+ * @returns A formatted string representation of the object, with each line prefixed by the specified prefix.
+ */
 function formatObject(prefix: string, arg: object): string {
     const json = JSON.stringify(arg, null, 2);
-                
+
     const prefixedJson = json
         .split('\n')
         .map((line, idx) => idx === 0 ? `${Logger.colors.darkGrey}${line}` : `${prefix} ${Logger.colors.grey}${line}`)
@@ -32,6 +54,15 @@ function formatObject(prefix: string, arg: object): string {
     return prefixedJson;
 }
 
+/**
+ * Formats the arguments for logging.
+ * It colors strings and formats objects with indentation.
+ * This function is used to prepare the arguments for console output.
+ * @param prefix - The prefix to use for the formatted arguments.
+ * @param args - The arguments to format.
+ * @param color - The color to use for the formatted arguments.
+ * @returns An array of formatted arguments, where strings are colored and objects are formatted with indentation.
+ */
 function formattedArgs(prefix: string, args: any[], color: string): any[] {
     return args.map(arg => {
         if(typeof arg === 'string') {
@@ -46,13 +77,29 @@ function formattedArgs(prefix: string, args: any[], color: string): any[] {
     });
 }
 
+/**
+ * Gets the name of the caller function or class from the stack trace.
+ * This function is used to determine the context of the log message.
+ * @returns The name of the caller function or class.
+ */
 function getCallee(): string {
     const stack = new Error().stack?.split('\n') ?? [];
     const caller = stack[3]?.trim().match(/at (.+?)(?:\..+)? .+$/)?.[1]?.replace('Object', '') || "App";
     return caller;
 }
 
-export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+/**
+ * Checks if the current log level allows logging the specified level.
+ * This function compares the current log level with the specified level to determine if logging should occur.
+ * @param level - The log level to check.
+ * @returns A boolean indicating whether the log level is enabled.
+ */
+function canLog(level: LogLevel): boolean {
+    return logLevelRank[level] >= logLevelRank[logLevel];
+}
+
+
+let logLevel: LogLevel = 'log';
 
 const logLevelRank: Record<LogLevel, number> = {
     debug: 0,
@@ -62,39 +109,24 @@ const logLevelRank: Record<LogLevel, number> = {
     error: 4,
 };
 
-function canLog(level: LogLevel): boolean {
-    return logLevelRank[level] >= logLevelRank[logLevel];
-}
-
-let logLevel: LogLevel = 'log';
-
 export namespace Logger {
-    
+
+    /**
+     * Sets the log level for the logger.
+     * This function allows you to change the log level dynamically at runtime.
+     * This won't affect the startup logs.
+     * @param level Sets the log level for the logger.
+     */
     export function setLogLevel(level: LogLevel): void {
         logLevel = level;
     }
 
-    export const colors = {
-        black: '\x1b[0;30m',
-        grey: '\x1b[0;37m',
-        red: '\x1b[0;31m',
-        green: '\x1b[0;32m',
-        brown: '\x1b[0;33m',
-        blue: '\x1b[0;34m',
-        purple: '\x1b[0;35m',
-        
-        darkGrey: '\x1b[1;30m',
-        lightRed: '\x1b[1;31m',
-        lightGreen: '\x1b[1;32m',
-        yellow: '\x1b[1;33m',
-        lightBlue: '\x1b[1;34m',
-        magenta: '\x1b[1;35m',
-        cyan: '\x1b[1;36m',
-        white: '\x1b[1;37m',
-
-        initial: '\x1b[0m'
-    };
-
+    /**
+     * Logs a message to the console with log level LOG.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
     export function log(...args: any[]): void {
         if(!canLog('log'))
             return;
@@ -104,6 +136,12 @@ export namespace Logger {
         console.log(prefix, ...formattedArgs(prefix, args, colors.green));
     }
 
+    /**
+     * Logs a message to the console with log level INFO.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
     export function info(...args: any[]): void {
         if(!canLog('info'))
             return;
@@ -113,6 +151,12 @@ export namespace Logger {
         console.info(prefix, ...formattedArgs(prefix, args, colors.blue));
     }
 
+    /**
+     * Logs a message to the console with log level WARN.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
     export function warn(...args: any[]): void {
         if(!canLog('warn'))
             return;
@@ -122,6 +166,12 @@ export namespace Logger {
         console.warn(prefix, ...formattedArgs(prefix, args, colors.brown));
     }
 
+    /**
+     * Logs a message to the console with log level ERROR.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
     export function error(...args: any[]): void {
         if(!canLog('error'))
             return;
@@ -131,6 +181,12 @@ export namespace Logger {
         console.error(prefix, ...formattedArgs(prefix, args, colors.red));
     }
 
+    /**
+     * Logs a message to the console with log level DEBUG.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
     export function debug(...args: any[]): void {
         if(!canLog('debug'))
             return;
@@ -139,4 +195,26 @@ export namespace Logger {
         const prefix = getLogPrefix(callee, "debug", colors.purple);
         console.debug(prefix, ...formattedArgs(prefix, args, colors.purple));
     }
-}
+
+
+    export const colors = {
+        black: '\x1b[0;30m',
+        grey: '\x1b[0;37m',
+        red: '\x1b[0;31m',
+        green: '\x1b[0;32m',
+        brown: '\x1b[0;33m',
+        blue: '\x1b[0;34m',
+        purple: '\x1b[0;35m',
+
+        darkGrey: '\x1b[1;30m',
+        lightRed: '\x1b[1;31m',
+        lightGreen: '\x1b[1;32m',
+        yellow: '\x1b[1;33m',
+        lightBlue: '\x1b[1;34m',
+        magenta: '\x1b[1;35m',
+        cyan: '\x1b[1;36m',
+        white: '\x1b[1;37m',
+
+        initial: '\x1b[0m'
+    };
+}

package/src/utils/radix-tree.ts

@@ -4,13 +4,23 @@
  * @author NoxFly
  */
 
+/**
+ *
+ */
 type Params = Record<string, string>;
 
+/**
+ * Represents a search result in the Radix Tree.
+ */
 interface ISearchResult<T> {
     node: RadixNode<T>;
     params: Params;
 }
 
+/**
+ * Represents a node in the Radix Tree.
+ * The represents a path segment
+ */
 class RadixNode<T> {
     public segment: string;
     public children: RadixNode<T>[] = [];
@@ -18,15 +28,25 @@ class RadixNode<T> {
     public isParam: boolean;
     public paramName?: string;
 
+    /**
+     * Creates a new RadixNode.
+     * @param segment - The segment of the path this node represents.
+     */
     constructor(segment: string) {
         this.segment = segment;
         this.isParam = segment.startsWith(":");
-        
+
         if(this.isParam) {
             this.paramName = segment.slice(1);
         }
     }
 
+    /**
+     * Matches a child node against a given segment.
+     * This method checks if the segment matches any of the children nodes.
+     * @param segment - The segment to match against the children of this node.
+     * @returns A child node that matches the segment, or undefined if no match is found.
+     */
     public matchChild(segment: string): RadixNode<T> | undefined {
         for(const child of this.children) {
             if(child.isParam || segment.startsWith(child.segment))
@@ -36,23 +56,50 @@ class RadixNode<T> {
         return undefined;
     }
 
+    /**
+     * Finds a child node that matches the segment exactly.
+     * This method checks if there is a child node that matches the segment exactly.
+     * @param segment - The segment to find an exact match for among the children of this node.
+     * @returns A child node that matches the segment exactly, or undefined if no match is found.
+     */
     public findExactChild(segment: string): RadixNode<T> | undefined {
         return this.children.find(c => c.segment === segment);
     }
 
+    /**
+     * Adds a child node to this node's children.
+     * This method adds a new child node to the list of children for this node.
+     * @param node - The child node to add to this node's children.
+     */
     public addChild(node: RadixNode<T>): void {
         this.children.push(node);
     }
 }
 
+/**
+ *
+ */
 export class RadixTree<T> {
     private readonly root = new RadixNode<T>("");
 
+    /**
+     * Inserts a path and its associated value into the Radix Tree.
+     * This method normalizes the path and inserts it into the tree, associating it with
+     * @param path - The path to insert into the tree.
+     * @param value - The value to associate with the path.
+     */
     public insert(path: string, value: T): void {
         const segments = this.normalize(path);
         this.insertRecursive(this.root, segments, value);
     }
 
+    /**
+     * Recursively inserts a path into the Radix Tree.
+     * This method traverses the tree and inserts the segments of the path, creating new nodes
+     * @param node - The node to start inserting from.
+     * @param segments - The segments of the path to insert.
+     * @param value - The value to associate with the path.
+     */
     private insertRecursive(node: RadixNode<T>, segments: string[], value: T): void {
         if(segments.length === 0) {
             node.value = value;
@@ -74,11 +121,25 @@ export class RadixTree<T> {
         this.insertRecursive(child, segments.slice(1), value);
     }
 
+    /**
+     * Searches for a path in the Radix Tree.
+     * This method normalizes the path and searches for it in the tree, returning the node
+     * @param path - The path to search for in the Radix Tree.
+     * @returns An ISearchResult containing the node and parameters if a match is found, otherwise undefined.
+     */
     public search(path: string): ISearchResult<T> | undefined {
         const segments = this.normalize(path);
         return this.searchRecursive(this.root, segments, {});
     }
 
+    /**
+     * Recursively searches for a path in the Radix Tree.
+     * This method traverses the tree and searches for the segments of the path, collecting parameters
+     * @param node - The node to start searching from.
+     * @param segments - The segments of the path to search for.
+     * @param params - The parameters collected during the search.
+     * @returns An ISearchResult containing the node and parameters if a match is found, otherwise undefined.
+     */
     private searchRecursive(node: RadixNode<T>, segments: string[], params: Params): ISearchResult<T> | undefined {
         if(segments.length === 0) {
             if(node.value !== undefined) {
@@ -96,7 +157,7 @@ export class RadixTree<T> {
         for(const child of node.children) {
             if(child.isParam) {
                 const paramName = child.paramName!;
-                
+
                 const childParams: Params = {
                     ...params,
                     [paramName]: segment ?? "",
@@ -110,7 +171,7 @@ export class RadixTree<T> {
                 }
 
                 const result = this.searchRecursive(child, rest, childParams);
-                
+
                 if(result)
                     return result;
             }
@@ -132,6 +193,12 @@ export class RadixTree<T> {
         return undefined;
     }
 
+    /**
+     * Normalizes a path into an array of segments.
+     * This method removes leading and trailing slashes, splits the path by slashes, and
+     * @param path - The path to normalize.
+     * @returns An array of normalized path segments.
+     */
     private normalize(path: string): string[] {
         const segments = path
             .replace(/^\/+|\/+$/g, "")
@@ -139,5 +206,5 @@ export class RadixTree<T> {
             .filter(Boolean);
 
         return ['', ...segments];
-    } 
+    }
 }

package/src/utils/types.ts

@@ -4,13 +4,18 @@
  * @author NoxFly
  */
 
-/* eslint-disable @typescript-eslint/no-unsafe-function-type */
-
 
+/**
+ * Represents a generic type that can be either a class or a function.
+ * This is used to define types that can be instantiated or called.
+ */
 declare const Type: FunctionConstructor;
 export interface Type<T> extends Function {
     // eslint-disable-next-line @typescript-eslint/prefer-function-type
     new (...args: any[]): T;
 }
 
-export type MaybeAsync<T> = T | Promise<T>;
+/**
+ * Represents a generic type that can be either a value or a promise resolving to that value.
+ */
+export type MaybeAsync<T> = T | Promise<T>;

package/tsup.config.ts

@@ -13,6 +13,7 @@ export default defineConfig({
         noxus: "src/index.ts"
     },
     keepNames: true,
+    minifyIdentifiers: false,
     name: "noxus",
     format: ["cjs", "esm"],
     dts: true,
@@ -28,4 +29,4 @@ export default defineConfig({
     banner: {
         js: copyrights,
     }
-});
+});