@noxfly/noxus 2.5.0 → 3.0.0-dev.1

package/src/internal/app.ts

@@ -0,0 +1,217 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { app, BrowserWindow, ipcMain, MessageChannelMain } from 'electron/main';
+import { Guard } from "src/main";
+import { Injectable } from '../decorators/injectable.decorator';
+import { Middleware } from '../decorators/middleware.decorator';
+import { inject } from '../DI/app-injector';
+import { InjectorExplorer } from '../DI/injector-explorer';
+import { Logger } from '../utils/logger';
+import { Type } from '../utils/types';
+import { WindowManager } from '../window/window-manager';
+import { IResponse, Request } from './request';
+import { Router } from './router';
+import { NoxSocket } from './socket';
+
+/**
+ * Your application service should implement IApp.
+ * Noxus calls these lifecycle methods at the appropriate time.
+ *
+ * Unlike v2, IApp no longer receives a BrowserWindow in onReady.
+ * Use the injected WindowManager instead — it is more flexible and
+ * does not couple the lifecycle to a single pre-created window.
+ *
+ * @example
+ * @Injectable({ lifetime: 'singleton', deps: [WindowManager, MyService] })
+ * class AppService implements IApp {
+ *   constructor(private wm: WindowManager, private svc: MyService) {}
+ *
+ *   async onReady() {
+ *     const win = await this.wm.createSplash({ webPreferences: { preload: ... } });
+ *     win.loadFile('index.html');
+ *   }
+ *
+ *   async onActivated() { ... }
+ *   async dispose() { ... }
+ * }
+ */
+export interface IApp {
+    dispose(): Promise<void>;
+    onReady(): Promise<void>;
+    onActivated(): Promise<void>;
+}
+
+@Injectable({ lifetime: 'singleton', deps: [Router, NoxSocket, WindowManager] })
+export class NoxApp {
+    private appService: IApp | undefined;
+
+    private readonly router = inject(Router);
+    private readonly socket = inject(NoxSocket);
+    public readonly windowManager = inject(WindowManager);
+
+    // -------------------------------------------------------------------------
+    // Initialisation
+    // -------------------------------------------------------------------------
+
+    public async init(): Promise<this> {
+        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('');
+        return this;
+    }
+
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+
+    /**
+     * Registers a lazy route. The file behind this prefix is dynamically
+     * imported on the first IPC request that targets it.
+     *
+     * The import function should NOT statically reference heavy modules —
+     * the whole point is to defer their loading.
+     *
+     * @example
+     * noxApp.lazy('auth', () => import('./modules/auth/auth.controller.js'));
+     * noxApp.lazy('reporting', () => import('./modules/reporting/index.js'));
+     */
+    public lazy(
+        pathPrefix: string,
+        load: () => Promise<unknown>,
+        guards: Guard[] = [],
+        middlewares: Middleware[] = [],
+    ): this {
+        this.router.registerLazyRoute(pathPrefix, load, guards, middlewares);
+        return this;
+    }
+
+    /**
+     * Eagerly loads a set of modules (controllers + services) before start().
+     * Use this for modules that provide services needed by your IApp.onReady().
+     *
+     * All imports run in parallel; DI is flushed with the two-phase guarantee.
+     */
+    public async load(importFns: Array<() => Promise<unknown>>): Promise<this> {
+        InjectorExplorer.beginAccumulate();
+        await Promise.all(importFns.map((fn) => fn()));
+        InjectorExplorer.flushAccumulated();
+        return this;
+    }
+
+    /**
+     * Registers a global middleware applied to every route.
+     */
+    public use(middleware: Middleware): this {
+        this.router.defineRootMiddleware(middleware);
+        return this;
+    }
+
+    /**
+     * Sets the application service (implements IApp) that receives lifecycle events.
+     * @param appClass - Class decorated with @Injectable that implements IApp.
+     */
+    public configure(appClass: Type<IApp>): this {
+        this.appService = inject(appClass);
+        return this;
+    }
+
+    /**
+     * Calls IApp.onReady(). Should be called after configure() and any lazy()
+     * registrations are set up.
+     */
+    public start(): this {
+        this.appService?.onReady();
+        return this;
+    }
+
+    // -------------------------------------------------------------------------
+    // IPC
+    // -------------------------------------------------------------------------
+
+    private readonly onRendererMessage = async (event: Electron.MessageEvent): Promise<void> => {
+        const { senderId, requestId, path, method, body }: import('./request').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: unknown) {
+            const response: IResponse = {
+                requestId,
+                status: 500,
+                body: null,
+                error: err instanceof Error ? err.message : 'Internal Server Error',
+            };
+            channels.request.port1.postMessage(response);
+        }
+    };
+
+    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();
+
+        event.sender.once('destroyed', () => this.shutdownChannel(senderId));
+
+        this.socket.register(senderId, requestChannel, socketChannel);
+        event.sender.postMessage('port', { senderId }, [requestChannel.port2, socketChannel.port2]);
+    }
+
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+
+    private onAppActivated(): void {
+        if (process.platform === 'darwin' && BrowserWindow.getAllWindows().length === 0) {
+            this.appService?.onActivated();
+        }
+    }
+
+    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.appService?.dispose();
+
+        if (process.platform !== 'darwin') app.quit();
+    }
+
+    private shutdownChannel(channelSenderId: number): void {
+        const channels = this.socket.get(channelSenderId);
+
+        if (!channels) {
+            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);
+    }
+}

