@noxfly/noxus 3.0.0-dev.4 → 3.0.0-dev.5

package/src/internal/request.ts

@@ -1,102 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-
-import { AtomicHttpMethod, HttpMethod } from '../decorators/method.decorator';
-import { AppInjector, RootInjector } from '../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();
-
-    public readonly params: Record<string, string> = {};
-    public readonly query: Record<string, string>;
-
-    constructor(
-        public readonly event: Electron.MessageEvent,
-        public readonly senderId: number,
-        public readonly id: string,
-        public readonly method: HttpMethod,
-        public readonly path: string,
-        public readonly body: unknown,
-        query?: Record<string, string>,
-    ) {
-        this.path = path.replace(/^\/|\/$/g, '');
-        this.query = query ?? {};
-    }
-}
-
-/**
- * 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<TBody = unknown> {
-    senderId: number;
-    requestId: string;
-    path: string;
-    method: HttpMethod;
-    body?: TBody;
-    query?: Record<string, string>;
-}
-
-export interface IBatchRequestItem<TBody = unknown> {
-    requestId?: string;
-    path: string;
-    method: AtomicHttpMethod;
-    body?: TBody;
-    query?: Record<string, string>;
-}
-
-export 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.
- */
-export interface IResponse<TBody = unknown> {
-    requestId: string;
-    status: number;
-    body?: TBody;
-    error?: string;
-    stack?: string;
-}
-
-export interface IBatchResponsePayload {
-    responses: IResponse[];
-}
-
-export const RENDERER_EVENT_TYPE = 'noxus:event';
-
-export interface IRendererEventMessage<TPayload = unknown> {
-    type: typeof RENDERER_EVENT_TYPE;
-    event: string;
-    payload?: TPayload;
-}
-
-export function createRendererEventMessage<TPayload = unknown>(event: string, payload?: TPayload): IRendererEventMessage<TPayload> {
-    return {
-        type: RENDERER_EVENT_TYPE,
-        event,
-        payload,
-    };
-}
-
-export function isRendererEventMessage(value: unknown): value is IRendererEventMessage {
-    if(value === null || typeof value !== 'object') {
-        return false;
-    }
-
-    const possibleMessage = value as Partial<IRendererEventMessage>;
-
-    return possibleMessage.type === RENDERER_EVENT_TYPE && typeof possibleMessage.event === 'string';
-}

package/src/internal/router.ts

