@noxfly/noxus 2.3.2 → 2.5.0

package/src/DI/injector-explorer.ts

@@ -13,31 +13,141 @@ import { Router } from "src/router";
 import { Logger } from "src/utils/logger";
 import { Type } from "src/utils/types";
 
+interface PendingRegistration {
+    target: Type<unknown>;
+    lifetime: Lifetime;
+}
+
 /**
  * InjectorExplorer is a utility class that explores the dependency injection system at the startup.
+ * It collects decorated classes during the import phase and defers their actual registration
+ * and resolution to when {@link processPending} is called by bootstrapApplication.
  */
 export class InjectorExplorer {
+    private static readonly pending: PendingRegistration[] = [];
+    private static processed = false;
+    private static accumulating = false;
+
+    /**
+     * Enqueues a class for deferred registration.
+     * Called by the @Injectable decorator at import time.
+     *
+     * If {@link processPending} has already been called (i.e. after bootstrap)
+     * and accumulation mode is not active, the class is registered immediately
+     * so that late dynamic imports (e.g. middlewares loaded after bootstrap)
+     * work correctly.
+     *
+     * When accumulation mode is active (between {@link beginAccumulate} and
+     * {@link flushAccumulated}), classes are queued instead — preserving the
+     * two-phase binding/resolution guarantee for lazy-loaded modules.
+     */
+    public static enqueue(target: Type<unknown>, lifetime: Lifetime): void {
+        if(InjectorExplorer.processed && !InjectorExplorer.accumulating) {
+            InjectorExplorer.registerImmediate(target, lifetime);
+            return;
+        }
+
+        InjectorExplorer.pending.push({ target, lifetime });
+    }
+
+    /**
+     * Enters accumulation mode. While active, all decorated classes discovered
+     * via dynamic imports are queued in {@link pending} rather than registered
+     * immediately. Call {@link flushAccumulated} to process them with the
+     * full two-phase (bind-then-resolve) guarantee.
+     */
+    public static beginAccumulate(): void {
+        InjectorExplorer.accumulating = true;
+    }
+
+    /**
+     * Exits accumulation mode and processes every class queued since
+     * {@link beginAccumulate} was called. Uses the same two-phase strategy
+     * as {@link processPending} (register all bindings first, then resolve
+     * singletons / controllers) so import ordering within a lazy batch
+     * does not cause resolution failures.
+     */
+    public static flushAccumulated(): void {
+        InjectorExplorer.accumulating = false;
+
+        const queue = [...InjectorExplorer.pending];
+        InjectorExplorer.pending.length = 0;
+
+        // Phase 1: register all bindings without instantiation
+        for(const { target, lifetime } of queue) {
+            if(!RootInjector.bindings.has(target)) {
+                RootInjector.bindings.set(target, {
+                    implementation: target,
+                    lifetime
+                });
+            }
+        }
+
+        // Phase 2: resolve singletons, register controllers, log modules
+        for(const { target, lifetime } of queue) {
+            InjectorExplorer.processRegistration(target, lifetime);
+        }
+    }
+
     /**
-     * Registers the class as injectable.
-     * When a class is instantiated, if it has dependencies and those dependencies
-     * are listed using this method, they will be injected into the class constructor.
+     * Processes all pending registrations in two phases:
+     * 1. Register all bindings (no instantiation) so every dependency is known.
+     * 2. Resolve singletons, register controllers and log module readiness.
+     *
+     * This two-phase approach makes the system resilient to import ordering:
+     * all bindings exist before any singleton is instantiated.
      */
-    public static register(target: Type<unknown>, lifetime: Lifetime): typeof RootInjector {
-        if(RootInjector.bindings.has(target)) // already registered
-            return RootInjector;
+    public static processPending(): void {
+        const queue = InjectorExplorer.pending;
+
+        // Phase 1: register all bindings without instantiation
+        for(const { target, lifetime } of queue) {
+            if(!RootInjector.bindings.has(target)) {
+                RootInjector.bindings.set(target, {
+                    implementation: target,
+                    lifetime
+                });
+            }
+        }
+
+        // Phase 2: resolve singletons, register controllers, log modules
+        for(const { target, lifetime } of queue) {
+            InjectorExplorer.processRegistration(target, lifetime);
+        }
+
+        queue.length = 0;
+        InjectorExplorer.processed = true;
+    }
+
+    /**
+     * Registers a single class immediately (post-bootstrap path).
+     * Used for classes discovered via late dynamic imports.
+     */
+    private static registerImmediate(target: Type<unknown>, lifetime: Lifetime): void {
+        if(RootInjector.bindings.has(target)) {
+            return;
+        }
 
         RootInjector.bindings.set(target, {
             implementation: target,
             lifetime
         });
 
+        InjectorExplorer.processRegistration(target, lifetime);
+    }
+
+    /**
+     * Performs phase-2 work for a single registration: resolve singletons,
+     * register controllers, and log module readiness.
+     */
+    private static processRegistration(target: Type<unknown>, lifetime: Lifetime): void {
         if(lifetime === 'singleton') {
             RootInjector.resolve(target);
         }
 
         if(getModuleMetadata(target)) {
             Logger.log(`${target.name} dependencies initialized`);
-            return RootInjector;
+            return;
         }
 
         const controllerMeta = getControllerMetadata(target);
@@ -45,20 +155,15 @@ export class InjectorExplorer {
         if(controllerMeta) {
             const router = RootInjector.resolve(Router);
             router?.registerController(target);
-            return RootInjector;
+            return;
         }
 
-        const routeMeta = getRouteMetadata(target);
-
-        if(routeMeta) {
-            return RootInjector;
+        if(getRouteMetadata(target).length > 0) {
+            return;
         }
 
         if(getInjectableMetadata(target)) {
             Logger.log(`Registered ${target.name} as ${lifetime}`);
-            return RootInjector;
         }
-
-        return RootInjector;
     }
 }

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";
@@ -21,7 +22,7 @@ import { Type } from "src/utils/types";
  */
 export interface IApp {
     dispose(): Promise<void>;
-    onReady(): Promise<void>;
+    onReady(mainWindow?: BrowserWindow): Promise<void>;
     onActivated(): Promise<void>;
 }
 
@@ -32,6 +33,7 @@ export interface IApp {
 @Injectable('singleton')
 export class NoxApp {
     private app: IApp | undefined;
+    private mainWindow: BrowserWindow | undefined;
 
     /**
      *
@@ -163,6 +165,51 @@ export class NoxApp {
 
     // ---
 
+    /**
+     * 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.
@@ -187,10 +234,11 @@ export class NoxApp {
 
     /**
      * 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.app?.onReady(this.mainWindow);
         return this;
     }
 }

package/src/bootstrap.ts

@@ -4,29 +4,79 @@
  * @author NoxFly
  */
 
-import { app } 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";
+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>): 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`);
     }
 
     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/injectable.decorator.ts

@@ -23,6 +23,6 @@ export function Injectable(lifetime: Lifetime = "scope"): ClassDecorator {
             throw new Error(`@Injectable can only be used on classes, not on ${typeof target}`);
         }
         defineInjectableMetadata(target, lifetime);
-        InjectorExplorer.register(target as unknown as Type<any>, lifetime);
+        InjectorExplorer.enqueue(target as unknown as Type<any>, lifetime);
     };
 }

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`);
     }
 
     /**