package/src/internal/bootstrap.ts

@@ -0,0 +1,108 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { app } from 'electron/main';
+import { inject, RootInjector } from '../DI/app-injector';
+import { InjectorExplorer } from '../DI/injector-explorer';
+import { TokenKey } from '../DI/token';
+import { NoxApp } from './app';
+import { RouteDefinition } from "./routes";
+
+/**
+ * A singleton value override: provides an already-constructed instance
+ * for a given token, bypassing the DI factory.
+ *
+ * Useful for injecting external singletons (e.g. a database connection,
+ * a logger already configured, a third-party SDK wrapper) that cannot
+ * or should not be constructed by the DI container.
+ *
+ * @example
+ * { token: MikroORM, useValue: await MikroORM.init(config) }
+ * { token: DB_URL,   useValue: process.env.DATABASE_URL }
+ */
+export interface SingletonOverride<T = unknown> {
+    token: TokenKey<T>;
+    useValue: T;
+}
+
+/**
+ * Configuration object for bootstrapApplication.
+ */
+export interface BootstrapConfig {
+    /**
+     * Application routing table, produced by defineRoutes().
+     * All lazy routes are registered before the app starts.
+     */
+    routes?: RouteDefinition[];
+
+    /**
+     * Pre-built singleton instances to inject into the DI container
+     * before the application starts.
+     *
+     * This replaces the v2 module/provider declaration pattern for
+     * external singletons.
+     *
+     * @example
+     * singletons: [
+     *   { token: MikroORM, useValue: await MikroORM.init(ormConfig) },
+     *   { token: DB_URL,   useValue: process.env.DATABASE_URL! },
+     * ]
+     */
+    singletons?: SingletonOverride[];
+
+    /**
+     * Controllers and services to eagerly load before NoxApp.start() is called.
+     * Each entry is a dynamic import function — files are imported in parallel.
+     *
+     * Use this only for things needed at startup (e.g. if your IApp service
+     * depends on a service in an otherwise lazy module).
+     *
+     * Everything else should be registered via noxApp.lazy().
+     *
+     * @example
+     * eagerLoad: [
+     *   () => import('./modules/auth/auth.controller.js'),
+     * ]
+     */
+    eagerLoad?: Array<() => Promise<unknown>>;
+}
+
+/**
+ * Bootstraps the Noxus application.
+ */
+export async function bootstrapApplication(config: BootstrapConfig = {}): Promise<NoxApp> {
+    await app.whenReady();
+
+    // Build override map for the DI flush phase
+    const overrides = new Map<TokenKey, unknown>();
+    for (const { token, useValue } of config.singletons ?? []) {
+        overrides.set(token, useValue);
+        // Pre-register the binding so the injector knows the token exists
+        RootInjector.singletons.set(token as any, useValue);
+    }
+
+    // Flush all classes enqueued by decorators at import time (two-phase)
+    InjectorExplorer.processPending(overrides);
+
+    // Resolve core framework singletons
+    const noxApp = inject(NoxApp);
+
+    // Register routes from the routing table
+    if (config.routes?.length) {
+        for (const route of config.routes) {
+            noxApp.lazy(route.path, route.load, route.guards, route.middlewares);
+        }
+    }
+
+    // Eagerly load optional modules
+    if (config.eagerLoad?.length) {
+        await noxApp.load(config.eagerLoad);
+    }
+
+    await noxApp.init();
+
+    return noxApp;
+}

package/src/{preload-bridge.ts → internal/preload-bridge.ts}

@@ -5,7 +5,7 @@
  */
 
 import { contextBridge, ipcRenderer } from 'electron/renderer';
-import type { IPortRequester } from 'src/renderer-client';
+import type { IPortRequester } from './renderer-client';
 
 export interface NoxusPreloadAPI extends IPortRequester {}
 

package/src/{renderer-client.ts → internal/renderer-client.ts}

@@ -4,8 +4,8 @@
  * @author NoxFly
  */
 
-import { IBatchRequestItem, IBatchResponsePayload, IRequest, IResponse } from 'src/request';
-import { RendererEventRegistry } from 'src/renderer-events';
+import { IBatchRequestItem, IBatchResponsePayload, IRequest, IResponse } from './request';
+import { RendererEventRegistry } from './renderer-events';
 
 export interface IPortRequester {
     requestPort(): void;

package/src/{renderer-events.ts → internal/renderer-events.ts}

@@ -8,7 +8,7 @@
  * Lightweight event registry to help renderer processes subscribe to
  * push messages sent by the main process through Noxus.
  */
-import { IRendererEventMessage, isRendererEventMessage } from 'src/request';
+import { IRendererEventMessage, isRendererEventMessage } from './request';
 
 export type RendererEventHandler<TPayload = unknown> = (payload: TPayload) => void;
 

package/src/{request.ts → internal/request.ts}

@@ -4,9 +4,9 @@
  * @author NoxFly
  */
 
-import 'reflect-metadata';
-import { AtomicHttpMethod, HttpMethod } from 'src/decorators/method.decorator';
-import { AppInjector, RootInjector } from 'src/DI/app-injector';
+
+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.