@noxfly/noxus 1.0.4 → 1.1.0

package/.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/README.md

@@ -62,10 +62,15 @@ However, you can feel free to keep both merged, this won't change anything, but
 // main/index.ts
 
 import { bootstrapApplication } from '@noxfly/noxus';
+import { AppModule } from './modules/app.module.ts';
 import { Application } from './modules/app.service.ts';
 
-async function main() {
-    const application = await bootstrapApplication(Application, AppModule);
+async function main(): Promise<void> {
+    const noxApp = await bootstrapApplication(AppModule);
+
+    noxApp.configure(Application);
+
+    noxApp.start();
 }
 
 main();
@@ -205,9 +210,9 @@ type fn = (...args: any[]) => void;
 contextBridge.exposeInMainWorld('ipcRenderer', {
     requestPort: () => ipcRenderer.send('gimme-my-port'),
     
-    hereIsMyPort: () => ipcRenderer.once('port', (e) => {
+    hereIsMyPort: () => ipcRenderer.once('port', (e, message) => {
         e.ports[0]?.start();
-        window.postMessage({ type: 'init-port' }, '*', [e.ports[0]!]);
+        window.postMessage({ type: 'init-port', senderId: message.senderId }, '*', [e.ports[0]!]);
     }),
 });
 ```
@@ -240,6 +245,7 @@ class ElectronService {
     private readonly ipcRenderer: any; // if you know how to get a type, tell me
 
     private port: MessagePort | undefined;
+    private senderId: number | undefined;
     private readonly pendingRequests = new Map<string, PendingRequestsHandlers<any>>();
 
     constructor() {
@@ -250,6 +256,7 @@ class ElectronService {
         window.addEventListener('message', (event: MessageEvent) => {
             if(event.data?.type === 'init-port' && event.ports.length > 0) {
                 this.port = event.ports[0]!;
+                this.senderId = event.data.senderId;
                 this.port.onmessage = onResponse;
             }
         });
@@ -297,14 +304,15 @@ class ElectronService {
     /**
      * Initiate a request to the main process
      */
-    public request<T>(request: Omit<IRequest, 'requestId'>): Promise<T> {
+    public request<T>(request: Omit<IRequest, 'requestId' | 'senderId'>): Promise<T> {
         return new Promise<T>((resolve, reject) => {
-            if(!this.port) {
+            if(!this.port || !this.senderId) {
                 return reject(new Error("MessagePort is not available"));
             }
         
             const req: IRequest = {
                 requestId: /* Create a random ID with the function of your choice */,
+                senderId: this.senderId,
                 ...request,
             };
         
@@ -379,6 +387,100 @@ throw new UnavailableException();
 | 599         | NetworkConnectTimeoutException         |
 
 
+## Advanced
+
+### Injection
+
+You can decide to inject an Injectable without passing by the constructor, as follow :
+
+```ts
+import { inject } from '@noxfly/noxus';
+import { MyClass } from 'src/myclass';
+
+const instance: MyClass = inject(MyClass);
+```
+
+### Middlewares
+
+Declare middlewares as follow :
+
+```ts
+// renderer/middlewares.ts
+
+import { IMiddleware, Injectable, Request, IResponse, NextFunction } from '@noxfly/noxus';
+
+@Injectable()
+export class MiddlewareA implements IMiddleware {
+    public async invoke(request: Request, response: IResponse, next: NextFunction): Promise<void> {
+        console.log(`[Middleware A] before next()`);
+        await next();
+        console.log(`[Middleware A] after next()`);
+    }
+}
+
+@Injectable()
+export class MiddlewareB implements IMiddleware {
+    public async invoke(request: Request, response: IResponse, next: NextFunction): Promise<void> {
+        console.log(`[Middleware B] before next()`);
+        await next();
+        console.log(`[Middleware B] after next()`);
+    }
+}
+```
+
+It is highly recommended to `await` the call of the `next` function.
+
+Register these by 3 possible ways :
+
+1. For a root scope. Will be present for each routes.
+
+```ts
+const noxApp = bootstrapApplication(AppModule);
+
+noxApp.configure(Application);
+
+noxApp.use(MiddlewareA);
+noxApp.use(MiddlewareB);
+
+noxApp.start();
+```
+
+2. Or for a controller or action's scope :
+
+```ts
+@Controller('user')
+@UseMiddlewares([MiddlewareA, MiddlewareB])
+export class UserController {
+    @Get('all')
+    @UseMiddlewares([MiddlewareA, MiddlewareB])
+    public getAll(): Promise<void> {
+        // ...
+    }
+}
+```
+
+Note that if, for a given action, it has registered multiples times the same middleware, only the first registration will be saved.
+
+For instance, registering MiddlewareA for root, on the controller and on the action is useless.
+
+The order of declaration of use of middlewares is important.
+
+assume we do this :
+1. Use Middleware A for root
+2. Use Middleware B for root just after MiddlewareA
+3. Use Middleware C for controller
+4. Use Middleware D for action
+5. Use AuthGuard on the controller
+6. Use RoleGuard on the action
+
+Then the executing pipeline will be as follow :
+
+```r
+A -> B -> C -> D -> AuthGuard -> RoleGuard -> [action] -> D -> C -> B -> A.
+```
+
+if a middleware throw any exception or put the response status higher or equal to 400, the pipeline immediatly stops and the response is returned, weither it is done before or after the call to the next function.
+
 ## Contributing
 
 1. Clone the repo

package/dist/noxus.d.mts

@@ -1,8 +1,14 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
 interface Type<T> extends Function {
     new (...args: any[]): T;
 }
 type MaybeAsync<T> = T | Promise<T>;
 
+
 type Lifetime = 'singleton' | 'scope' | 'transient';
 interface IBinding {
     lifetime: Lifetime;
@@ -31,11 +37,8 @@ declare class AppInjector {
     private instantiate;
 }
 declare const RootInjector: AppInjector;
+declare function inject<T>(t: Type<T>): T;
 
-interface IApp {
-    dispose(): Promise<void>;
-    onReady(): Promise<void>;
-}
 
 interface IRouteMetadata {
     method: HttpMethod;
@@ -52,18 +55,19 @@ declare const Delete: (path: string) => MethodDecorator;
 declare const ROUTE_METADATA_KEY: unique symbol;
 declare function getRouteMetadata(target: Type<unknown>): IRouteMetadata[];
 
+
 declare class Request {
-    readonly app: IApp;
     readonly event: Electron.MessageEvent;
     readonly id: string;
     readonly method: HttpMethod;
     readonly path: string;
     readonly body: any;
-    readonly context: any;
+    readonly context: AppInjector;
     readonly params: Record<string, string>;
-    constructor(app: IApp, event: Electron.MessageEvent, id: string, method: HttpMethod, path: string, body: any);
+    constructor(event: Electron.MessageEvent, id: string, method: HttpMethod, path: string, body: any);
 }
 interface IRequest<T = any> {
+    senderId: number;
     requestId: string;
     path: string;
     method: HttpMethod;
@@ -76,6 +80,7 @@ interface IResponse<T = any> {
     error?: string;
 }
 
+
 interface IGuard {
     canActivate(request: Request): MaybeAsync<boolean>;
 }
@@ -87,32 +92,117 @@ declare function Authorize(...guardClasses: Type<IGuard>[]): MethodDecorator & C
 declare function getGuardForController(controllerName: string): Type<IGuard>[];
 declare function getGuardForControllerAction(controllerName: string, actionName: string): Type<IGuard>[];
 
+
+type NextFunction = () => Promise<void>;
+interface IMiddleware {
+    invoke(request: Request, response: IResponse, next: NextFunction): MaybeAsync<void>;
+}
+declare function UseMiddlewares(mdlw: Type<IMiddleware>[]): ClassDecorator & MethodDecorator;
+declare function getMiddlewaresForController(controllerName: string): Type<IMiddleware>[];
+declare function getMiddlewaresForControllerAction(controllerName: string, actionName: string): Type<IMiddleware>[];
+
+
 interface IRouteDefinition {
     method: string;
     path: string;
     controller: Type<any>;
     handler: string;
     guards: Type<IGuard>[];
+    middlewares: Type<IMiddleware>[];
 }
 type ControllerAction = (request: Request, response: IResponse) => any;
 declare class Router {
     private readonly routes;
+    private readonly rootMiddlewares;
+    /**
+     *
+     */
     registerController(controllerClass: Type<unknown>): Router;
+    /**
+     *
+     */
+    defineRootMiddleware(middleware: Type<IMiddleware>): Router;
+    /**
+     *
+     */
     handle(request: Request): Promise<IResponse>;
+    /**
+     *
+     */
     private findRoute;
+    /**
+     *
+     */
     private resolveController;
-    private verifyRequestBody;
+    /**
+     *
+     */
+    private runRequestPipeline;
+    /**
+     *
+     */
+    private runMiddleware;
+    /**
+     *
+     */
+    private runGuard;
+    /**
+     *
+     */
     private extractParams;
 }
 
+
+interface IApp {
+    dispose(): Promise<void>;
+    onReady(): Promise<void>;
+    onActivated(): Promise<void>;
+}
+declare class NoxApp {
+    private readonly router;
+    private readonly messagePorts;
+    private app;
+    constructor(router: Router);
+    /**
+     *
+     */
+    init(): Promise<NoxApp>;
+    /**
+     *
+     */
+    private giveTheRendererAPort;
+    /**
+     * Electron specific message handling.
+     * Replaces HTTP calls by using Electron's IPC mechanism.
+     */
+    private onRendererMessage;
+    /**
+     * MacOS specific behavior.
+     */
+    private onAppActivated;
+    private shutdownChannel;
+    /**
+     *
+     */
+    private onAllWindowsClosed;
+    configure(app: Type<IApp>): NoxApp;
+    use(middleware: Type<IMiddleware>): NoxApp;
+    /**
+     * Should be called after the bootstrapApplication function is called.
+     */
+    start(): NoxApp;
+}
+
+
 /**
  *
  */
-declare function bootstrapApplication(root: Type<IApp>, rootModule: Type<any>): Promise<IApp>;
+declare function bootstrapApplication(rootModule: Type<any>): Promise<NoxApp>;
 
-declare abstract class ResponseException extends Error {
-    abstract readonly status: number;
+declare class ResponseException extends Error {
+    readonly status: number;
     constructor(message?: string);
+    constructor(statusCode?: number, message?: string);
 }
 declare class BadRequestException extends ResponseException {
     readonly status = 400;
@@ -120,6 +210,9 @@ declare class BadRequestException extends ResponseException {
 declare class UnauthorizedException extends ResponseException {
     readonly status = 401;
 }
+declare class PaymentRequiredException extends ResponseException {
+    readonly status = 402;
+}
 declare class ForbiddenException extends ResponseException {
     readonly status = 403;
 }
@@ -181,6 +274,7 @@ declare class NetworkConnectTimeoutException extends ResponseException {
     readonly status = 599;
 }
 
+
 interface IControllerMetadata {
     path: string;
     guards: Type<IGuard>[];
@@ -189,10 +283,12 @@ declare function Controller(path: string): ClassDecorator;
 declare const CONTROLLER_METADATA_KEY: unique symbol;
 declare function getControllerMetadata(target: Type<unknown>): IControllerMetadata | undefined;
 
+
 declare function Injectable(lifetime?: Lifetime): ClassDecorator;
 declare const INJECTABLE_METADATA_KEY: unique symbol;
 declare function getInjectableMetadata(target: Type<unknown>): Lifetime | undefined;
 
+
 declare function Module(metadata: IModuleMetadata): ClassDecorator;
 declare const MODULE_METADATA_KEY: unique symbol;
 interface IModuleMetadata {
@@ -231,4 +327,4 @@ declare namespace Logger {
     function debug(...args: any[]): void;
 }
 
-export { Authorize, BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, Delete, ForbiddenException, GatewayTimeoutException, Get, type HttpMethod, HttpVersionNotSupportedException, type IApp, type IBinding, type IControllerMetadata, type IGuard, type IModuleMetadata, INJECTABLE_METADATA_KEY, type IRequest, type IResponse, type IRouteDefinition, type IRouteMetadata, Injectable, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, type MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, Patch, Post, Put, ROUTE_METADATA_KEY, Request, RequestTimeoutException, ResponseException, RootInjector, Router, ServiceUnavailableException, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, bootstrapApplication, getControllerMetadata, getGuardForController, getGuardForControllerAction, getInjectableMetadata, getModuleMetadata, getRouteMetadata };
+export { AppInjector, Authorize, BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, Delete, ForbiddenException, GatewayTimeoutException, Get, type HttpMethod, HttpVersionNotSupportedException, type IApp, type IBinding, type IControllerMetadata, type IGuard, type IMiddleware, type IModuleMetadata, INJECTABLE_METADATA_KEY, type IRequest, type IResponse, type IRouteDefinition, type IRouteMetadata, Injectable, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, type MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, Patch, PaymentRequiredException, Post, Put, ROUTE_METADATA_KEY, Request, RequestTimeoutException, ResponseException, RootInjector, Router, ServiceUnavailableException, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, UseMiddlewares, VariantAlsoNegotiatesException, bootstrapApplication, getControllerMetadata, getGuardForController, getGuardForControllerAction, getInjectableMetadata, getMiddlewaresForController, getMiddlewaresForControllerAction, getModuleMetadata, getRouteMetadata, inject };

package/dist/noxus.d.ts

@@ -1,8 +1,14 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
 interface Type<T> extends Function {
     new (...args: any[]): T;
 }
 type MaybeAsync<T> = T | Promise<T>;
 
+
 type Lifetime = 'singleton' | 'scope' | 'transient';
 interface IBinding {
     lifetime: Lifetime;
@@ -31,11 +37,8 @@ declare class AppInjector {
     private instantiate;
 }
 declare const RootInjector: AppInjector;
+declare function inject<T>(t: Type<T>): T;
 
-interface IApp {
-    dispose(): Promise<void>;
-    onReady(): Promise<void>;
-}
 
 interface IRouteMetadata {
     method: HttpMethod;
@@ -52,18 +55,19 @@ declare const Delete: (path: string) => MethodDecorator;
 declare const ROUTE_METADATA_KEY: unique symbol;
 declare function getRouteMetadata(target: Type<unknown>): IRouteMetadata[];
 
+
 declare class Request {
-    readonly app: IApp;
     readonly event: Electron.MessageEvent;
     readonly id: string;
     readonly method: HttpMethod;
     readonly path: string;
     readonly body: any;
-    readonly context: any;
+    readonly context: AppInjector;
     readonly params: Record<string, string>;
-    constructor(app: IApp, event: Electron.MessageEvent, id: string, method: HttpMethod, path: string, body: any);
+    constructor(event: Electron.MessageEvent, id: string, method: HttpMethod, path: string, body: any);
 }
 interface IRequest<T = any> {
+    senderId: number;
     requestId: string;
     path: string;
     method: HttpMethod;
@@ -76,6 +80,7 @@ interface IResponse<T = any> {
     error?: string;
 }
 
+
 interface IGuard {
     canActivate(request: Request): MaybeAsync<boolean>;
 }
@@ -87,32 +92,117 @@ declare function Authorize(...guardClasses: Type<IGuard>[]): MethodDecorator & C
 declare function getGuardForController(controllerName: string): Type<IGuard>[];
 declare function getGuardForControllerAction(controllerName: string, actionName: string): Type<IGuard>[];
 
+
+type NextFunction = () => Promise<void>;
+interface IMiddleware {
+    invoke(request: Request, response: IResponse, next: NextFunction): MaybeAsync<void>;
+}
+declare function UseMiddlewares(mdlw: Type<IMiddleware>[]): ClassDecorator & MethodDecorator;
+declare function getMiddlewaresForController(controllerName: string): Type<IMiddleware>[];
+declare function getMiddlewaresForControllerAction(controllerName: string, actionName: string): Type<IMiddleware>[];
+
+
 interface IRouteDefinition {
     method: string;
     path: string;
     controller: Type<any>;
     handler: string;
     guards: Type<IGuard>[];
+    middlewares: Type<IMiddleware>[];
 }
 type ControllerAction = (request: Request, response: IResponse) => any;
 declare class Router {
     private readonly routes;
+    private readonly rootMiddlewares;
+    /**
+     *
+     */
     registerController(controllerClass: Type<unknown>): Router;
+    /**
+     *
+     */
+    defineRootMiddleware(middleware: Type<IMiddleware>): Router;
+    /**
+     *
+     */
     handle(request: Request): Promise<IResponse>;
+    /**
+     *
+     */
     private findRoute;
+    /**
+     *
+     */
     private resolveController;
-    private verifyRequestBody;
+    /**
+     *
+     */
+    private runRequestPipeline;
+    /**
+     *
+     */
+    private runMiddleware;
+    /**
+     *
+     */
+    private runGuard;
+    /**
+     *
+     */
     private extractParams;
 }
 
+
+interface IApp {
+    dispose(): Promise<void>;
+    onReady(): Promise<void>;
+    onActivated(): Promise<void>;
+}
+declare class NoxApp {
+    private readonly router;
+    private readonly messagePorts;
+    private app;
+    constructor(router: Router);
+    /**
+     *
+     */
+    init(): Promise<NoxApp>;
+    /**
+     *
+     */
+    private giveTheRendererAPort;
+    /**
+     * Electron specific message handling.
+     * Replaces HTTP calls by using Electron's IPC mechanism.
+     */
+    private onRendererMessage;
+    /**
+     * MacOS specific behavior.
+     */
+    private onAppActivated;
+    private shutdownChannel;
+    /**
+     *
+     */
+    private onAllWindowsClosed;
+    configure(app: Type<IApp>): NoxApp;
+    use(middleware: Type<IMiddleware>): NoxApp;
+    /**
+     * Should be called after the bootstrapApplication function is called.
+     */
+    start(): NoxApp;
+}
+
+
 /**
  *
  */
-declare function bootstrapApplication(root: Type<IApp>, rootModule: Type<any>): Promise<IApp>;
+declare function bootstrapApplication(rootModule: Type<any>): Promise<NoxApp>;
 
-declare abstract class ResponseException extends Error {
-    abstract readonly status: number;
+declare class ResponseException extends Error {
+    readonly status: number;
     constructor(message?: string);
+    constructor(statusCode?: number, message?: string);
 }
 declare class BadRequestException extends ResponseException {
     readonly status = 400;
@@ -120,6 +210,9 @@ declare class BadRequestException extends ResponseException {
 declare class UnauthorizedException extends ResponseException {
     readonly status = 401;
 }
+declare class PaymentRequiredException extends ResponseException {
+    readonly status = 402;
+}
 declare class ForbiddenException extends ResponseException {
     readonly status = 403;
 }
@@ -181,6 +274,7 @@ declare class NetworkConnectTimeoutException extends ResponseException {
     readonly status = 599;
 }
 
+
 interface IControllerMetadata {
     path: string;
     guards: Type<IGuard>[];
@@ -189,10 +283,12 @@ declare function Controller(path: string): ClassDecorator;
 declare const CONTROLLER_METADATA_KEY: unique symbol;
 declare function getControllerMetadata(target: Type<unknown>): IControllerMetadata | undefined;
 
+
 declare function Injectable(lifetime?: Lifetime): ClassDecorator;
 declare const INJECTABLE_METADATA_KEY: unique symbol;
 declare function getInjectableMetadata(target: Type<unknown>): Lifetime | undefined;
 
+
 declare function Module(metadata: IModuleMetadata): ClassDecorator;
 declare const MODULE_METADATA_KEY: unique symbol;
 interface IModuleMetadata {
@@ -231,4 +327,4 @@ declare namespace Logger {
     function debug(...args: any[]): void;
 }
 
-export { Authorize, BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, Delete, ForbiddenException, GatewayTimeoutException, Get, type HttpMethod, HttpVersionNotSupportedException, type IApp, type IBinding, type IControllerMetadata, type IGuard, type IModuleMetadata, INJECTABLE_METADATA_KEY, type IRequest, type IResponse, type IRouteDefinition, type IRouteMetadata, Injectable, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, type MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, Patch, Post, Put, ROUTE_METADATA_KEY, Request, RequestTimeoutException, ResponseException, RootInjector, Router, ServiceUnavailableException, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, bootstrapApplication, getControllerMetadata, getGuardForController, getGuardForControllerAction, getInjectableMetadata, getModuleMetadata, getRouteMetadata };
+export { AppInjector, Authorize, BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, Delete, ForbiddenException, GatewayTimeoutException, Get, type HttpMethod, HttpVersionNotSupportedException, type IApp, type IBinding, type IControllerMetadata, type IGuard, type IMiddleware, type IModuleMetadata, INJECTABLE_METADATA_KEY, type IRequest, type IResponse, type IRouteDefinition, type IRouteMetadata, Injectable, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, type MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, Patch, PaymentRequiredException, Post, Put, ROUTE_METADATA_KEY, Request, RequestTimeoutException, ResponseException, RootInjector, Router, ServiceUnavailableException, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, UseMiddlewares, VariantAlsoNegotiatesException, bootstrapApplication, getControllerMetadata, getGuardForController, getGuardForControllerAction, getInjectableMetadata, getMiddlewaresForController, getMiddlewaresForControllerAction, getModuleMetadata, getRouteMetadata, inject };