@@ -1,365 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { getControllerMetadata } from '../decorators/controller.decorator';
-import { Guard } from '../decorators/guards.decorator';
-import { Injectable } from '../decorators/injectable.decorator';
-import { getRouteMetadata, isAtomicHttpMethod } from '../decorators/method.decorator';
-import { Middleware, NextFunction } from '../decorators/middleware.decorator';
-import { InjectorExplorer } from '../DI/injector-explorer';
-import { Logger } from '../utils/logger';
-import { RadixTree } from '../utils/radix-tree';
-import { Type } from '../utils/types';
-import {
-    BadRequestException,
-    NotFoundException,
-    ResponseException,
-    UnauthorizedException
-} from './exceptions';
-import { IBatchRequestItem, IBatchRequestPayload, IBatchResponsePayload, IResponse, Request } from './request';
-
-export interface ILazyRoute {
-    load: () => Promise<unknown>;
-    guards: Guard[];
-    middlewares: Middleware[];
-    loading: Promise<void> | null;
-    loaded: boolean;
-}
-
-interface LazyRouteEntry {
-    load: (() => Promise<unknown>) | null;
-    guards: Guard[];
-    middlewares: Middleware[];
-    loading: Promise<void> | null;
-    loaded: boolean;
-}
-
-export interface IRouteDefinition {
-    method: string;
-    path: string;
-    controller: Type<unknown>;
-    handler: string;
-    guards: Guard[];
-    middlewares: Middleware[];
-}
-
-export type ControllerAction = (request: Request, response: IResponse) => unknown;
-
-@Injectable({ lifetime: 'singleton' })
-export class Router {
-    private readonly routes = new RadixTree<IRouteDefinition>();
-    private readonly rootMiddlewares: Middleware[] = [];
-    private readonly lazyRoutes = new Map<string, LazyRouteEntry>();
-
-    // -------------------------------------------------------------------------
-    // Registration
-    // -------------------------------------------------------------------------
-
-    public registerController(
-        controllerClass: Type<unknown>,
-        pathPrefix: string,
-        routeGuards: Guard[] = [],
-        routeMiddlewares: Middleware[] = [],
-    ): this {
-        const meta = getControllerMetadata(controllerClass);
-
-        if (!meta) {
-            throw new Error(`[Noxus] Missing @Controller decorator on ${controllerClass.name}`);
-        }
-
-        const routeMeta = getRouteMetadata(controllerClass);
-
-        for (const def of routeMeta) {
-            const fullPath = `${pathPrefix}/${def.path}`.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
-
-            // Route-level guards/middlewares from defineRoutes() + action-level ones
-            const guards      = [...new Set([...routeGuards,      ...def.guards])];
-            const middlewares = [...new Set([...routeMiddlewares,  ...def.middlewares])];
-
-            const routeDef: IRouteDefinition = {
-                method: def.method,
-                path: fullPath,
-                controller: controllerClass,
-                handler: def.handler,
-                guards,
-                middlewares,
-            };
-
-            this.routes.insert(fullPath + '/' + def.method, routeDef);
-
-            const guardInfo = guards.length ? `<${guards.map(g => g.name).join('|')}>` : '';
-            Logger.log(`Mapped {${def.method} /${fullPath}}${guardInfo} route`);
-        }
-
-        const ctrlGuardInfo = routeGuards.length
-            ? `<${routeGuards.map(g => g.name).join('|')}>`
-            : '';
-        Logger.log(`Mapped ${controllerClass.name}${ctrlGuardInfo} controller's routes`);
-
-        return this;
-    }
-
-    public registerLazyRoute(
-        pathPrefix: string,
-        load: () => Promise<unknown>,
-        guards: Guard[] = [],
-        middlewares: Middleware[] = [],
-    ): this {
-        const normalized = pathPrefix.replace(/^\/+|\/+$/g, '');
-        this.lazyRoutes.set(normalized, { load, guards, middlewares, loading: null, loaded: false });
-        Logger.log(`Registered lazy route prefix {${normalized}}`);
-        return this;
-    }
-
-    public defineRootMiddleware(middleware: Middleware): this {
-        this.rootMiddlewares.push(middleware);
-        return this;
-    }
-
-    public getRegisteredRoutes(): Array<{ method: string; path: string; }> {
-        const allRoutes = this.routes.collectValues();
-        return allRoutes.map(r => ({ method: r.method, path: r.path }));
-    }
-
-    public getLazyRoutes(): Array<{ prefix: string; loaded: boolean; }> {
-        return [...this.lazyRoutes.entries()].map(([prefix, entry]) => ({
-            prefix,
-            loaded: entry.loaded,
-        }));
-    }
-
-    // -------------------------------------------------------------------------
-    // Request handling
-    // -------------------------------------------------------------------------
-
-    public async handle(request: Request): Promise<IResponse> {
-        return request.method === 'BATCH'
-            ? this.handleBatch(request)
-            : this.handleAtomic(request);
-    }
-
-    private async handleAtomic(request: Request): Promise<IResponse> {
-        Logger.comment(`>     ${request.method} /${request.path}`);
-        const t0 = performance.now();
-
-        const response: IResponse = { requestId: request.id, status: 200, body: null };
-        let isCritical = false;
-
-        try {
-            const routeDef = await this.findRoute(request);
-            await this.resolveController(request, response, routeDef);
-
-            if (response.status >= 400) throw new ResponseException(response.status, response.error);
-        }
-        catch (error) {
-            this.fillErrorResponse(response, error, (c) => { isCritical = c; });
-        }
-        finally {
-            this.logResponse(request, response, performance.now() - t0, isCritical);
-            return response;
-        }
-    }
-
-    private async handleBatch(request: Request): Promise<IResponse> {
-        Logger.comment(`>     ${request.method} /${request.path}`);
-        const t0 = performance.now();
-
-        const response: IResponse<IBatchResponsePayload> = {
-            requestId: request.id,
-            status: 200,
-            body: { responses: [] },
-        };
-        let isCritical = false;
-
-        try {
-            const payload = this.normalizeBatchPayload(request.body);
-            response.body!.responses = await Promise.all(
-                payload.requests.map((item, i) => {
-                    const id = item.requestId ?? `${request.id}:${i}`;
-                    return this.handleAtomic(new Request(request.event, request.senderId, id, item.method, item.path, item.body, item.query));
-                }),
-            );
-        }
-        catch (error) {
-            this.fillErrorResponse(response, error, (c) => { isCritical = c; });
-        }
-        finally {
-            this.logResponse(request, response, performance.now() - t0, isCritical);
-            return response;
-        }
-    }
-
-    // -------------------------------------------------------------------------
-    // Route resolution
-    // -------------------------------------------------------------------------
-
-    private tryFindRoute(request: Request): IRouteDefinition | undefined {
-        const matched = this.routes.search(request.path);
-        if (!matched?.node || matched.node.children.length === 0) return undefined;
-        return matched.node.findExactChild(request.method)?.value;
-    }
-
-    private async findRoute(request: Request): Promise<IRouteDefinition> {
-        const direct = this.tryFindRoute(request);
-        if (direct) return direct;
-
-        await this.tryLoadLazyRoute(request.path);
-
-        const afterLazy = this.tryFindRoute(request);
-        if (afterLazy) return afterLazy;
-
-        throw new NotFoundException(`No route matches ${request.method} ${request.path}`);
-    }
-
-    private async tryLoadLazyRoute(requestPath: string): Promise<void> {
-        const firstSegment = requestPath.replace(/^\/+/, '').split('/')[0] ?? '';
-
-        for (const [prefix, entry] of this.lazyRoutes) {
-            if (entry.loaded) continue;
-            const normalized = requestPath.replace(/^\/+/, '');
-            if (normalized === prefix || normalized.startsWith(prefix + '/') || firstSegment === prefix) {
-                if (!entry.loading) entry.loading = this.loadLazyModule(prefix, entry);
-                await entry.loading;
-                return;
-            }
-        }
-    }
-
-    private async loadLazyModule(prefix: string, entry: LazyRouteEntry): Promise<void> {
-        const t0 = performance.now();
-        InjectorExplorer.beginAccumulate();
-
-        await entry.load?.();
-
-        entry.loading = null;
-        entry.load = null;
-
-        await InjectorExplorer.flushAccumulated(entry.guards, entry.middlewares, prefix);
-
-        entry.loaded = true;
-
-        Logger.info(`Lazy-loaded module for prefix {${prefix}} in ${Math.round(performance.now() - t0)}ms`);
-    }
-
-    // -------------------------------------------------------------------------
-    // Pipeline
-    // -------------------------------------------------------------------------
-
-    private async resolveController(request: Request, response: IResponse, routeDef: IRouteDefinition): Promise<void> {
-        const instance = request.context.resolve(routeDef.controller);
-        Object.assign(request.params, this.extractParams(request.path, routeDef.path));
-        await this.runPipeline(request, response, routeDef, instance);
-    }
-
-    private async runPipeline(
-        request: Request,
-        response: IResponse,
-        routeDef: IRouteDefinition,
-        controllerInstance: unknown,
-    ): Promise<void> {
-        const middlewares = [...new Set([...this.rootMiddlewares, ...routeDef.middlewares])];
-        const mwMax = middlewares.length - 1;
-        const guardMax = mwMax + routeDef.guards.length;
-        let index = -1;
-
-        const dispatch = async (i: number): Promise<void> => {
-            if (i <= index) throw new Error('next() called multiple times');
-            index = i;
-
-            if (i <= mwMax) {
-                await this.runMiddleware(request, response, dispatch.bind(null, i + 1), middlewares[i]!);
-                if (response.status >= 400) throw new ResponseException(response.status, response.error);
-                return;
-            }
-
-            if (i <= guardMax) {
-                await this.runGuard(request, routeDef.guards[i - middlewares.length]!);
-                await dispatch(i + 1);
-                return;
-            }
-
-            const action = (controllerInstance as Record<string, ControllerAction>)[routeDef.handler]!;
-            response.body = await action.call(controllerInstance, request, response);
-            if (response.body === undefined) response.body = {};
-        };
-
-        await dispatch(0);
-    }
-
-    private async runMiddleware(request: Request, response: IResponse, next: NextFunction, middleware: Middleware): Promise<void> {
-        await middleware(request, response, next);
-    }
-
-    private async runGuard(request: Request, guard: Guard): Promise<void> {
-        if (!await guard(request)) {
-            throw new UnauthorizedException(`Unauthorized for ${request.method} ${request.path}`);
-        }
-    }
-
-    // -------------------------------------------------------------------------
-    // Utilities
-    // -------------------------------------------------------------------------
-
-    private extractParams(actual: string, template: string): Record<string, string> {
-        const aParts = actual.split('/');
-        const tParts = template.split('/');
-        const params: Record<string, string> = {};
-        tParts.forEach((part, i) => {
-            if (part.startsWith(':')) params[part.slice(1)] = aParts[i] ?? '';
-        });
-        return params;
-    }
-
-    private normalizeBatchPayload(body: unknown): IBatchRequestPayload {
-        if (body === null || typeof body !== 'object') {
-            throw new BadRequestException('Batch payload must be an object containing a requests array.');
-        }
-        const { requests } = body as Partial<IBatchRequestPayload>;
-        if (!Array.isArray(requests)) throw new BadRequestException('Batch payload must define a requests array.');
-        return { requests: requests.map((e, i) => this.normalizeBatchItem(e, i)) };
-    }
-
-    private normalizeBatchItem(entry: unknown, index: number): IBatchRequestItem {
-        if (entry === null || typeof entry !== 'object') throw new BadRequestException(`Batch request at index ${index} must be an object.`);
-        const { requestId, path, method, body } = entry as Partial<IBatchRequestItem> & { method?: unknown };
-        if (requestId !== undefined && typeof requestId !== 'string') throw new BadRequestException(`Batch request at index ${index} has an invalid requestId.`);
-        if (typeof path !== 'string' || !path.length) throw new BadRequestException(`Batch request at index ${index} must define a non-empty path.`);
-        if (typeof method !== 'string') throw new BadRequestException(`Batch request at index ${index} must define an HTTP method.`);
-        const normalized = method.toUpperCase();
-        if (!isAtomicHttpMethod(normalized)) throw new BadRequestException(`Batch request at index ${index} uses unsupported method ${method}.`);
-        return { requestId, path, method: normalized, body };
-    }
-
-    private fillErrorResponse(response: IResponse, error: unknown, setCritical: (v: boolean) => void): void {
-        response.body = undefined;
-        if (error instanceof ResponseException) {
-            response.status = error.status;
-            response.error = error.message;
-            response.stack = error.stack;
-        } else if (error instanceof Error) {
-            setCritical(true);
-            response.status = 500;
-            response.error = error.message || 'Internal Server Error';
-            response.stack = error.stack;
-        } else {
-            setCritical(true);
-            response.status = 500;
-            response.error = 'Unknown error occurred';
-        }
-    }
-
-    private logResponse(request: Request, response: IResponse, ms: number, isCritical: boolean): void {
-        const msg = `< ${response.status} ${request.method} /${request.path} ${Logger.colors.yellow}${Math.round(ms)}ms${Logger.colors.initial}`;
-        if (response.status < 400) Logger.log(msg);
-        else if (response.status < 500) Logger.warn(msg);
-        else isCritical ? Logger.critical(msg) : Logger.error(msg);
-
-        if (response.error) {
-            isCritical ? Logger.critical(response.error) : Logger.error(response.error);
-            if (response.stack) Logger.errorStack(response.stack);
-        }
-    }
-}

