@noxfly/noxus 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NoxFly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# ⚡ Noxus — The NestJS-Inspired Framework Built for Electron
+
+Noxus brings the elegance and power of NestJS-like architecture to Electron applications — but with a purpose-built design for IPC and MessagePort communication instead of HTTP.
+
+While NestJS is an excellent framework for building web servers, it is not suited for Electron environments where communication between the main process and the renderer is critical.
+
+Transferring data between these using a local server and using HTTP request would be a waste of resources for the user's target device.
+
+Noxus fills that gap.
+
+✅ Use of decorators
+
+✅ Use of dependency injection, with lifetimes management (singleton, scope, transient)
+
+✅ Modular architecture with the use of modules, defining a map of controllers and services
+
+✅ Automatic and performant controller and route registration with path and method mapping
+
+✅ A true request/response model built on top of MessagePort to look like HTTP requests
+
+✅ Custom exception handling and unified error responses
+
+✅ Decorator-based guard system for route and controller authorization
+
+✅ Scoped dependency injection per request context
+
+✅ Setup the electron application and communication with your renderer easily and with flexibility
+
+✅ TypeScript-first with full type safety and metadata reflection
+
+✅ Pluggable logging with color-coded output for different log levels
+
+<sub>* If you see any issue and you'd like to enhance this framework, feel free to open an issue, fork and do a pull request.</sub>
+
+## Installation
+
+Install the package in your main process application :
+
+```sh
+npm i @noxfly/noxus
+```
+
+If you have a separated renderer from the main process, you'd like to install the package as well to get typed requests/responses models, for development purposes :
+
+```sh
+npm i -D @noxfly/noxus
+```
+
+Because you only need types during development, using the `-D` argument will make this package a `devDependency`, thus won't be present on your build.
+
+## Basic use
+
+When employing "main", we consider this is the electron side of your application.
+
+When employing "renderer", this is the separated renderer side of your application.
+
+However, you can feel free to keep both merged, this won't change anything, but for further examples, this will be done to show you where the code should go.
+
+### Setup Main Process side
+
+```ts
+// main/index.ts
+
+import { bootstrapApplication } from '@noxfly/noxus';
+import { Application } from './modules/app.service.ts';
+
+async function main() {
+    const application = await bootstrapApplication(Application, AppModule);
+}
+
+main();
+```
+
+> ℹ️ Note that you have to specify which service you'd like to see as your application root's service, so the framework can interact with it and setup things on it.
+
+```ts
+// main/modules/app.service.ts
+
+import { IApp, Injectable, Logger } from '@noxfly/noxus';
+
+@Injectable('singleton')
+export class Application implements IApp {
+    constructor(
+        private readonly windowManager: WindowManager, // An Injectable too
+    ) {}
+
+    // automatically called by the bootstrapApplication function
+    // once it is all setup
+    public async onReady(): Promise<void> {
+        Logger.info("Application's ready");
+        this.windowManager.createMain(); // Your custom logic here to create a window
+    }
+}
+```
+
+```ts
+// main/modules/app.module.ts
+
+import { Module } from '@noxfly/noxus';
+
+@Module({
+    imports: [UsersModule], // import modules to be found here
+    providers: [], // define services that should be found here
+    controllers: [], // define controllers that this module has to create a route node
+})
+export class AppModule {}
+```
+
+> ℹ️ Note that we do not register Application service in it because it already has been registered when bootstraping the application.
+
+```ts
+// main/modules/users/users.module.ts
+
+import { Module } from '@noxfly/noxus';
+
+@Module({
+    providers: [UsersService],
+    controllers: [UsersController],
+})
+export class UsersModule {}
+```
+
+```ts
+// main/modules/users/users.service.ts
+
+import { Injectable } from '@noxfly/noxus';
+
+@Injectable()
+export class UsersService {
+    public async findAll(): Promise<User[]> {
+        // ...
+    }
+
+    public async findOneById(id: string): Promise<User> {
+        // ...
+    }
+}
+```
+
+> ℹ️ You can specify the lifetime of an injectable passing a value in the decorator, between `singleton`, `scope` or `transient` (default to `scope`).
+
+```ts
+// main/modules/users/users.controller.ts
+
+import { Controller, Get } from '@noxfly/noxus';
+import { UsersService } from './users.service.ts';
+
+@Controller('users')
+export class UsersController {
+    constructor(
+        private readonly usersService: UsersService,
+    ) {}
+
+    @Get('all')
+    public getAll(): Promise<User[]> {
+        return await this.usersService.findAll();
+    }
+
+    @Get('profile/:id')
+    @Authorize(AuthGuard)
+    public getProfile(IRequest request, IResponse response): Promise<User | undefined> {
+        return await this.usersService.findOneById(request.params.id);
+    }
+}
+```
+
+Further upgrades might include new decorators like `@Param()`, `@Body()` etc... like Nest.js offers.
+
+```ts
+// main/guards/auth.guard.ts
+
+import { IGuard, Injectable, MaybeAsync, Request } from 'nox';
+
+@Injectable()
+export class AuthGuard implements IGuard {
+    constructor(
+        private readonly authService: AuthService
+    ) {}
+
+    public async canActivate(IRequest request): MaybeAsync<boolean> {
+        return this.authService.isAuthenticated();
+    }
+}
+```
+
+Here is the output (not with that exact same example) when running the main process :
+
+![Startup image](./images/screenshot-startup.png)
+
+
+### Setup Preload
+
+We need some configuration on the preload so the main process can give the renderer a port (MessagePort) to communicate with. Everytime this is requested, a new channel is created, an d the previous is closed.
+
+```ts
+// main/preload.ts
+
+import { contextBridge, ipcRenderer } from 'electron/renderer';
+
+// .invoke -> front sends to back
+// .on -> back sends to front
+
+type fn = (...args: any[]) => void;
+
+contextBridge.exposeInMainWorld('ipcRenderer', {
+    requestPort: () => ipcRenderer.send('gimme-my-port'),
+    
+    hereIsMyPort: () => ipcRenderer.once('port', (e) => {
+        e.ports[0]?.start();
+        window.postMessage({ type: 'init-port' }, '*', [e.ports[0]!]);
+    }),
+});
+```
+
+> ⚠️ As the Electron documentation warns well, you should NEVER expose the whole ipcRenderer to the renderer. Expose only restricted API that your renderer could use.
+
+We need to use `window.postMessage()` and not a custom callback function, otherwise the port would have been structuredCloned and would only arrive to the renderer with the `onmessage` function, and nothing else (a bit frustrating to not request, isn't it).
+
+
+### Setup Renderer
+
+I am personnally using Angular as renderer, so there might be some changes if you use another framework or vanilla js, but it is only about typescript's configuration and types.
+
+Maybe this should become a class directly available from @noxfly/noxus;
+
+```ts
+// renderer/anyFileAtStartup.ts
+
+import { IRequest, IResponse } from '@noxfly/noxus';
+
+interface PendingRequestHandlers<T> {
+    resolve: (value: IResponse<T>) => void;
+    reject: (reason?: IResponse<T>) => void;
+    request: IRequest;
+}
+
+// might be a singleton service
+class ElectronService {
+    private readonly bridge: any;
+    private readonly ipcRenderer: any; // if you know how to get a type, tell me
+
+    private port: MessagePort | undefined;
+    private readonly pendingRequests = new Map<string, PendingRequestsHandlers<any>>();
+
+    constructor() {
+        this.bridge = window as any;
+        this.ipcRenderer = this.bridge.ipcRenderer;
+
+        // when receiving the port given by the main renderer -> preload -> renderer
+        window.addEventListener('message', (event: MessageEvent) => {
+            if(event.data?.type === 'init-port' && event.ports.length > 0) {
+                this.port = event.ports[0]!;
+                this.port.onmessage = onResponse;
+            }
+        });
+
+        ipcRenderer.requestPort();
+    }
+
+    /**
+     * Resolve the signal-based response
+     */
+    private onResponse(event: MessageEvent): void {
+        const response: IResponse<unknown> = event.data;
+
+        if(!response || !response.requestId) {
+            console.error('Received invalid response:', response);
+            return;
+        }
+
+        const pending = this.pendingRequests.get(response.requestId);
+        
+        if(!pending) {
+            console.error(`No handler found for request ID: ${response.requestId}`);
+            return;
+        }
+        
+        this.pendingRequests.delete(response.requestId);
+
+        let fn: (response: IResponse<unknown>) => void = pending.resolve;
+
+        console.groupCollapsed(`${response.status} ${pending.request.method} /${pending.request.path}`);
+        
+        if(response.error) {
+            console.error('error message:', response.error);
+            fn = pending.reject;
+        }
+        
+        console.info('response:', response.body);
+        console.info('request:', pending.request);
+
+        console.groupEnd();
+
+        fn(response);
+    }
+
+    /**
+     * Initiate a request to the main process
+     */
+    public request<T>(request: Omit<IRequest, 'requestId'>): Promise<T> {
+        return new Promise<T>((resolve, reject) => {
+            if(!this.port) {
+                return reject(new Error("MessagePort is not available"));
+            }
+        
+            const req: IRequest = {
+                requestId: /* Create a random ID with the function of your choice */,
+                ...request,
+            };
+        
+            this.pendingRequests.set(req.requestId, {
+                resolve: (response: IResponse<T>) => (response.status < 400)
+                    ? resolve(response.body as T)
+                    : reject(response);
+                reject: (response?: IResponse<T>) => reject(response),
+                request: req,
+            });
+        
+            this.port.postMessage(req);
+        });
+    }
+}
+```
+
+Use it like that :
+
+```ts
+const response: User[] = await electronService.request<User[]>({
+    method: 'GET',
+    path: 'users/all',
+});
+```
+
+![Startup image](./images/screenshot-requests.png)
+
+
+## Contributing
+
+1. Clone the repo
+1. `npm i`
+1. Develop
+1. Push changes (automatically builds)
+1. Create a PR
+
+if you'd like to test your changes locally :
+1. `npm run build`
+1. from an electron project, `npm i ../<path/to/repo>`
+

package/dist/noxus.d.mts

@@ -0,0 +1,231 @@
+type MaybeAsync<T> = T | Promise<T>;
+
+interface IApp {
+    dispose(): Promise<void>;
+    onReady(): Promise<void>;
+}
+declare function Injectable(lifetime?: Lifetime): ClassDecorator;
+declare function Module(metadata: IModuleMetadata): ClassDecorator;
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface IRouteDefinition {
+    method: string;
+    path: string;
+    controller: Type<any>;
+    handler: string;
+    guards: Type<IGuard>[];
+}
+type ControllerAction = (request: Request, response: IResponse) => any;
+declare function Controller(path: string): ClassDecorator;
+declare const Get: (path: string) => MethodDecorator;
+declare const Post: (path: string) => MethodDecorator;
+declare const Put: (path: string) => MethodDecorator;
+declare const Patch: (path: string) => MethodDecorator;
+declare const Delete: (path: string) => MethodDecorator;
+declare class Router {
+    private readonly routes;
+    registerController(controllerClass: Type<unknown>): Router;
+    handle(request: Request): Promise<IResponse>;
+    private findRoute;
+    private resolveController;
+    private verifyRequestBody;
+    private extractParams;
+}
+
+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 params: Record<string, string>;
+    constructor(app: IApp, event: Electron.MessageEvent, id: string, method: HttpMethod, path: string, body: any);
+}
+interface IRequest<T = any> {
+    requestId: string;
+    path: string;
+    method: HttpMethod;
+    body?: T;
+}
+interface IResponse<T = any> {
+    requestId: string;
+    status: number;
+    body?: T;
+    error?: string;
+}
+
+interface IGuard {
+    canActivate(request: Request): MaybeAsync<boolean>;
+}
+/**
+ * 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.
+ */
+declare function Authorize(...guardClasses: Type<IGuard>[]): MethodDecorator & ClassDecorator;
+declare function getGuardForController(controllerName: string): Type<IGuard>[];
+declare function getGuardForControllerAction(controllerName: string, actionName: string): Type<IGuard>[];
+
+interface Type<T> extends Function {
+    new (...args: any[]): T;
+}
+declare const MODULE_METADATA_KEY: unique symbol;
+declare const INJECTABLE_METADATA_KEY: unique symbol;
+declare const CONTROLLER_METADATA_KEY: unique symbol;
+declare const ROUTE_METADATA_KEY: unique symbol;
+interface IModuleMetadata {
+    imports?: Type<unknown>[];
+    providers?: Type<unknown>[];
+    controllers?: Type<unknown>[];
+    exports?: Type<unknown>[];
+}
+interface IRouteMetadata {
+    method: HttpMethod;
+    path: string;
+    handler: string;
+    guards: Type<IGuard>[];
+}
+interface IControllerMetadata {
+    path: string;
+    guards: Type<IGuard>[];
+}
+declare function getControllerMetadata(target: Type<unknown>): IControllerMetadata | undefined;
+declare function getRouteMetadata(target: Type<unknown>): IRouteMetadata[];
+declare function getModuleMetadata(target: Function): IModuleMetadata | undefined;
+declare function getInjectableMetadata(target: Type<unknown>): Lifetime | undefined;
+
+type Lifetime = 'singleton' | 'scope' | 'transient';
+interface IBinding {
+    lifetime: Lifetime;
+    implementation: Type<unknown>;
+    instance?: InstanceType<Type<unknown>>;
+}
+declare class AppInjector {
+    readonly name: string | null;
+    bindings: Map<Type<unknown>, IBinding>;
+    singletons: Map<Type<unknown>, unknown>;
+    scoped: Map<Type<unknown>, unknown>;
+    constructor(name?: string | null);
+    /**
+     * 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)
+     */
+    createScope(): AppInjector;
+    /**
+     * Appelé lorsqu'on souhaite résoudre une dépendance,
+     * c'est-à-dire récupérer l'instance d'une classe donnée.
+     */
+    resolve<T extends Type<unknown>>(target: T): InstanceType<T>;
+    /**
+     *
+     */
+    private instantiate;
+}
+declare const RootInjector: AppInjector;
+
+/**
+ *
+ */
+declare function bootstrapApplication(root: Type<IApp>, rootModule: Type<any>): Promise<IApp>;
+
+declare abstract class ResponseException extends Error {
+    abstract readonly status: number;
+    constructor(message: string);
+}
+declare class BadRequestException extends ResponseException {
+    readonly status = 400;
+}
+declare class UnauthorizedException extends ResponseException {
+    readonly status = 401;
+}
+declare class ForbiddenException extends ResponseException {
+    readonly status = 403;
+}
+declare class NotFoundException extends ResponseException {
+    readonly status = 404;
+}
+declare class MethodNotAllowedException extends ResponseException {
+    readonly status = 405;
+}
+declare class NotAcceptableException extends ResponseException {
+    readonly status = 406;
+}
+declare class RequestTimeoutException extends ResponseException {
+    readonly status = 408;
+}
+declare class ConflictException extends ResponseException {
+    readonly status = 409;
+}
+declare class UpgradeRequiredException extends ResponseException {
+    readonly status = 426;
+}
+declare class TooManyRequestsException extends ResponseException {
+    readonly status = 429;
+}
+declare class InternalServerException extends ResponseException {
+    readonly status = 500;
+}
+declare class NotImplementedException extends ResponseException {
+    readonly status = 501;
+}
+declare class BadGatewayException extends ResponseException {
+    readonly status = 502;
+}
+declare class ServiceUnavailableException extends ResponseException {
+    readonly status = 503;
+}
+declare class GatewayTimeoutException extends ResponseException {
+    readonly status = 504;
+}
+declare class HttpVersionNotSupportedException extends ResponseException {
+    readonly status = 505;
+}
+declare class VariantAlsoNegotiatesException extends ResponseException {
+    readonly status = 506;
+}
+declare class InsufficientStorageException extends ResponseException {
+    readonly status = 507;
+}
+declare class LoopDetectedException extends ResponseException {
+    readonly status = 508;
+}
+declare class NotExtendedException extends ResponseException {
+    readonly status = 510;
+}
+declare class NetworkAuthenticationRequiredException extends ResponseException {
+    readonly status = 511;
+}
+declare class NetworkConnectTimeoutException extends ResponseException {
+    readonly status = 599;
+}
+
+type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+declare namespace Logger {
+    function setLogLevel(level: LogLevel): void;
+    const colors: {
+        black: string;
+        grey: string;
+        red: string;
+        green: string;
+        brown: string;
+        blue: string;
+        purple: string;
+        darkGrey: string;
+        lightRed: string;
+        lightGreen: string;
+        yellow: string;
+        lightBlue: string;
+        magenta: string;
+        cyan: string;
+        white: string;
+        initial: string;
+    };
+    function log(...args: any[]): void;
+    function info(...args: any[]): void;
+    function warn(...args: any[]): void;
+    function error(...args: any[]): void;
+    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 };