@noxfly/noxus 1.1.9 → 1.2.0

package/src/app.ts

@@ -9,6 +9,7 @@ import { Injectable } from "src/decorators/injectable.decorator";
 import { IMiddleware } from "src/decorators/middleware.decorator";
 import { inject } from "src/DI/app-injector";
 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";
@@ -30,11 +31,37 @@ export interface IApp {
  */
 @Injectable('singleton')
 export class NoxApp {
-    private readonly messagePorts = new Map<number, Electron.MessageChannelMain>();
     private app: IApp | undefined;
+    private readonly onRendererMessage = async (event: Electron.MessageEvent): Promise<void> => {
+        const { senderId, requestId, path, method, body }: IRequest = event.data;
+
+        const channel = this.socket.get(senderId);
+
+        if(!channel) {
+            Logger.error(`No message channel found for sender ID: ${senderId}`);
+            return;
+        }
+
+        try {
+            const request = new Request(event, requestId, method, path, body);
+            const response = await this.router.handle(request);
+            channel.port1.postMessage(response);
+        }
+        catch(err: any) {
+            const response: IResponse = {
+                requestId,
+                status: 500,
+                body: null,
+                error: err.message || 'Internal Server Error',
+            };
+
+            channel.port1.postMessage(response);
+        }
+    };
 
     constructor(
         private readonly router: Router,
+        private readonly socket: NoxSocket,
     ) {}
 
     /**
@@ -62,47 +89,18 @@ export class NoxApp {
     private giveTheRendererAPort(event: Electron.IpcMainInvokeEvent): void {
         const senderId = event.sender.id;
 
-        if(this.messagePorts.has(senderId)) {
+        if(this.socket.get(senderId)) {
             this.shutdownChannel(senderId);
         }
 
         const channel = new MessageChannelMain();
-        this.messagePorts.set(senderId, channel);
 
-        channel.port1.on('message', this.onRendererMessage.bind(this));
+        channel.port1.on('message', this.onRendererMessage);
         channel.port1.start();
 
-        event.sender.postMessage('port', { senderId }, [channel.port2]);
-    }
-
-    /**
-     * Electron specific message handling.
-     * Replaces HTTP calls by using Electron's IPC mechanism.
-     */
-    private async onRendererMessage(event: Electron.MessageEvent): Promise<void> {
-        const { senderId, requestId, path, method, body }: IRequest = event.data;
-
-        const channel = this.messagePorts.get(senderId);
-
-        if(!channel) {
-            Logger.error(`No message channel found for sender ID: ${senderId}`);
-            return;
-        }
-        try {
-            const request = new Request(event, requestId, method, path, body);
-            const response = await this.router.handle(request);
-            channel.port1.postMessage(response);
-        }
-        catch(err: any) {
-            const response: IResponse = {
-                requestId,
-                status: 500,
-                body: null,
-                error: err.message || 'Internal Server Error',
-            };
+        this.socket.register(senderId, channel);
 
-            channel.port1.postMessage(response);
-        }
+        event.sender.postMessage('port', { senderId }, [channel.port2]);
     }
 
     /**
@@ -122,18 +120,18 @@ export class NoxApp {
      * @param remove - Whether to remove the channel from the messagePorts map.
      */
     private shutdownChannel(channelSenderId: number): void {
-        const channel = this.messagePorts.get(channelSenderId);
+        const channel = this.socket.get(channelSenderId);
 
         if(!channel) {
             Logger.warn(`No message channel found for sender ID: ${channelSenderId}`);
             return;
         }
 
-        channel.port1.off('message', this.onRendererMessage.bind(this));
+        channel.port1.off('message', this.onRendererMessage);
         channel.port1.close();
         channel.port2.close();
 
-        this.messagePorts.delete(channelSenderId);
+        this.socket.unregister(channelSenderId);
     }
 
     /**
@@ -141,11 +139,9 @@ export class NoxApp {
      * This method is called when all windows are closed, and it cleans up the message channels
      */
     private async onAllWindowsClosed(): Promise<void> {
-        this.messagePorts.forEach((channel, senderId) => {
+        for(const senderId of this.socket.getSenderIds()) {
             this.shutdownChannel(senderId);
-        });
-
-        this.messagePorts.clear();
+        }
 
         Logger.info('All windows closed, shutting down application...');
         await this.app?.dispose();

package/src/decorators/method.decorator.ts

@@ -23,7 +23,12 @@ export interface IRouteMetadata {
 /**
  * The different HTTP methods that can be used in the application.
  */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'BATCH';
+
+/**
+ * Atomic HTTP verbs supported by controllers. BATCH is handled at the router level only.
+ */
+export type AtomicHttpMethod = Exclude<HttpMethod, 'BATCH'>;
 
 /**
  * The configuration that waits a route's decorator.

package/src/index.ts

@@ -4,17 +4,5 @@
  * @author NoxFly
  */
 
-export * from './DI/app-injector';
-export * from './router';
-export * from './app';
-export * from './bootstrap';
-export * from './exceptions';
-export * from './decorators/middleware.decorator';
-export * from './decorators/guards.decorator';
-export * from './decorators/controller.decorator';
-export * from './decorators/injectable.decorator';
-export * from './decorators/method.decorator';
-export * from './decorators/module.decorator';
-export * from './utils/logger';
-export * from './utils/types';
 export * from './request';
+export * from './renderer-events';

package/src/main.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+/**
+ * Entry point for Electron main-process consumers.
+ */
+export * from './DI/app-injector';
+export * from './router';
+export * from './app';
+export * from './bootstrap';
+export * from './exceptions';
+export * from './decorators/middleware.decorator';
+export * from './decorators/guards.decorator';
+export * from './decorators/controller.decorator';
+export * from './decorators/injectable.decorator';
+export * from './decorators/method.decorator';
+export * from './decorators/module.decorator';
+export * from './utils/logger';
+export * from './utils/types';
+export * from './request';
+export * from './renderer-events';
+export * from './socket';

package/src/renderer-events.ts

@@ -0,0 +1,110 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+/**
+ * Lightweight event registry to help renderer processes subscribe to
+ * push messages sent by the main process through Noxus.
+ */
+import { IRendererEventMessage, isRendererEventMessage } from 'src/request';
+
+export type RendererEventHandler<TPayload = unknown> = (payload: TPayload) => void;
+
+export interface RendererEventSubscription {
+    unsubscribe(): void;
+}
+
+export class RendererEventRegistry {
+    private readonly listeners = new Map<string, Set<RendererEventHandler>>();
+
+    /**
+     *
+     */
+    public subscribe<TPayload>(eventName: string, handler: RendererEventHandler<TPayload>): RendererEventSubscription {
+        const normalizedEventName = eventName.trim();
+
+        if(normalizedEventName.length === 0) {
+            throw new Error('Renderer event name must be a non-empty string.');
+        }
+
+        const handlers = this.listeners.get(normalizedEventName) ?? new Set<RendererEventHandler>();
+
+        handlers.add(handler as RendererEventHandler);
+        this.listeners.set(normalizedEventName, handlers);
+
+        return {
+            unsubscribe: () => this.unsubscribe(normalizedEventName, handler as RendererEventHandler),
+        };
+    }
+
+    /**
+     *
+     */
+    public unsubscribe<TPayload>(eventName: string, handler: RendererEventHandler<TPayload>): void {
+        const handlers = this.listeners.get(eventName);
+
+        if(!handlers) {
+            return;
+        }
+
+        handlers.delete(handler as RendererEventHandler);
+
+        if(handlers.size === 0) {
+            this.listeners.delete(eventName);
+        }
+    }
+
+    /**
+     *
+     */
+    public clear(eventName?: string): void {
+        if(eventName) {
+            this.listeners.delete(eventName);
+            return;
+        }
+
+        this.listeners.clear();
+    }
+
+    /**
+     *
+     */
+    public dispatch<TPayload>(message: IRendererEventMessage<TPayload>): void {
+        const handlers = this.listeners.get(message.event);
+
+        if(!handlers || handlers.size === 0) {
+            return;
+        }
+
+        handlers.forEach((handler) => {
+            try {
+                handler(message.payload as TPayload);
+            }
+            catch(error) {
+                console.error(`[Noxus] Renderer event handler for "${message.event}" threw an error.`, error);
+            }
+        });
+    }
+
+    /**
+     *
+     */
+    public tryDispatchFromMessageEvent(event: MessageEvent): boolean {
+        if(!isRendererEventMessage(event.data)) {
+            return false;
+        }
+
+        this.dispatch(event.data);
+        return true;
+    }
+
+    /**
+     *
+     */
+    public hasHandlers(eventName: string): boolean {
+        const handlers = this.listeners.get(eventName);
+        return !!handlers && handlers.size > 0;
+    }
+}

package/src/request.ts

@@ -5,7 +5,7 @@
  */
 
 import 'reflect-metadata';
-import { HttpMethod } from 'src/decorators/method.decorator';
+import { AtomicHttpMethod, HttpMethod } from 'src/decorators/method.decorator';
 import { AppInjector, RootInjector } from 'src/DI/app-injector';
 
 /**
@@ -34,22 +34,63 @@ export class Request {
  * It includes properties for the sender ID, request ID, path, method, and an optional body.
  * This interface is used to standardize the request data across the application.
  */
-export interface IRequest<T = any> {
+export interface IRequest<TBody = unknown> {
     senderId: number;
     requestId: string;
     path: string;
     method: HttpMethod;
-    body?: T;
+    body?: TBody;
+}
+
+export interface IBatchRequestItem<TBody = unknown> {
+    requestId?: string;
+    path: string;
+    method: AtomicHttpMethod;
+    body?: TBody;
+}
+
+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<T = any> {
+export interface IResponse<TBody = unknown> {
     requestId: string;
     status: number;
-    body?: T;
+    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/router.ts

@@ -8,14 +8,20 @@ import 'reflect-metadata';
 import { getControllerMetadata } from 'src/decorators/controller.decorator';
 import { getGuardForController, getGuardForControllerAction, IGuard } from 'src/decorators/guards.decorator';
 import { Injectable } from 'src/decorators/injectable.decorator';
-import { getRouteMetadata } from 'src/decorators/method.decorator';
+import { AtomicHttpMethod, getRouteMetadata } from 'src/decorators/method.decorator';
 import { getMiddlewaresForController, getMiddlewaresForControllerAction, IMiddleware, NextFunction } from 'src/decorators/middleware.decorator';
-import { MethodNotAllowedException, NotFoundException, ResponseException, UnauthorizedException } from 'src/exceptions';
-import { IResponse, Request } from 'src/request';
+import { BadRequestException, MethodNotAllowedException, NotFoundException, ResponseException, UnauthorizedException } from 'src/exceptions';
+import { IBatchRequestItem, IBatchRequestPayload, IBatchResponsePayload, IResponse, Request } from 'src/request';
 import { Logger } from 'src/utils/logger';
 import { RadixTree } from 'src/utils/radix-tree';
 import { Type } from 'src/utils/types';
 
+const ATOMIC_HTTP_METHODS: ReadonlySet<AtomicHttpMethod> = new Set<AtomicHttpMethod>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+
+function isAtomicHttpMethod(method: unknown): method is AtomicHttpMethod {
+    return typeof method === 'string' && ATOMIC_HTTP_METHODS.has(method as AtomicHttpMethod);
+}
+
 /**
  * IRouteDefinition interface defines the structure of a route in the application.
  * It includes the HTTP method, path, controller class, handler method name,
@@ -121,6 +127,14 @@ export class Router {
      * @param channelSenderId - The ID of the sender channel to shut down.
      */
     public async handle(request: Request): Promise<IResponse> {
+        if(request.method === 'BATCH') {
+            return this.handleBatch(request);
+        }
+
+        return this.handleAtomic(request);
+    }
+
+    private async handleAtomic(request: Request): Promise<IResponse> {
         Logger.comment(`>     ${request.method} /${request.path}`);
 
         const t0 = performance.now();
@@ -182,6 +196,122 @@ export class Router {
         }
     }
 
+    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: [] },
+        };
+
+        try {
+            const payload = this.normalizeBatchPayload(request.body);
+            const batchResponses: IResponse[] = [];
+
+            for(const [index, item] of payload.requests.entries()) {
+                const subRequestId = item.requestId ?? `${request.id}:${index}`;
+                const atomicRequest = new Request(request.event, subRequestId, item.method, item.path, item.body);
+                batchResponses.push(await this.handleAtomic(atomicRequest));
+            }
+
+            response.body!.responses = batchResponses;
+        }
+        catch(error: unknown) {
+            response.body = undefined;
+
+            if(error instanceof ResponseException) {
+                response.status = error.status;
+                response.error = error.message;
+                response.stack = error.stack;
+            }
+            else if(error instanceof Error) {
+                response.status = 500;
+                response.error = error.message || 'Internal Server Error';
+                response.stack = error.stack || 'No stack trace available';
+            }
+            else {
+                response.status = 500;
+                response.error = 'Unknown error occurred';
+                response.stack = 'No stack trace available';
+            }
+        }
+        finally {
+            const t1 = performance.now();
+
+            const message = `< ${response.status} ${request.method} /${request.path} ${Logger.colors.yellow}${Math.round(t1 - t0)}ms${Logger.colors.initial}`;
+
+            if(response.status < 400)
+                Logger.log(message);
+            else if(response.status < 500)
+                Logger.warn(message);
+            else
+                Logger.error(message);
+
+            if(response.error !== undefined) {
+                Logger.error(response.error);
+
+                if(response.stack !== undefined) {
+                    Logger.errorStack(response.stack);
+                }
+            }
+
+            return response;
+        }
+    }
+
+    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 possiblePayload = body as Partial<IBatchRequestPayload>;
+        const { requests } = possiblePayload;
+
+        if(!Array.isArray(requests)) {
+            throw new BadRequestException('Batch payload must define a requests array.');
+        }
+
+        const normalizedRequests = requests.map((entry, index) => this.normalizeBatchItem(entry, index));
+
+        return { requests: normalizedRequests };
+    }
+
+    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 === 0) {
+            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 normalizedMethod = method.toUpperCase();
+
+        if(!isAtomicHttpMethod(normalizedMethod)) {
+            throw new BadRequestException(`Batch request at index ${index} uses the unsupported method ${method}.`);
+        }
+
+        return {
+            requestId,
+            path,
+            method: normalizedMethod as AtomicHttpMethod,
+            body,
+        };
+    }
+
     /**
      * Finds the route definition for a given request.
      * This method searches the routing tree for a matching route based on the request's path and method.

package/src/socket.ts

@@ -0,0 +1,68 @@
+/**
+ * @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 'src/decorators/injectable.decorator';
+import { createRendererEventMessage } from 'src/request';
+import { Logger } from 'src/utils/logger';
+
+@Injectable('singleton')
+export class NoxSocket {
+    private readonly messagePorts = new Map<number, Electron.MessageChannelMain>();
+
+    public register(senderId: number, channel: Electron.MessageChannelMain): void {
+        this.messagePorts.set(senderId, channel);
+    }
+
+    public get(senderId: number): Electron.MessageChannelMain | undefined {
+        return this.messagePorts.get(senderId);
+    }
+
+    public unregister(senderId: number): void {
+        this.messagePorts.delete(senderId);
+    }
+
+    public getSenderIds(): number[] {
+        return [...this.messagePorts.keys()];
+    }
+
+    public emit<TPayload = unknown>(eventName: string, payload?: TPayload, targetSenderIds?: number[]): number {
+        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();
+        let delivered = 0;
+
+        for(const senderId of recipients) {
+            const channel = this.messagePorts.get(senderId);
+
+            if(!channel) {
+                Logger.warn(`No message channel found for sender ID: ${senderId} while emitting "${normalizedEvent}".`);
+                continue;
+            }
+
+            try {
+                channel.port1.postMessage(createRendererEventMessage(normalizedEvent, payload));
+                delivered++;
+            }
+            catch(error) {
+                Logger.error(`[Noxus] Failed to emit "${normalizedEvent}" to sender ${senderId}.`, error);
+            }
+        }
+
+        return delivered;
+    }
+
+    public emitToRenderer<TPayload = unknown>(senderId: number, eventName: string, payload?: TPayload): boolean {
+        return this.emit(eventName, payload, [senderId]) > 0;
+    }
+}

package/tsup.config.ts

@@ -10,7 +10,8 @@ const copyrights = `
 
 export default defineConfig({
     entry: {
-        noxus: "src/index.ts"
+        renderer: "src/index.ts",
+        main: "src/main.ts",
     },
     keepNames: true,
     minifyIdentifiers: false,