package/src/internal/routes.ts

@@ -1,142 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Guard } from '../decorators/guards.decorator';
-import { Middleware } from '../decorators/middleware.decorator';
-
-/**
- * A single route entry in the application routing table.
- */
-export interface RouteDefinition {
-    /**
-     * The path prefix for this route (e.g. 'users', 'orders').
-     * All actions defined in the controller will be prefixed with this path.
-     */
-    path: string;
-
-    /**
-     * Dynamic import function returning the controller file.
-     * The controller is loaded lazily on the first IPC request targeting this prefix.
-     *
-     * Optional when the route only serves as a parent for `children`.
-     *
-     * @example
-     * load: () => import('./modules/users/users.controller')
-     */
-    load?: () => Promise<unknown>;
-
-    /**
-     * Guards applied to every action in this controller.
-     * Merged with action-level guards.
-     */
-    guards?: Guard[];
-
-    /**
-     * Middlewares applied to every action in this controller.
-     * Merged with action-level middlewares.
-     */
-    middlewares?: Middleware[];
-
-    /**
-     * Nested child routes. Guards and middlewares declared here are
-     * inherited (merged) by all children.
-     */
-    children?: RouteDefinition[];
-}
-
-/**
- * Defines the application routing table.
- * Each entry maps a path prefix to a lazily-loaded controller.
- *
- * This is the single source of truth for routing — no path is declared
- * in @Controller(), preventing duplicate route prefixes across controllers.
- *
- * Supports nested routes via the `children` property. Guards and middlewares
- * from parent entries are inherited (merged) into each child.
- *
- * @example
- * export const routes = defineRoutes([
- *     {
- *         path: 'users',
- *         load: () => import('./modules/users/users.controller'),
- *         guards: [authGuard],
- *     },
- *     {
- *         path: 'admin',
- *         guards: [authGuard, adminGuard],
- *         children: [
- *             { path: 'users',    load: () => import('./admin/users.controller') },
- *             { path: 'products', load: () => import('./admin/products.controller') },
- *         ],
- *     },
- * ]);
- */
-export function defineRoutes(routes: RouteDefinition[]): RouteDefinition[] {
-    const flat = flattenRoutes(routes);
-
-    const paths = flat.map(r => r.path);
-
-    // Check exact duplicates
-    const duplicates = paths.filter((p, i) => paths.indexOf(p) !== i);
-    if (duplicates.length > 0) {
-        throw new Error(
-            `[Noxus] Duplicate route prefixes detected: ${[...new Set(duplicates)].map(d => `"${d}"`).join(', ')}`
-        );
-    }
-
-    // Check overlapping prefixes (e.g. 'users' and 'users/admin')
-    const sorted = [...paths].sort();
-    for (let i = 0; i < sorted.length - 1; i++) {
-        const a = sorted[i]!;
-        const b = sorted[i + 1]!;
-        if (b.startsWith(a + '/')) {
-            throw new Error(
-                `[Noxus] Overlapping route prefixes detected: "${a}" and "${b}". ` +
-                `Use nested children under "${a}" instead of declaring both as top-level routes.`
-            );
-        }
-    }
-
-    return flat;
-}
-
-/**
- * Recursively flattens nested route definitions, merging parent guards / middlewares.
- */
-function flattenRoutes(
-    routes: RouteDefinition[],
-    parentPath = '',
-    parentGuards: Guard[] = [],
-    parentMiddlewares: Middleware[] = [],
-): RouteDefinition[] {
-    const result: RouteDefinition[] = [];
-
-    for (const route of routes) {
-        const path = [parentPath, route.path.replace(/^\/+|\/+$/g, '')]
-            .filter(Boolean)
-            .join('/');
-
-        const guards = [...new Set([...parentGuards, ...(route.guards ?? [])])];
-        const middlewares = [...new Set([...parentMiddlewares, ...(route.middlewares ?? [])])];
-
-        if (route.load) {
-            result.push({ ...route, path, guards, middlewares });
-        }
-
-        if (route.children?.length) {
-            result.push(...flattenRoutes(route.children, path, guards, middlewares));
-        }
-
-        if (!route.load && !route.children?.length) {
-            throw new Error(
-                `[Noxus] Route "${path}" has neither a load function nor children. ` +
-                `It must have at least one of them.`
-            );
-        }
-    }
-
-    return result;
-}

