@noxfly/noxus 1.1.1 → 1.1.4

package/dist/noxus.mjs

@@ -225,8 +225,10 @@ var _AppInjector = class _AppInjector {
     this.name = name;
   }
   /**
-   * Utilisé généralement pour créer un scope d'injection de dépendances
-   * au niveau "scope" (donc durée de vie d'une requête)
+   * Typically used to create a dependency injection scope
+   * at the "scope" level (i.e., per-request lifetime).
+   *
+   * SHOULD NOT BE USED by anything else than the framework itself.
    */
   createScope() {
     const scope = new _AppInjector();
@@ -235,8 +237,8 @@ var _AppInjector = class _AppInjector {
     return scope;
   }
   /**
-   * Appelé lorsqu'on souhaite résoudre une dépendance,
-   * c'est-à-dire récupérer l'instance d'une classe donnée.
+   * Called when resolving a dependency,
+   * i.e., retrieving the instance of a given class.
    */
   resolve(target) {
     const binding = this.bindings.get(target);
@@ -263,7 +265,7 @@ Did you forget to use @Injectable() decorator ?`);
     }
   }
   /**
-   * 
+   *
    */
   instantiate(target) {
     const paramTypes = Reflect.getMetadata("design:paramtypes", target) || [];
@@ -273,11 +275,11 @@ Did you forget to use @Injectable() decorator ?`);
 };
 __name(_AppInjector, "AppInjector");
 var AppInjector = _AppInjector;
-var RootInjector = new AppInjector("root");
 function inject(t) {
   return RootInjector.resolve(t);
 }
 __name(inject, "inject");
+var RootInjector = new AppInjector("root");
 
 // src/router.ts
 import "reflect-metadata";
@@ -317,6 +319,11 @@ function getCallee() {
   return caller;
 }
 __name(getCallee, "getCallee");
+function canLog(level) {
+  return logLevelRank[level] >= logLevelRank[logLevel];
+}
+__name(canLog, "canLog");
+var logLevel = "log";
 var logLevelRank = {
   debug: 0,
   log: 1,
@@ -324,35 +331,12 @@ var logLevelRank = {
   warn: 3,
   error: 4
 };
-function canLog(level) {
-  return logLevelRank[level] >= logLevelRank[logLevel];
-}
-__name(canLog, "canLog");
-var logLevel = "log";
 (function(Logger2) {
   function setLogLevel(level) {
     logLevel = level;
   }
   __name(setLogLevel, "setLogLevel");
   Logger2.setLogLevel = setLogLevel;
-  Logger2.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"
-  };
   function log(...args) {
     if (!canLog("log")) return;
     const callee = getCallee();
@@ -393,11 +377,28 @@ var logLevel = "log";
   }
   __name(debug, "debug");
   Logger2.debug = debug;
+  Logger2.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"
+  };
 })(Logger || (Logger = {}));
 var Logger;
 
 // src/decorators/guards.decorator.ts
