@noxfly/noxus 2.5.0 → 3.0.0-dev.1

package/dist/request-CdpZ9qZL.d.ts

@@ -1,167 +0,0 @@
-import { M as MaybeAsync, T as Type, A as AppInjector } from './app-injector-B3MvgV3k.js';
-
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-/**
- * 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
- */
-interface IGuard {
-    canActivate(request: Request): MaybeAsync<boolean>;
-}
-/**
- * Can be used to protect the routes of a controller.
- * Can be used on a controller class or on a controller method.
- */
-declare function Authorize(...guardClasses: Type<IGuard>[]): MethodDecorator & ClassDecorator;
-/**
- * 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.
- */
-declare function getGuardForController(controllerName: string): Type<IGuard>[];
-/**
- * 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.
- */
-declare function getGuardForControllerAction(controllerName: string, actionName: string): Type<IGuard>[];
-
-
-/**
- * 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.
- */
-interface IRouteMetadata {
-    method: HttpMethod;
-    path: string;
-    handler: string;
-    guards: Type<IGuard>[];
-}
-/**
- * The different HTTP methods that can be used in the application.
- */
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'BATCH';
-/**
- * Atomic HTTP verbs supported by controllers. BATCH is handled at the router level only.
- */
-type AtomicHttpMethod = Exclude<HttpMethod, 'BATCH'>;
-/**
- * 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.
- */
-declare function getRouteMetadata(target: Type<unknown>): IRouteMetadata[];
-/**
- * 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.
- */
-declare const Get: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Post: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Put: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Patch: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Delete: (path: string) => MethodDecorator;
-declare const ROUTE_METADATA_KEY: unique symbol;
-
-
-/**
- * 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.
- */
-declare class Request {
-    readonly event: Electron.MessageEvent;
-    readonly senderId: number;
-    readonly id: string;
-    readonly method: HttpMethod;
-    readonly path: string;
-    readonly body: any;
-    readonly context: AppInjector;
-    readonly params: Record<string, string>;
-    constructor(event: Electron.MessageEvent, senderId: number, id: string, method: HttpMethod, path: string, body: any);
-}
-/**
- * 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.
- */
-interface IRequest<TBody = unknown> {
-    senderId: number;
-    requestId: string;
-    path: string;
-    method: HttpMethod;
-    body?: TBody;
-}
-interface IBatchRequestItem<TBody = unknown> {
-    requestId?: string;
-    path: string;
-    method: AtomicHttpMethod;
-    body?: TBody;
-}
-interface IBatchRequestPayload {
-    requests: IBatchRequestItem[];
-}
-/**
- * Creates a Request object from the IPC event data.
- * This function extracts the necessary information from the IPC event and constructs a Request instance.
- */
-interface IResponse<TBody = unknown> {
-    requestId: string;
-    status: number;
-    body?: TBody;
-    error?: string;
-    stack?: string;
-}
-interface IBatchResponsePayload {
-    responses: IResponse[];
-}
-declare const RENDERER_EVENT_TYPE = "noxus:event";
-interface IRendererEventMessage<TPayload = unknown> {
-    type: typeof RENDERER_EVENT_TYPE;
-    event: string;
-    payload?: TPayload;
-}
-declare function createRendererEventMessage<TPayload = unknown>(event: string, payload?: TPayload): IRendererEventMessage<TPayload>;
-declare function isRendererEventMessage(value: unknown): value is IRendererEventMessage;
-
-export { type AtomicHttpMethod as A, Delete as D, Get as G, type HttpMethod as H, type IRendererEventMessage as I, Post as P, Request as R, type IResponse as a, type IRequest as b, type IBatchRequestItem as c, type IBatchResponsePayload as d, type IBatchRequestPayload as e, RENDERER_EVENT_TYPE as f, createRendererEventMessage as g, type IGuard as h, isRendererEventMessage as i, Authorize as j, getGuardForController as k, getGuardForControllerAction as l, type IRouteMetadata as m, getRouteMetadata as n, Put as o, Patch as p, ROUTE_METADATA_KEY as q };

package/dist/request-Dx_5Prte.d.mts