package/src/internal/socket.ts

@@ -1,75 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-/**
- * Centralizes MessagePort storage for renderer communication and handles
- * push-event delivery back to renderer processes.
- */
-import { Injectable } from '../decorators/injectable.decorator';
-import { Logger } from '../utils/logger';
-import { createRendererEventMessage } from './request';
-
-interface RendererChannels {
-    request: Electron.MessageChannelMain;
-    socket: Electron.MessageChannelMain;
-}
-
-@Injectable({ lifetime: 'singleton' })
-export class NoxSocket {
-    private readonly channels = new Map<number, RendererChannels>();
-
-    public register(senderId: number, requestChannel: Electron.MessageChannelMain, socketChannel: Electron.MessageChannelMain): void {
-        this.channels.set(senderId, { request: requestChannel, socket: socketChannel });
-    }
-
-    public get(senderId: number): RendererChannels | undefined {
-        return this.channels.get(senderId);
-    }
-
-    public unregister(senderId: number): void {
-        this.channels.delete(senderId);
-    }
-
-    public getSenderIds(): number[] {
-        return [...this.channels.keys()];
-    }
-
-    public emit<TPayload = unknown>(eventName: string, payload?: TPayload, targetSenderIds?: number[]): void {
-        const normalizedEvent = eventName.trim();
-
-        if(normalizedEvent.length === 0) {
-            throw new Error('Renderer event name must be a non-empty string.');
-        }
-
-        const recipients = targetSenderIds ?? this.getSenderIds();
-
-        for(const senderId of recipients) {
-            const channel = this.channels.get(senderId);
-
-            if(!channel) {
-                Logger.warn(`No message channel found for sender ID: ${senderId} while emitting "${normalizedEvent}".`);
-                continue;
-            }
-
-            try {
-                channel.socket.port1.postMessage(createRendererEventMessage(normalizedEvent, payload));
-            }
-            catch(error) {
-                Logger.error(`[Noxus] Failed to emit "${normalizedEvent}" to sender ${senderId}.`, error);
-            }
-        }
-    }
-
-    public emitToRenderer<TPayload = unknown>(senderId: number, eventName: string, payload?: TPayload): boolean {
-        if(!this.channels.has(senderId)) {
-            return false;
-        }
-
-        this.emit(eventName, payload, [senderId]);
-
-        return true;
-    }
-}