-var authorizations = /* @__PURE__ */ new Map();
 function Authorize(...guardClasses) {
   return (target, propertyKey) => {
     let key;
@@ -427,6 +428,7 @@ function getGuardForControllerAction(controllerName, actionName) {
   return authorizations.get(key) ?? [];
 }
 __name(getGuardForControllerAction, "getGuardForControllerAction");
+var authorizations = /* @__PURE__ */ new Map();
 
 // src/decorators/method.decorator.ts
 function createRouteDecorator(verb) {
@@ -445,16 +447,16 @@ function createRouteDecorator(verb) {
   };
 }
 __name(createRouteDecorator, "createRouteDecorator");
+function getRouteMetadata(target) {
+  return Reflect.getMetadata(ROUTE_METADATA_KEY, target) || [];
+}
+__name(getRouteMetadata, "getRouteMetadata");
 var Get = createRouteDecorator("GET");
 var Post = createRouteDecorator("POST");
 var Put = createRouteDecorator("PUT");
 var Patch = createRouteDecorator("PATCH");
 var Delete = createRouteDecorator("DELETE");
 var ROUTE_METADATA_KEY = Symbol("ROUTE_METADATA_KEY");
-function getRouteMetadata(target) {
-  return Reflect.getMetadata(ROUTE_METADATA_KEY, target) || [];
-}
-__name(getRouteMetadata, "getRouteMetadata");
 
 // src/decorators/module.decorator.ts
 function Module(metadata) {
@@ -492,19 +494,18 @@ function Module(metadata) {
   };
 }
 __name(Module, "Module");
-var MODULE_METADATA_KEY = Symbol("MODULE_METADATA_KEY");
 function getModuleMetadata(target) {
   return Reflect.getMetadata(MODULE_METADATA_KEY, target);
 }
 __name(getModuleMetadata, "getModuleMetadata");
+var MODULE_METADATA_KEY = Symbol("MODULE_METADATA_KEY");
 
 // src/DI/injector-explorer.ts
 var _InjectorExplorer = class _InjectorExplorer {
   /**
-   * Enregistre la classe comme étant injectable.
-   * Lorsqu'une classe sera instanciée, si elle a des dépendances, et que celles-ci
-   * figurent dans la liste grâce à cette méthode, elles seront injectées dans le
-   * constructeur de la classe.
+   * Registers the class as injectable.
+   * When a class is instantiated, if it has dependencies and those dependencies
+   * are listed using this method, they will be injected into the class constructor.
    */
   static register(target, lifetime) {
     Logger.debug(`Registering ${target.name} as ${lifetime}`);
@@ -551,11 +552,11 @@ function Injectable(lifetime = "scope") {
   };
 }
 __name(Injectable, "Injectable");
-var INJECTABLE_METADATA_KEY = Symbol("INJECTABLE_METADATA_KEY");
 function getInjectableMetadata(target) {
   return Reflect.getMetadata(INJECTABLE_METADATA_KEY, target);
 }
 __name(getInjectableMetadata, "getInjectableMetadata");
+var INJECTABLE_METADATA_KEY = Symbol("INJECTABLE_METADATA_KEY");
 
 // src/decorators/controller.decorator.ts
 function Controller(path) {
@@ -569,14 +570,13 @@ function Controller(path) {
   };
 }
 __name(Controller, "Controller");
-var CONTROLLER_METADATA_KEY = Symbol("CONTROLLER_METADATA_KEY");
 function getControllerMetadata(target) {
   return Reflect.getMetadata(CONTROLLER_METADATA_KEY, target);
 }
 __name(getControllerMetadata, "getControllerMetadata");
+var CONTROLLER_METADATA_KEY = Symbol("CONTROLLER_METADATA_KEY");
 
 // src/decorators/middleware.decorator.ts
-var middlewares = /* @__PURE__ */ new Map();
 function UseMiddlewares(mdlw) {
   return (target, propertyKey) => {
     let key;
@@ -606,10 +606,15 @@ function getMiddlewaresForControllerAction(controllerName, actionName) {
   return middlewares.get(key) ?? [];
 }
 __name(getMiddlewaresForControllerAction, "getMiddlewaresForControllerAction");
+var middlewares = /* @__PURE__ */ new Map();
 
 // src/utils/radix-tree.ts
 var _a;
 var RadixNode = (_a = class {
+  /**
+   * Creates a new RadixNode.
+   * @param segment - The segment of the path this node represents.
+   */
   constructor(segment) {
     __publicField(this, "segment");
     __publicField(this, "children", []);
@@ -622,15 +627,32 @@ var RadixNode = (_a = class {
       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.
+   */
   matchChild(segment) {
     for (const child of this.children) {
       if (child.isParam || segment.startsWith(child.segment)) return child;
     }
     return void 0;
   }
+  /**
+   * 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.
+   */
   findExactChild(segment) {
     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.
+   */
   addChild(node) {
     this.children.push(node);
   }
@@ -639,10 +661,23 @@ var _RadixTree = class _RadixTree {
   constructor() {
     __publicField(this, "root", new RadixNode(""));
   }
+  /**
+   * 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.
+   */
   insert(path, value) {
     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.
+   */
   insertRecursive(node, segments, value) {
     if (segments.length === 0) {
       node.value = value;
@@ -656,10 +691,24 @@ var _RadixTree = class _RadixTree {
     }
     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.
+   */
   search(path) {
     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.
+   */
   searchRecursive(node, segments, params) {
     if (segments.length === 0) {
       if (node.value !== void 0) {
@@ -699,6 +748,12 @@ var _RadixTree = class _RadixTree {
     }
     return void 0;
   }
+  /**
+   * 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.
+   */
   normalize(path) {
     const segments = path.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
     return [
@@ -724,7 +779,10 @@ var _Router = class _Router {
     __publicField(this, "rootMiddlewares", []);
   }
   /**
-   * 
+   * 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.
    */
   registerController(controllerClass) {
     const controllerMeta = getControllerMetadata(controllerClass);
@@ -767,7 +825,10 @@ var _Router = class _Router {
     return this;
   }
   /**
-   * 
+   * 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.
    */
   defineRootMiddleware(middleware) {
     Logger.debug(`Registering root middleware: ${middleware.name}`);
@@ -775,7 +836,10 @@ var _Router = class _Router {
     return this;
   }
   /**
-   * 
+   * 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.
    */
   async handle(request) {
     Logger.log(`> Received request: {${request.method} /${request.path}}`);
@@ -816,7 +880,11 @@ var _Router = 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.
    */
   findRoute(request) {
     const matchedRoutes = this.routes.search(request.path);
@@ -830,7 +898,14 @@ var _Router = class _Router {
     return routeDef.value;
   }
   /**
-   * 
+   * 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.
    */
   async resolveController(request, response, routeDef) {
     const controllerInstance = request.context.resolve(routeDef.controller);
@@ -838,7 +913,15 @@ var _Router = class _Router {
     await this.runRequestPipeline(request, response, routeDef, controllerInstance);
   }
   /**
-   * 
+   * 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.
    */
   async runRequestPipeline(request, response, routeDef, controllerInstance) {
     const middlewares2 = [
@@ -874,14 +957,27 @@ var _Router = class _Router {
     await dispatch(0);
   }
   /**
-   * 
+   * 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.
    */
   async runMiddleware(request, response, next, middlewareType) {
     const middleware = request.context.resolve(middlewareType);
     await middleware.invoke(request, response, next);
   }
   /**
-   * 
+   * 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.
    */
   async runGuard(request, guardType) {
     const guard = request.context.resolve(guardType);
@@ -889,7 +985,12 @@ var _Router = class _Router {
     if (!allowed) throw new UnauthorizedException(`Unauthorized for ${request.method} ${request.path}`);
   }
   /**
-   * 
+   * 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.
    */
   extractParams(actual, template) {
     const aParts = actual.split("/");
@@ -954,7 +1055,9 @@ var _NoxApp = class _NoxApp {
     this.router = router;
   }
   /**
-   *
+   * Initializes the NoxApp instance.
+   * This method sets up the IPC communication, registers event listeners,
+   * and prepares the application for use.
    */
   async init() {
     ipcMain.on("gimme-my-port", this.giveTheRendererAPort.bind(this));
@@ -964,7 +1067,10 @@ var _NoxApp = class _NoxApp {
     return this;
   }
   /**
-   *
+   * Handles the request from the renderer process.
+   * This method creates a Request object from the IPC event data,
+   * processes it through the Router, and sends the response back
+   * to the renderer process using the MessageChannel.
    */
   giveTheRendererAPort(event) {
     const senderId = event.sender.id;
@@ -1014,7 +1120,14 @@ var _NoxApp = class _NoxApp {
       this.app?.onActivated();
     }
   }
-  shutdownChannel(channelSenderId, remove = true) {
+  /**
+   * 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.
+   * @param remove - Whether to remove the channel from the messagePorts map.
+   */
+  shutdownChannel(channelSenderId) {
     const channel = this.messagePorts.get(channelSenderId);
     if (!channel) {
       Logger.warn(`No message channel found for sender ID: ${channelSenderId}`);
@@ -1026,11 +1139,12 @@ var _NoxApp = class _NoxApp {
     this.messagePorts.delete(channelSenderId);
   }
   /**
-   *
+   * Handles the application shutdown process.
+   * This method is called when all windows are closed, and it cleans up the message channels
    */
   async onAllWindowsClosed() {
     this.messagePorts.forEach((channel, senderId) => {
-      this.shutdownChannel(senderId, false);
+      this.shutdownChannel(senderId);
     });
     this.messagePorts.clear();
     this.app?.dispose();
@@ -1039,16 +1153,29 @@ var _NoxApp = class _NoxApp {
     }
   }
   // ---
+  /**
+   * Configures the NoxApp instance with the provided application class.
+   * This method allows you to set the application class that will handle lifecycle events.
+   * @param app - The application class to configure.
+   * @returns NoxApp instance for method chaining.
+   */
   configure(app3) {
     this.app = inject(app3);
     return this;
   }
+  /**
+   * Registers a middleware for the root of the application.
+   * This method allows you to define a middleware that will be applied to all requests
+   * @param middleware - The middleware class to register.
+   * @returns NoxApp instance for method chaining.
+   */
   use(middleware) {
     this.router.defineRootMiddleware(middleware);
     return this;
   }
   /**
    * Should be called after the bootstrapApplication function is called.
+   * @returns NoxApp instance for method chaining.
    */
   start() {
     this.app?.onReady();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noxfly/noxus",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "main": "dist/noxus.js",
   "types": "dist/noxus.d.ts",
   "scripts": {

package/src/DI/app-injector.ts

@@ -8,14 +8,32 @@ import 'reflect-metadata';
 import { InternalServerException } from 'src/exceptions';
 import { Type } from 'src/utils/types';
 
+/**
+ * Represents a lifetime of a binding in the dependency injection system.
+ * It can be one of the following:
+ * - 'singleton': The instance is created once and shared across the application.
+ * - 'scope': The instance is created once per scope (e.g., per request).
+ * - 'transient': A new instance is created every time it is requested.
+ */
 export type Lifetime = 'singleton' | 'scope' | 'transient';
 
+/**
+ * Represents a binding in the dependency injection system.
+ * It contains the lifetime of the binding, the implementation type, and optionally an instance.
+ */
 export interface IBinding {
     lifetime: Lifetime;
     implementation: Type<unknown>;
     instance?: InstanceType<Type<unknown>>;
 }
 
+/**
+ * AppInjector is the root dependency injection container.
+ * It is used to register and resolve dependencies in the application.
+ * It supports different lifetimes for dependencies:
+ * This should not be manually instantiated, outside of the framework.
+ * Use the `RootInjector` instance instead.
+ */
 export class AppInjector {
     public bindings = new Map<Type<unknown>, IBinding>();
     public singletons = new Map<Type<unknown>, InstanceType<Type<unknown>>>();
@@ -26,20 +44,22 @@ export class AppInjector {
     ) {}
 
     /**
-     * Utilisé généralement pour créer un scope d'injection de dépendances
-     * au niveau "scope" (donc durée de vie d'une requête)
+     * Typically used to create a dependency injection scope
+     * at the "scope" level (i.e., per-request lifetime).
+     *
+     * SHOULD NOT BE USED by anything else than the framework itself.
      */
     public createScope(): AppInjector {
         const scope = new AppInjector();
-        scope.bindings = this.bindings; // transmet les déclarations d'injectables
-        scope.singletons = this.singletons; // on passe les singletons du parent à l'enfant pour éviter de les recréer
-        // on ne garde pas les scoped du parent
+        scope.bindings = this.bindings; // pass injectable declarations
+        scope.singletons = this.singletons; // share parent's singletons to avoid recreating them
+        // do not keep parent's scoped instances
         return scope;
     }
 
     /**
-     * Appelé lorsqu'on souhaite résoudre une dépendance,
-     * c'est-à-dire récupérer l'instance d'une classe donnée.
+     * Called when resolving a dependency,
+     * i.e., retrieving the instance of a given class.
      */
     public resolve<T extends Type<unknown>>(target: T): InstanceType<T> {
         const binding = this.bindings.get(target);
@@ -77,7 +97,7 @@ export class AppInjector {
     }
 
     /**
-     * 
+     *
      */
     private instantiate<T extends Type<unknown>>(target: T): InstanceType<T> {
         const paramTypes = Reflect.getMetadata('design:paramtypes', target) || [];
@@ -86,8 +106,16 @@ export class AppInjector {
     }
 }
 
-export const RootInjector = new AppInjector('root');
-
+/**
+ * Injects a type from the dependency injection system.
+ * This function is used to retrieve an instance of a type that has been registered in the dependency injection system.
+ * It is typically used in the constructor of a class to inject dependencies.
+ * @param t - The type to inject.
+ * @returns An instance of the type.
+ * @throws If the type is not registered in the dependency injection system.
+ */
 export function inject<T>(t: Type<T>): T {
     return RootInjector.resolve(t);
 }
+
+export const RootInjector = new AppInjector('root');

package/src/DI/injector-explorer.ts

@@ -13,12 +13,14 @@ import { Router } from "src/router";
 import { Logger } from "src/utils/logger";
 import { Type } from "src/utils/types";
 
+/**
+ * InjectorExplorer is a utility class that explores the dependency injection system at the startup.
+ */
 export class InjectorExplorer {
     /**
-     * Enregistre la classe comme étant injectable.
-     * Lorsqu'une classe sera instanciée, si elle a des dépendances, et que celles-ci
-     * figurent dans la liste grâce à cette méthode, elles seront injectées dans le
-     * constructeur de la classe.
+     * Registers the class as injectable.
+     * When a class is instantiated, if it has dependencies and those dependencies
+     * are listed using this method, they will be injected into the class constructor.
      */
     public static register(target: Type<unknown>, lifetime: Lifetime): typeof RootInjector {
         Logger.debug(`Registering ${target.name} as ${lifetime}`);
@@ -40,7 +42,7 @@ export class InjectorExplorer {
         }
 
         const controllerMeta = getControllerMetadata(target);
-        
+
         if(controllerMeta) {
             const router = RootInjector.resolve(Router);
             router?.registerController(target);
@@ -48,7 +50,7 @@ export class InjectorExplorer {
         }
 
         const routeMeta = getRouteMetadata(target);
-        
+
         if(routeMeta) {
             return RootInjector;
         }
@@ -60,4 +62,4 @@ export class InjectorExplorer {
 
         return RootInjector;
     }
-}
+}