@@ -1,167 +0,0 @@
-import { M as MaybeAsync, T as Type, A as AppInjector } from './app-injector-B3MvgV3k.mjs';
-
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-/**
- * 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
- */
-interface IGuard {
-    canActivate(request: Request): MaybeAsync<boolean>;
-}
-/**
- * Can be used to protect the routes of a controller.
- * Can be used on a controller class or on a controller method.
- */
-declare function Authorize(...guardClasses: Type<IGuard>[]): MethodDecorator & ClassDecorator;
-/**
- * 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.
- */
-declare function getGuardForController(controllerName: string): Type<IGuard>[];
-/**
- * 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.
- */
-declare function getGuardForControllerAction(controllerName: string, actionName: string): Type<IGuard>[];
-
-
-/**
- * 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.
- */
-interface IRouteMetadata {
-    method: HttpMethod;
-    path: string;
-    handler: string;
-    guards: Type<IGuard>[];
-}
-/**
- * The different HTTP methods that can be used in the application.
- */
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'BATCH';
-/**
- * Atomic HTTP verbs supported by controllers. BATCH is handled at the router level only.
- */
-type AtomicHttpMethod = Exclude<HttpMethod, 'BATCH'>;
-/**
- * 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.
- */
-declare function getRouteMetadata(target: Type<unknown>): IRouteMetadata[];
-/**
- * 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.
- */
-declare const Get: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Post: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Put: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Patch: (path: string) => MethodDecorator;
-/**
- * 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.
- */
-declare const Delete: (path: string) => MethodDecorator;
-declare const ROUTE_METADATA_KEY: unique symbol;
-
-
-/**
- * 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.
- */
-declare class Request {
-    readonly event: Electron.MessageEvent;
-    readonly senderId: number;
-    readonly id: string;
-    readonly method: HttpMethod;
-    readonly path: string;
-    readonly body: any;
-    readonly context: AppInjector;
-    readonly params: Record<string, string>;
-    constructor(event: Electron.MessageEvent, senderId: number, id: string, method: HttpMethod, path: string, body: any);
-}
-/**
- * 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.
- */
-interface IRequest<TBody = unknown> {
-    senderId: number;
-    requestId: string;
-    path: string;
-    method: HttpMethod;
-    body?: TBody;
-}
-interface IBatchRequestItem<TBody = unknown> {
-    requestId?: string;
-    path: string;
-    method: AtomicHttpMethod;
-    body?: TBody;
-}
-interface IBatchRequestPayload {
-    requests: IBatchRequestItem[];
-}
-/**
- * Creates a Request object from the IPC event data.
- * This function extracts the necessary information from the IPC event and constructs a Request instance.
- */
-interface IResponse<TBody = unknown> {
-    requestId: string;
-    status: number;
-    body?: TBody;
-    error?: string;
-    stack?: string;
-}
-interface IBatchResponsePayload {
-    responses: IResponse[];
-}
-declare const RENDERER_EVENT_TYPE = "noxus:event";
-interface IRendererEventMessage<TPayload = unknown> {
-    type: typeof RENDERER_EVENT_TYPE;
-    event: string;
-    payload?: TPayload;
-}
-declare function createRendererEventMessage<TPayload = unknown>(event: string, payload?: TPayload): IRendererEventMessage<TPayload>;
-declare function isRendererEventMessage(value: unknown): value is IRendererEventMessage;
-
-export { type AtomicHttpMethod as A, Delete as D, Get as G, type HttpMethod as H, type IRendererEventMessage as I, Post as P, Request as R, type IResponse as a, type IRequest as b, type IBatchRequestItem as c, type IBatchResponsePayload as d, type IBatchRequestPayload as e, RENDERER_EVENT_TYPE as f, createRendererEventMessage as g, type IGuard as h, isRendererEventMessage as i, Authorize as j, getGuardForController as k, getGuardForControllerAction as l, type IRouteMetadata as m, getRouteMetadata as n, Put as o, Patch as p, ROUTE_METADATA_KEY as q };

package/src/app.ts

