@noxfly/noxus 1.1.1 → 1.1.4

package/src/app.ts

@@ -13,12 +13,21 @@ import { Router } from "src/router";
 import { Logger } from "src/utils/logger";
 import { Type } from "src/utils/types";
 
+/**
+ * The application service should implement this interface, as
+ * the NoxApp class instance will use it to notify the given service
+ * about application lifecycle events.
+ */
 export interface IApp {
     dispose(): Promise<void>;
     onReady(): Promise<void>;
     onActivated(): Promise<void>;
 }
 
+/**
+ * NoxApp is the main application class that manages the application lifecycle,
+ * handles IPC communication, and integrates with the Router.
+ */
 @Injectable('singleton')
 export class NoxApp {
     private readonly messagePorts = new Map<number, Electron.MessageChannelMain>();
@@ -29,7 +38,9 @@ export class NoxApp {
     ) {}
 
     /**
-     *
+     * Initializes the NoxApp instance.
+     * This method sets up the IPC communication, registers event listeners,
+     * and prepares the application for use.
      */
     public async init(): Promise<NoxApp> {
         ipcMain.on('gimme-my-port', this.giveTheRendererAPort.bind(this));
@@ -43,7 +54,10 @@ export class NoxApp {
     }
 
     /**
-     *
+     * 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.
      */
     private giveTheRendererAPort(event: Electron.IpcMainInvokeEvent): void {
         const senderId = event.sender.id;
@@ -74,7 +88,6 @@ export class NoxApp {
             Logger.error(`No message channel found for sender ID: ${senderId}`);
             return;
         }
-
         try {
             const request = new Request(event, requestId, method, path, body);
             const response = await this.router.handle(request);
@@ -101,7 +114,14 @@ export class NoxApp {
         }
     }
 
-    private shutdownChannel(channelSenderId: number, remove: boolean = true): void {
+    /**
+     * 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.
+     */
+    private shutdownChannel(channelSenderId: number): void {
         const channel = this.messagePorts.get(channelSenderId);
 
         if(!channel) {
@@ -117,11 +137,12 @@ export class NoxApp {
     }
 
     /**
-     *
+     * Handles the application shutdown process.
+     * This method is called when all windows are closed, and it cleans up the message channels
      */
     private async onAllWindowsClosed(): Promise<void> {
         this.messagePorts.forEach((channel, senderId) => {
-            this.shutdownChannel(senderId, false);
+            this.shutdownChannel(senderId);
         });
 
         this.messagePorts.clear();
@@ -136,12 +157,23 @@ export 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.
+     */
     public configure(app: Type<IApp>): NoxApp {
         this.app = inject(app);
         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.
+     */
     public use(middleware: Type<IMiddleware>): NoxApp {
         this.router.defineRootMiddleware(middleware);
         return this;
@@ -149,6 +181,7 @@ export class NoxApp {
 
     /**
      * Should be called after the bootstrapApplication function is called.
+     * @returns NoxApp instance for method chaining.
      */
     public start(): NoxApp {
         this.app?.onReady();

package/src/bootstrap.ts

@@ -11,7 +11,12 @@ import { inject } from "src/DI/app-injector";
 import { Type } from "src/utils/types";
 
 /**
- * 
+ * Bootstraps the Noxus application.
+ * This function initializes the application by creating an instance of NoxApp,
+ * registering the root module, and starting the application.
+ * @param rootModule - The root module of the application, decorated with @Module.
+ * @return A promise that resolves to the NoxApp instance.
+ * @throws Error if the root module is not decorated with @Module, or if the electron process could not start.
  */
 export async function bootstrapApplication(rootModule: Type<any>): Promise<NoxApp> {
     if(!getModuleMetadata(rootModule)) {

package/src/decorators/controller.decorator.ts

@@ -8,11 +8,20 @@ import { getGuardForController, IGuard } from "src/decorators/guards.decorator";
 import { Injectable } from "src/decorators/injectable.decorator";
 import { Type } from "src/utils/types";
 
+/**
+ * The configuration that waits a controller's decorator.
+ */
 export interface IControllerMetadata {
     path: string;
     guards: Type<IGuard>[];
 }
 
+/**
+ * Controller decorator is used to define a controller in the application.
+ * It is a kind of node in the routing tree, that can contains routes and middlewares.
+ *
+ * @param path - The path for the controller.
+ */
 export function Controller(path: string): ClassDecorator {
     return (target) => {
         const data: IControllerMetadata = {
@@ -25,8 +34,14 @@ export function Controller(path: string): ClassDecorator {
     };
 }
 
-export const CONTROLLER_METADATA_KEY = Symbol('CONTROLLER_METADATA_KEY');
-
+/**
+ * Gets the controller metadata for a given target class.
+ * This metadata includes the path and guards defined by the @Controller decorator.
+ * @param target - The target class to get the controller metadata from.
+ * @returns The controller metadata if it exists, otherwise undefined.
+ */
 export function getControllerMetadata(target: Type<unknown>): IControllerMetadata | undefined {
     return Reflect.getMetadata(CONTROLLER_METADATA_KEY, target);
-}
+}
+
+export const CONTROLLER_METADATA_KEY = Symbol('CONTROLLER_METADATA_KEY');

package/src/decorators/guards.decorator.ts

@@ -8,15 +8,23 @@ import { Request } from 'src/request';
 import { Logger } from 'src/utils/logger';
 import { MaybeAsync, Type } from 'src/utils/types';
 
+/**
+ * IGuard interface defines a guard that can be used to protect routes.
+ * It has a `canActivate` method that takes a request and returns a MaybeAsync boolean.
+ * The `canActivate` method can return either a value or a Promise.
+ * Use it on a class that should be registered as a guard in the application.
+ * Guards can be used to protect routes or controller actions.
+ * For example, you can use guards to check if the user is authenticated or has the right permissions.
+ * You can use the `Authorize` decorator to register guards for a controller or a controller action.
+ * @see Authorize
+ */
 export interface IGuard {
     canActivate(request: Request): MaybeAsync<boolean>;
 }
 
-const authorizations = new Map<string, Type<IGuard>[]>();
-
 /**
- * Peut être utilisé pour protéger les routes d'un contrôleur.
- * Peut être utilisé sur une classe controleur, ou sur une méthode de contrôleur.
+ * Can be used to protect the routes of a controller.
+ * Can be used on a controller class or on a controller method.
  */
 export function Authorize(...guardClasses: Type<IGuard>[]): MethodDecorator & ClassDecorator {
     return (target: Function | object, propertyKey?: string | symbol) => {
@@ -44,13 +52,25 @@ export function Authorize(...guardClasses: Type<IGuard>[]): MethodDecorator & Cl
     };
 }
 
-
+/**
+ * Gets the guards for a controller or a controller action.
+ * @param controllerName The name of the controller to get the guards for.
+ * @returns An array of guards for the controller.
+ */
 export function getGuardForController(controllerName: string): Type<IGuard>[] {
     const key = `${controllerName}`;
     return authorizations.get(key) ?? [];
 }
 
+/**
+ * Gets the guards for a controller action.
+ * @param controllerName The name of the controller to get the guards for.
+ * @param actionName The name of the action to get the guards for.
+ * @returns An array of guards for the controller action.
+ */
 export function getGuardForControllerAction(controllerName: string, actionName: string): Type<IGuard>[] {
     const key = `${controllerName}.${actionName}`;
     return authorizations.get(key) ?? [];
 }
+
+const authorizations = new Map<string, Type<IGuard>[]>();

package/src/decorators/injectable.decorator.ts

@@ -8,6 +8,13 @@ import { Lifetime } from "src/DI/app-injector";
 import { InjectorExplorer } from "src/DI/injector-explorer";
 import { Type } from "src/utils/types";
 
+/**
+ * The Injectable decorator marks a class as injectable.
+ * It allows the class to be registered in the dependency injection system.
+ * A class decorated with @Injectable can be injected into other classes
+ * either from the constructor of the class that needs it of from the `inject` function.
+ * @param lifetime - The lifetime of the injectable. Can be 'singleton', 'scope', or 'transient'.
+ */
 export function Injectable(lifetime: Lifetime = 'scope'): ClassDecorator {
     return (target) => {
         if(typeof target !== 'function' || !target.prototype) {
@@ -19,8 +26,14 @@ export function Injectable(lifetime: Lifetime = 'scope'): ClassDecorator {
     };
 }
 
-export const INJECTABLE_METADATA_KEY = Symbol('INJECTABLE_METADATA_KEY');
-
+/**
+ * Gets the injectable metadata for a given target class.
+ * This metadata includes the lifetime of the injectable defined by the @Injectable decorator.
+ * @param target - The target class to get the injectable metadata from.
+ * @returns The lifetime of the injectable if it exists, otherwise undefined.
+ */
 export function getInjectableMetadata(target: Type<unknown>): Lifetime | undefined {
     return Reflect.getMetadata(INJECTABLE_METADATA_KEY, target);
-}
+}
+
+export const INJECTABLE_METADATA_KEY = Symbol('INJECTABLE_METADATA_KEY');

package/src/decorators/method.decorator.ts

@@ -7,6 +7,30 @@
 import { getGuardForControllerAction, IGuard } from "src/decorators/guards.decorator";
 import { Type } from "src/utils/types";
 
+/**
+ * IRouteMetadata interface defines the metadata for a route.
+ * It includes the HTTP method, path, handler name, and guards associated with the route.
+ * This metadata is used to register the route in the application.
+ * This is the configuration that waits a route's decorator.
+ */
+export interface IRouteMetadata {
+    method: HttpMethod;
+    path: string;
+    handler: string;
+    guards: Type<IGuard>[];
+}
+
+/**
+ * The different HTTP methods that can be used in the application.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * The configuration that waits a route's decorator.
+ * It contains the HTTP method, path, handler, and guards for the route.
+ * @param verb The HTTP method for the route.
+ * @returns A method decorator that registers the route with the specified HTTP method.
+ */
 function createRouteDecorator(verb: HttpMethod): (path: string) => MethodDecorator {
     return (path: string): MethodDecorator => {
         return (target, propertyKey) => {
@@ -26,23 +50,53 @@ function createRouteDecorator(verb: HttpMethod): (path: string) => MethodDecorat
     };
 }
 
-export interface IRouteMetadata {
-    method: HttpMethod;
-    path: string;
-    handler: string;
-    guards: Type<IGuard>[];
+/**
+ * Gets the route metadata for a given target class.
+ * This metadata includes the HTTP method, path, handler, and guards defined by the route decorators.
+ * @see Get
+ * @see Post
+ * @see Put
+ * @see Patch
+ * @see Delete
+ * @param target The target class to get the route metadata from.
+ * @returns An array of route metadata if it exists, otherwise an empty array.
+ */
+export function getRouteMetadata(target: Type<unknown>): IRouteMetadata[] {
+    return Reflect.getMetadata(ROUTE_METADATA_KEY, target) || [];
 }
 
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-
+/**
+ * Route decorator that defines a leaf in the routing tree, attaching it to a controller method
+ * that will be called when the route is matched.
+ * This route will have to be called with the GET method.
+ */
 export const Get = createRouteDecorator('GET');
+
+/**
+ * Route decorator that defines a leaf in the routing tree, attaching it to a controller method
+ * that will be called when the route is matched.
+ * This route will have to be called with the POST method.
+ */
 export const Post = createRouteDecorator('POST');
+
+/**
+ * Route decorator that defines a leaf in the routing tree, attaching it to a controller method
+ * that will be called when the route is matched.
+ * This route will have to be called with the PUT method.
+ */
 export const Put = createRouteDecorator('PUT');
+/**
+ * Route decorator that defines a leaf in the routing tree, attaching it to a controller method
+ * that will be called when the route is matched.
+ * This route will have to be called with the PATCH method.
+ */
 export const Patch = createRouteDecorator('PATCH');
+
+/**
+ * Route decorator that defines a leaf in the routing tree, attaching it to a controller method
+ * that will be called when the route is matched.
+ * This route will have to be called with the DELETE method.
+ */
 export const Delete = createRouteDecorator('DELETE');
 
 export const ROUTE_METADATA_KEY = Symbol('ROUTE_METADATA_KEY');
-
-export function getRouteMetadata(target: Type<unknown>): IRouteMetadata[] {
-    return Reflect.getMetadata(ROUTE_METADATA_KEY, target) || [];
-}

package/src/decorators/middleware.decorator.ts

@@ -8,15 +8,28 @@ import { IResponse, Request } from "src/request";
 import { Logger } from "src/utils/logger";
 import { MaybeAsync, Type } from "src/utils/types";
 
-
+/**
+ * NextFunction is a function that is called to continue the middleware chain.
+ * It returns an Promise that emits when the next middleware is done.
+ */
 export type NextFunction = () => Promise<void>;
 
+/**
+ * IMiddleware interface defines a middleware that can be used in the application.
+ * It has an `invoke` method that takes a request, a response, and a next function.
+ * The `invoke` method can return a MaybeAsync, which means it can return either a value or a Promise.
+ *
+ * Use it on a class that should be registered as a middleware in the application.
+ */
 export interface IMiddleware {
     invoke(request: Request, response: IResponse, next: NextFunction): MaybeAsync<void>;
 }
 
-const middlewares = new Map<string, Type<IMiddleware>[]>();
-
+/**
+ * UseMiddlewares decorator can be used to register middlewares for a controller or a controller action.
+ *
+ * @param mdlw - The middlewares list to register for the controller or the controller action.
+ */
 export function UseMiddlewares(mdlw: Type<IMiddleware>[]): ClassDecorator & MethodDecorator {
     return (target: Function | object, propertyKey?: string | symbol) => {
         let key: string;
@@ -43,12 +56,29 @@ export function UseMiddlewares(mdlw: Type<IMiddleware>[]): ClassDecorator & Meth
     };
 }
 
+/**
+ * Gets the middlewares for a controller or a controller action.
+ * This function retrieves the middlewares registered with the UseMiddlewares decorator.
+ * It returns an array of middleware classes that can be used to process requests for the specified controller.
+ * @param controllerName The name of the controller to get the middlewares for.
+ * @returns An array of middlewares for the controller.
+ */
 export function getMiddlewaresForController(controllerName: string): Type<IMiddleware>[] {
     const key = `${controllerName}`;
     return middlewares.get(key) ?? [];
 }
 
+/**
+ * Gets the middlewares for a controller action.
+ * This function retrieves the middlewares registered with the UseMiddlewares decorator for a specific action in a controller.
+ * It returns an array of middleware classes that can be used to process requests for the specified controller action.
+ * @param controllerName The name of the controller to get the middlewares for.
+ * @param actionName The name of the action to get the middlewares for.
+ * @returns An array of middlewares for the controller action.
+ */
 export function getMiddlewaresForControllerAction(controllerName: string, actionName: string): Type<IMiddleware>[] {
     const key = `${controllerName}.${actionName}`;
     return middlewares.get(key) ?? [];
-}
+}
+
+const middlewares = new Map<string, Type<IMiddleware>[]>();

package/src/decorators/module.decorator.ts

@@ -8,13 +8,26 @@ import { CONTROLLER_METADATA_KEY } from "src/decorators/controller.decorator";
 import { Injectable, INJECTABLE_METADATA_KEY } from "src/decorators/injectable.decorator";
 import { Type } from "src/utils/types";
 
+export interface IModuleMetadata {
+    imports?: Type<unknown>[];
+    exports?: Type<unknown>[];
+    providers?: Type<unknown>[];
+    controllers?: Type<unknown>[];
+}
+
+/**
+ * Module decorator is used to define a module in the application.
+ * It is a kind of node in the routing tree, that can contains controllers, services, and other modules.
+ *
+ * @param metadata - The metadata for the module.
+ */
 export function Module(metadata: IModuleMetadata): ClassDecorator {
     return (target: Function) => {
         // Validate imports and exports: must be decorated with @Module
         const checkModule = (arr?: Type<unknown>[], arrName?: string): void => {
             if(!arr)
                 return;
-            
+
             for(const clazz of arr) {
                 if(!Reflect.getMetadata(MODULE_METADATA_KEY, clazz)) {
                     throw new Error(`Class ${clazz.name} in ${arrName} must be decorated with @Module`);
@@ -55,15 +68,8 @@ export function Module(metadata: IModuleMetadata): ClassDecorator {
     };
 }
 
-export const MODULE_METADATA_KEY = Symbol('MODULE_METADATA_KEY');
-
-export interface IModuleMetadata {
-    imports?: Type<unknown>[];
-    exports?: Type<unknown>[];
-    providers?: Type<unknown>[];
-    controllers?: Type<unknown>[];
-}
-
 export function getModuleMetadata(target: Function): IModuleMetadata | undefined {
     return Reflect.getMetadata(MODULE_METADATA_KEY, target);
-}
+}
+
+export const MODULE_METADATA_KEY = Symbol('MODULE_METADATA_KEY');

package/src/request.ts

@@ -8,6 +8,11 @@ import 'reflect-metadata';
 import { HttpMethod } from 'src/decorators/method.decorator';
 import { AppInjector, RootInjector } from 'src/DI/app-injector';
 
+/**
+ * The Request class represents an HTTP request in the Noxus framework.
+ * It encapsulates the request data, including the event, ID, method, path, and body.
+ * It also provides a context for dependency injection through the AppInjector.
+ */
 export class Request {
     public readonly context: AppInjector = RootInjector.createScope();
 
@@ -24,6 +29,11 @@ export class Request {
     }
 }
 
+/**
+ * The IRequest interface defines the structure of a request object.
+ * It includes properties for the sender ID, request ID, path, method, and an optional body.
+ * This interface is used to standardize the request data across the application.
+ */
 export interface IRequest<T = any> {
     senderId: number;
     requestId: string;
@@ -32,6 +42,10 @@ export interface IRequest<T = any> {
     body?: T;
 }
 
+/**
+ * Creates a Request object from the IPC event data.
+ * This function extracts the necessary information from the IPC event and constructs a Request instance.
+ */
 export interface IResponse<T = any> {
     requestId: string;
     status: number;