@noxfly/noxus 2.4.0 → 2.5.0

package/src/app.ts

@@ -8,6 +8,7 @@ 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";
@@ -173,6 +174,42 @@ export class NoxApp {
         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.

package/src/bootstrap.ts

@@ -4,7 +4,7 @@
  * @author NoxFly
  */
 
-import { app, BrowserWindow } from "electron/main";
+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";
@@ -38,8 +38,8 @@ export interface BootstrapOptions {
  * @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>, options?: BootstrapOptions): Promise<NoxApp> {
-    if(!getModuleMetadata(rootModule)) {
+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`);
     }
 
@@ -51,6 +51,21 @@ export async function bootstrapApplication(rootModule: Type<any>, options?: Boot
 
     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)

package/src/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from './request';
+export * from './preload-bridge';
 export * from './renderer-events';
 export * from './renderer-client';
 export type { HttpMethod, AtomicHttpMethod } from './decorators/method.decorator';

package/src/main.ts

@@ -22,12 +22,9 @@ export * from './decorators/injectable.decorator';
 export * from './decorators/inject.decorator';
 export * from './decorators/method.decorator';
 export * from './decorators/module.decorator';
-export * from './preload-bridge';
 export * from './utils/logger';
 export * from './utils/types';
 export * from './utils/forward-ref';
 export * from './request';
-export * from './renderer-events';
-export * from './renderer-client';
 export * from './socket';
 

package/src/router.ts

@@ -12,10 +12,28 @@ import { AtomicHttpMethod, getRouteMetadata } from 'src/decorators/method.decora
 import { getMiddlewaresForController, getMiddlewaresForControllerAction, IMiddleware, NextFunction } from 'src/decorators/middleware.decorator';
 import { BadRequestException, MethodNotAllowedException, NotFoundException, ResponseException, UnauthorizedException } from 'src/exceptions';
 import { IBatchRequestItem, IBatchRequestPayload, IBatchResponsePayload, IResponse, Request } from 'src/request';
+import { InjectorExplorer } from 'src/DI/injector-explorer';
 import { Logger } from 'src/utils/logger';
 import { RadixTree } from 'src/utils/radix-tree';
 import { Type } from 'src/utils/types';
 
+/**
+ * A lazy route entry maps a path prefix to a dynamic import function.
+ * The module is loaded on the first request matching the prefix.
+ */
+export interface ILazyRoute {
+    /** Path prefix (e.g. "auth", "printing"). Matched against the first segment(s) of the request path. */
+    path: string;
+    /** Dynamic import function returning the module file. */
+    loadModule: () => Promise<unknown>;
+}
+
+interface LazyRouteEntry {
+    loadModule: () => Promise<unknown>;
+    loading: Promise<void> | null;
+    loaded: boolean;
+}
+
 const ATOMIC_HTTP_METHODS: ReadonlySet<AtomicHttpMethod> = new Set<AtomicHttpMethod>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 
 function isAtomicHttpMethod(method: unknown): method is AtomicHttpMethod {
@@ -51,6 +69,7 @@ export type ControllerAction = (request: Request, response: IResponse) => any;
 export class Router {
     private readonly routes = new RadixTree<IRouteDefinition>();
     private readonly rootMiddlewares: Type<IMiddleware>[] = [];
+    private readonly lazyRoutes = new Map<string, LazyRouteEntry>();
 
     /**
      * Registers a controller class with the router.
@@ -109,6 +128,21 @@ export class Router {
         return this;
     }
 
+    /**
+     * Registers a lazy route. The module behind this route prefix will only
+     * be imported (and its controllers/services registered in DI) the first
+     * time a request targets this prefix.
+     *
+     * @param pathPrefix - Route prefix (e.g. "auth"). Matched against the first segment of the request path.
+     * @param loadModule - A function that returns a dynamic import promise.
+     */
+    public registerLazyRoute(pathPrefix: string, loadModule: () => Promise<unknown>): Router {
+        const normalized = pathPrefix.replace(/^\/+|\/+$/g, '');
+        this.lazyRoutes.set(normalized, { loadModule, loading: null, loaded: false });
+        Logger.log(`Registered lazy route prefix {${normalized}}`);
+        return this;
+    }
+
     /**
      * Defines a middleware for the root of the application.
      * This method allows you to register a middleware that will be applied to all requests
@@ -148,7 +182,7 @@ export class Router {
         let isCritical: boolean = false;
 
         try {
-            const routeDef = this.findRoute(request);
+            const routeDef = await this.findRoute(request);
             await this.resolveController(request, response, routeDef);
 
             if(response.status > 400) {
@@ -352,20 +386,79 @@ export class Router {
      * @param request - The Request object containing the method and path to search for.
      * @returns The IRouteDefinition for the matched route.
      */
-    private findRoute(request: Request): IRouteDefinition {
+    /**
+     * Attempts to find a route definition for the given request.
+     * Returns undefined instead of throwing when the route is not found,
+     * so the caller can try lazy-loading first.
+     */
+    private tryFindRoute(request: Request): IRouteDefinition | undefined {
         const matchedRoutes = this.routes.search(request.path);
 
         if(matchedRoutes?.node === undefined || matchedRoutes.node.children.length === 0) {
-            throw new NotFoundException(`No route matches ${request.method} ${request.path}`);
+            return undefined;
         }
 
         const routeDef = matchedRoutes.node.findExactChild(request.method);
+        return routeDef?.value;
+    }
+
+    /**
+     * Finds the route definition for a given request.
+     * If no eagerly-registered route matches, attempts to load a lazy module
+     * whose prefix matches the request path, then retries.
+     */
+    private async findRoute(request: Request): Promise<IRouteDefinition> {
+        // Fast path: route already registered
+        const direct = this.tryFindRoute(request);
+        if(direct) return direct;
 
-        if(routeDef?.value === undefined) {
-            throw new MethodNotAllowedException(`Method Not Allowed for ${request.method} ${request.path}`);
+        // Try lazy route loading
+        await this.tryLoadLazyRoute(request.path);
+
+        // Retry after lazy load
+        const afterLazy = this.tryFindRoute(request);
+        if(afterLazy) return afterLazy;
+
+        throw new NotFoundException(`No route matches ${request.method} ${request.path}`);
+    }
+
+    /**
+     * Given a request path, checks whether a lazy route prefix matches
+     * and triggers the dynamic import if it hasn't been loaded yet.
+     */
+    private async tryLoadLazyRoute(requestPath: string): Promise<void> {
+        const firstSegment = requestPath.replace(/^\/+/, '').split('/')[0] ?? '';
+
+        // Check exact first segment, then try multi-segment prefixes
+        for(const [prefix, entry] of this.lazyRoutes) {
+            if(entry.loaded) continue;
+
+            const normalizedPath = requestPath.replace(/^\/+/, '');
+            if(normalizedPath === prefix || normalizedPath.startsWith(prefix + '/') || firstSegment === prefix) {
+                if(!entry.loading) {
+                    entry.loading = this.loadLazyModule(prefix, entry);
+                }
+                await entry.loading;
+                return;
+            }
         }
+    }
+
+    /**
+     * Dynamically imports a lazy module and registers its decorated classes
+     * (controllers, services) in the DI container using the two-phase strategy.
+     */
+    private async loadLazyModule(prefix: string, entry: LazyRouteEntry): Promise<void> {
+        const t0 = performance.now();
+
+        InjectorExplorer.beginAccumulate();
+        await entry.loadModule();
+        InjectorExplorer.flushAccumulated();
+
+        entry.loaded = true;
 
-        return routeDef.value;
+        const t1 = performance.now();
+        Logger.info(`Lazy-loaded module for prefix {${prefix}} in ${Math.round(t1 - t0)}ms`);
     }
 
     /**