@@ -1,244 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { app, BrowserWindow, ipcMain, MessageChannelMain } from "electron/main";
-import { Injectable } from "src/decorators/injectable.decorator";
-import { IMiddleware } from "src/decorators/middleware.decorator";
-import { inject } from "src/DI/app-injector";
-import { InjectorExplorer } from "src/DI/injector-explorer";
-import { IRequest, IResponse, Request } from "src/request";
-import { NoxSocket } from "src/socket";
-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(mainWindow?: BrowserWindow): 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 app: IApp | undefined;
-    private mainWindow: BrowserWindow | undefined;
-
-    /**
-     *
-     */
-    private readonly onRendererMessage = async (event: Electron.MessageEvent): Promise<void> => {
-        const { senderId, requestId, path, method, body }: IRequest = event.data;
-
-        const channels = this.socket.get(senderId);
-
-        if(!channels) {
-            Logger.error(`No message channel found for sender ID: ${senderId}`);
-            return;
-        }
-
-        try {
-            const request = new Request(event, senderId, requestId, method, path, body);
-            const response = await this.router.handle(request);
-            channels.request.port1.postMessage(response);
-        }
-        catch(err: any) {
-            const response: IResponse = {
-                requestId,
-                status: 500,
-                body: null,
-                error: err.message || 'Internal Server Error',
-            };
-
-            channels.request.port1.postMessage(response);
-        }
-    };
-
-    constructor(
-        private readonly router: Router,
-        private readonly socket: NoxSocket,
-    ) {}
-
-    /**
-     * 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));
-
-        app.once('activate', this.onAppActivated.bind(this));
-        app.once('window-all-closed', this.onAllWindowsClosed.bind(this));
-
-        console.log(''); // create a new line in the console to separate setup logs from the future logs
-
-        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.
-     */
-    private giveTheRendererAPort(event: Electron.IpcMainInvokeEvent): void {
-        const senderId = event.sender.id;
-
-        if(this.socket.get(senderId)) {
-            this.shutdownChannel(senderId);
-        }
-
-        const requestChannel = new MessageChannelMain();
-        const socketChannel = new MessageChannelMain();
-
-        requestChannel.port1.on('message', this.onRendererMessage);
-        requestChannel.port1.start();
-        socketChannel.port1.start();
-
-        this.socket.register(senderId, requestChannel, socketChannel);
-
-        event.sender.postMessage('port', { senderId }, [requestChannel.port2, socketChannel.port2]);
-    }
-
-    /**
-     * MacOS specific behavior.
-     */
-    private onAppActivated(): void {
-        if(process.platform === 'darwin' && BrowserWindow.getAllWindows().length === 0) {
-            this.app?.onActivated();
-        }
-    }
-
-    /**
-     * 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 channels = this.socket.get(channelSenderId);
-
-        if(!channels) {
-            Logger.warn(`No message channel found for sender ID: ${channelSenderId}`);
-            return;
-        }
-
-        channels.request.port1.off('message', this.onRendererMessage);
-        channels.request.port1.close();
-        channels.request.port2.close();
-
-        channels.socket.port1.close();
-        channels.socket.port2.close();
-
-        this.socket.unregister(channelSenderId);
-    }
-
-    /**
-     * 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> {
-        for(const senderId of this.socket.getSenderIds()) {
-            this.shutdownChannel(senderId);
-        }
-
-        Logger.info('All windows closed, shutting down application...');
-        await this.app?.dispose();
-
-        if(process.platform !== 'darwin') {
-            app.quit();
-        }
-    }
-
-
-    // ---
-
-    /**
-     * Sets the main BrowserWindow that was created early by bootstrapApplication.
-     * This window will be passed to IApp.onReady when start() is called.
-     * @param window - The BrowserWindow created during bootstrap.
-     */
-    public setMainWindow(window: BrowserWindow): void {
-        this.mainWindow = window;
-    }
-
-    /**
-     * Registers a lazy-loaded route. The module behind this path prefix
-     * will only be dynamically imported when the first IPC request
-     * targets this prefix — like Angular's loadChildren.
-     *
-     * @example
-     * ```ts
-     * noxApp.lazy("auth", () => import("./modules/auth/auth.module.js"));
-     * noxApp.lazy("printing", () => import("./modules/printing/printing.module.js"));
-     * ```
-     *
-     * @param pathPrefix - The route prefix (e.g. "auth", "cash-register").
-     * @param loadModule - A function returning a dynamic import promise.
-     * @returns NoxApp instance for method chaining.
-     */
-    public lazy(pathPrefix: string, loadModule: () => Promise<unknown>): NoxApp {
-        this.router.registerLazyRoute(pathPrefix, loadModule);
-        return this;
-    }
-
-    /**
-     * Eagerly loads one or more modules with a two-phase DI guarantee.
-     * Use this when a service needed at startup lives inside a module
-     * (e.g. the Application service depends on LoaderService).
-     *
-     * All dynamic imports run in parallel; bindings are registered first,
-     * then singletons are resolved — safe regardless of import ordering.
-     *
-     * @param importFns - Functions returning dynamic import promises.
-     */
-    public async loadModules(importFns: Array<() => Promise<unknown>>): Promise<void> {
-        InjectorExplorer.beginAccumulate();
-        await Promise.all(importFns.map(fn => fn()));
-        InjectorExplorer.flushAccumulated();
-    }
-
-    /**
-     * 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;
-    }
-
-    /**
-     * Should be called after the bootstrapApplication function is called.
-     * Passes the early-created BrowserWindow (if any) to the configured IApp service.
-     * @returns NoxApp instance for method chaining.
-     */
-    public start(): NoxApp {
-        this.app?.onReady(this.mainWindow);
-        return this;
-    }
-}

package/src/bootstrap.ts

@@ -1,84 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { app, BrowserWindow, screen } from "electron/main";
-import { NoxApp } from "src/app";
-import { getModuleMetadata } from "src/decorators/module.decorator";
-import { inject } from "src/DI/app-injector";
-import { InjectorExplorer } from "src/DI/injector-explorer";
-import { Type } from "src/utils/types";
-
-/**
- * Options for bootstrapping the Noxus application.
- */
-export interface BootstrapOptions {
-    /**
-     * If provided, Noxus creates a BrowserWindow immediately after Electron is ready,
-     * before any DI processing occurs. This window is passed to the configured
-     * IApp service via onReady(). It allows the user to see a window as fast as possible,
-     * even before the application is fully initialized.
-     */
-    window?: Electron.BrowserWindowConstructorOptions;
-}
-
-/**
- * Bootstraps the Noxus application.
- * This function initializes the application by creating an instance of NoxApp,
- * registering the root module, and starting the application.
- *
- * When {@link BootstrapOptions.window} is provided, a BrowserWindow is created
- * immediately after Electron readiness — before DI resolution — so the user
- * sees a window as quickly as possible.
- *
- * @param rootModule - The root module of the application, decorated with @Module.
- * @param options - Optional bootstrap configuration.
- * @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> | null, options?: BootstrapOptions): Promise<NoxApp> {
-    if(rootModule && !getModuleMetadata(rootModule)) {
-        throw new Error(`Root module must be decorated with @Module`);
-    }
-
-    await app.whenReady();
-
-    // Create window immediately after Electron is ready, before DI processing.
-    // This gets pixels on screen as fast as possible.
-    let mainWindow: BrowserWindow | undefined;
-
-    if(options?.window) {
-        mainWindow = new BrowserWindow(options.window);
-
-        mainWindow.once("ready-to-show", () => {
-            mainWindow?.show();
-        });
-
-        const primaryDisplay = screen.getPrimaryDisplay();
-        const { width, height } = primaryDisplay.workAreaSize;
-
-        if(options.window.minWidth && options.window.minHeight) {
-            mainWindow.setSize(
-                Math.min(width, options.window.minWidth),
-                Math.min(height, options.window.minHeight),
-                true,
-            );
-        }
-    }
-
-    // Process all deferred injectable registrations (two-phase: bindings then resolution)
-    InjectorExplorer.processPending();
-
-    const noxApp = inject(NoxApp);
-
-    if(mainWindow) {
-        noxApp.setMainWindow(mainWindow);
-    }
-
-    await noxApp.init();
-
-    return noxApp;
-}
-

package/src/decorators/inject.decorator.ts

@@ -1,24 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import 'reflect-metadata';
-
-export const INJECT_METADATA_KEY = 'custom:inject';
-
-/**
- * Decorator to manually inject a dependency.
- * Useful for handling circular dependencies with `forwardRef` or injecting specific tokens.
- *
- * @param token The token or forward reference to inject.
- */
-export function Inject(token: any): ParameterDecorator {
-    return (target, propertyKey, parameterIndex) => {
-        // target is the constructor for constructor parameters
-        const existingParameters = Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) || [];
-        existingParameters[parameterIndex] = token;
-        Reflect.defineMetadata(INJECT_METADATA_KEY, existingParameters, target);
-    };
-}