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

package/src/internal/renderer-client.ts

@@ -17,6 +17,15 @@ export interface RendererClientOptions {
     initMessageType?: string;
     windowRef?: Window;
     generateRequestId?: () => string;
+    /**
+     * Timeout in milliseconds for IPC requests.
+     * If the main process does not respond within this duration,
+     * the request Promise is rejected and the pending entry cleaned up.
+     * Defaults to 10 000 ms. Set to 0 to disable.
+     */
+    requestTimeout?: number;
+    /** @default true */
+    enableLogging?: boolean;
 }
 
 interface PendingRequest<T = unknown> {
@@ -24,6 +33,7 @@ interface PendingRequest<T = unknown> {
     reject: (reason: IResponse<T>) => void;
     request: IRequest;
     submittedAt: number;
+    timer?: ReturnType<typeof setTimeout>;
 }
 
 const DEFAULT_INIT_EVENT = 'init-port';
@@ -97,18 +107,23 @@ export class NoxRendererClient {
     private readonly initMessageType: string;
     private readonly windowRef: Window;
     private readonly generateRequestId: () => string;
+    private readonly requestTimeout: number;
 
     private isReady = false;
     private setupPromise: Promise<void> | undefined;
     private setupResolve: (() => void) | undefined;
     private setupReject: ((reason: Error) => void) | undefined;
 
+    private enableLogging: boolean;
+
     constructor(options: RendererClientOptions = {}) {
         this.windowRef = options.windowRef ?? window;
         const resolvedBridge = options.bridge ?? resolveBridgeFromWindow(this.windowRef, options.bridgeName);
         this.bridge = resolvedBridge ?? null;
         this.initMessageType = options.initMessageType ?? DEFAULT_INIT_EVENT;
         this.generateRequestId = options.generateRequestId ?? defaultRequestId;
+        this.requestTimeout = options.requestTimeout ?? 10_000;
+        this.enableLogging = options.enableLogging ?? true;
     }
 
     public async setup(): Promise<void> {
@@ -146,6 +161,12 @@ export class NoxRendererClient {
         this.senderId = undefined;
         this.isReady = false;
 
+        for(const pending of this.pendingRequests.values()) {
+            if(pending.timer !== undefined) {
+                clearTimeout(pending.timer);
+            }
+        }
+
         this.pendingRequests.clear();
     }
 
@@ -177,6 +198,13 @@ export class NoxRendererClient {
                 submittedAt: Date.now(),
             };
 
+            if(this.requestTimeout > 0) {
+                pending.timer = setTimeout(() => {
+                    this.pendingRequests.delete(message.requestId);
+                    reject(this.createErrorResponse<TResponse>(message.requestId, `Request timed out after ${this.requestTimeout}ms`) as IResponse<TResponse>);
+                }, this.requestTimeout);
+            }
+
             this.pendingRequests.set(message.requestId, pending as PendingRequest);
 
             this.requestPort!.postMessage(message);
@@ -260,6 +288,10 @@ export class NoxRendererClient {
             return;
         }
 
+        if(pending.timer !== undefined) {
+            clearTimeout(pending.timer);
+        }
+
         this.pendingRequests.delete(response.requestId);
 
         this.onRequestCompleted(pending, response);
@@ -273,6 +305,10 @@ export class NoxRendererClient {
     };
 
     protected onRequestCompleted(pending: PendingRequest, response: IResponse): void {
+        if(!this.enableLogging) {
+            return;
+        }
+
         if(typeof console.groupCollapsed === 'function') {
             console.groupCollapsed(`${response.status} ${pending.request.method} /${pending.request.path}`);
         }

package/src/internal/request.ts

@@ -17,6 +17,7 @@ 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,
@@ -24,9 +25,11 @@ export class Request {
         public readonly id: string,
         public readonly method: HttpMethod,
         public readonly path: string,
-        public readonly body: any,
+        public readonly body: unknown,
+        query?: Record<string, string>,
     ) {
         this.path = path.replace(/^\/|\/$/g, '');
+        this.query = query ?? {};
     }
 }
 
@@ -41,6 +44,7 @@ export interface IRequest<TBody = unknown> {
     path: string;
     method: HttpMethod;
     body?: TBody;
+    query?: Record<string, string>;
 }
 
 export interface IBatchRequestItem<TBody = unknown> {
@@ -48,6 +52,7 @@ export interface IBatchRequestItem<TBody = unknown> {
     path: string;
     method: AtomicHttpMethod;
     body?: TBody;
+    query?: Record<string, string>;
 }
 
 export interface IBatchRequestPayload {

package/src/internal/router.ts

@@ -119,6 +119,18 @@ export class Router {
         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
     // -------------------------------------------------------------------------
@@ -167,7 +179,7 @@ export class Router {
             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));
+                    return this.handleAtomic(new Request(request.event, request.senderId, id, item.method, item.path, item.body, item.query));
                 }),
             );
         }
@@ -225,7 +237,7 @@ export class Router {
         entry.loading = null;
         entry.load = null;
 
-        InjectorExplorer.flushAccumulated(entry.guards, entry.middlewares, prefix);
+        await InjectorExplorer.flushAccumulated(entry.guards, entry.middlewares, prefix);
 
         entry.loaded = true;
 

package/src/internal/routes.ts

@@ -21,10 +21,12 @@ export interface RouteDefinition {
      * 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>;
+    load?: () => Promise<unknown>;
 
     /**
      * Guards applied to every action in this controller.
@@ -37,6 +39,12 @@ export interface RouteDefinition {
      * Merged with action-level middlewares.
      */
     middlewares?: Middleware[];
+
+    /**
+     * Nested child routes. Guards and middlewares declared here are
+     * inherited (merged) by all children.
+     */
+    children?: RouteDefinition[];
 }
 
 /**
@@ -46,6 +54,9 @@ export interface RouteDefinition {
  * 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([
  *     {
@@ -54,25 +65,78 @@ export interface RouteDefinition {
  *         guards: [authGuard],
  *     },
  *     {
- *         path: 'orders',
- *         load: () => import('./modules/orders/orders.controller'),
- *         guards: [authGuard],
- *         middlewares: [logMiddleware],
+ *         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 paths = routes.map(r => r.path.replace(/^\/+|\/+$/g, ''));
-    const duplicates = paths.filter((p, i) => paths.indexOf(p) !== i);
+    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(', ')}`
         );
     }
 
-    return routes.map(r => ({
-        ...r,
-        path: r.path.replace(/^\/+|\/+$/g, ''),
-    }));
+    // 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

@@ -37,7 +37,7 @@ export class NoxSocket {
         return [...this.channels.keys()];
     }
 
-    public emit<TPayload = unknown>(eventName: string, payload?: TPayload, targetSenderIds?: number[]): number {
+    public emit<TPayload = unknown>(eventName: string, payload?: TPayload, targetSenderIds?: number[]): void {
         const normalizedEvent = eventName.trim();
 
         if(normalizedEvent.length === 0) {
@@ -45,7 +45,6 @@ export class NoxSocket {
         }
 
         const recipients = targetSenderIds ?? this.getSenderIds();
-        let delivered = 0;
 
         for(const senderId of recipients) {
             const channel = this.channels.get(senderId);
@@ -57,17 +56,20 @@ export class NoxSocket {
 
             try {
                 channel.socket.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;
+        if(!this.channels.has(senderId)) {
+            return false;
+        }
+
+        this.emit(eventName, payload, [senderId]);
+
+        return true;
     }
 }

package/src/utils/radix-tree.ts

@@ -132,6 +132,31 @@ export class RadixTree<T> {
         return this.searchRecursive(this.root, segments, {});
     }
 
+    /**
+     * Collects all values in the subtree rooted at the given node.
+     * This method traverses the subtree starting from the given node and collects all values
+     * @param node - The node to start collecting values from.
+     * @param values - An array to store the collected values. This parameter is optional and can be used for recursive calls.
+     * @returns An array of all values found in the subtree rooted at the given node.
+     */
+    public collectValues(): T[];
+    public collectValues(node: RadixNode<T>, values: T[]): T[];
+    public collectValues(node?: RadixNode<T>, values: T[] = []): T[] {
+        if(!node) {
+            node = this.root;
+        }
+
+        if(node.value !== undefined) {
+            values.push(node.value);
+        }
+
+        for(const child of node.children) {
+            this.collectValues(child, values);
+        }
+
+        return values;
+    }
+
     /**
      * Recursively searches for a path in the Radix Tree.
      * This method traverses the tree and searches for the segments of the path, collecting parameters
@@ -154,40 +179,48 @@ export class RadixTree<T> {
 
         const [segment, ...rest] = segments;
 
+        // Try static (exact) matches first, then param matches.
+        // This ensures e.g. 'addNote' is preferred over ':id'.
+        const staticChildren: RadixNode<T>[] = [];
+        const paramChildren: RadixNode<T>[] = [];
+
         for(const child of node.children) {
             if(child.isParam) {
-                const paramName = child.paramName!;
-
-                const childParams: Params = {
-                    ...params,
-                    [paramName]: segment ?? "",
-                };
+                paramChildren.push(child);
+            }
+            else if(segment === child.segment) {
+                staticChildren.push(child);
+            }
+        }
 
-                if(rest.length === 0) {
-                    return {
-                        node: child,
-                        params: childParams
-                    };
+        for(const child of staticChildren) {
+            if(rest.length === 0) {
+                // Only return leaf-level matches (has children for method nodes, or has a value)
+                if(child.value !== undefined || child.children.length > 0) {
+                    return { node: child, params };
                 }
+            }
 
-                const result = this.searchRecursive(child, rest, childParams);
+            const result = this.searchRecursive(child, rest, params);
+            if(result) return result;
+        }
 
-                if(result)
-                    return result;
-            }
-            else if(segment === child.segment) {
-                if(rest.length === 0) {
-                    return {
-                        node: child,
-                        params
-                    };
-                }
+        for(const child of paramChildren) {
+            const paramName = child.paramName!;
 
-                const result = this.searchRecursive(child, rest, params);
+            const childParams: Params = {
+                ...params,
+                [paramName]: segment ?? "",
+            };
 
-                if(result)
-                    return result;
+            if(rest.length === 0) {
+                if(child.value !== undefined || child.children.length > 0) {
+                    return { node: child, params: childParams };
+                }
             }
+
+            const result = this.searchRecursive(child, rest, childParams);
+            if(result) return result;
         }
 
         return undefined;

package/src/window/window-manager.ts

@@ -4,7 +4,7 @@
  * @author NoxFly
  */
 
-import { BrowserWindow, screen } from 'electron/main';
+import { BrowserWindow } from 'electron/main';
 import { Injectable } from '../decorators/injectable.decorator';
 import { Logger } from '../utils/logger';
 
@@ -30,6 +30,12 @@ export interface WindowRecord {
     id: number;
 }
 
+/**
+ * @description
+ * The events emitted by WindowManager when windows are created, closed, focused, or blurred.
+ */
+export type WindowEvent = 'created' | 'closed' | 'focused' | 'blurred';
+
 /**
  * WindowManager is a singleton service that centralizes BrowserWindow lifecycle.
  *
@@ -55,6 +61,8 @@ export interface WindowRecord {
 @Injectable({ lifetime: 'singleton' })
 export class WindowManager {
     private readonly _windows = new Map<number, BrowserWindow>();
+    private readonly listeners = new Map<WindowEvent, Set<(win: BrowserWindow) => void>>();
+
     private _mainWindowId: number | undefined;
 
     // -------------------------------------------------------------------------
@@ -114,15 +122,21 @@ export class WindowManager {
      * win.loadFile('index.html');
      */
     public async createSplash(
-        options: Electron.BrowserWindowConstructorOptions & { animationDuration?: number } = {},
+        options: Electron.BrowserWindowConstructorOptions & {
+            animationDuration?: number;
+            expandToWorkArea?: boolean;
+        } = {},
     ): Promise<BrowserWindow> {
-        const { animationDuration = 600, ...bwOptions } = options;
+        const {
+            animationDuration = 10,
+            expandToWorkArea = true,
+            ...bwOptions
+        } = options;
 
         const win = new BrowserWindow({
             width: 600,
             height: 600,
             center: true,
-            frame: false,
             show: true,
             ...bwOptions,
         });
@@ -131,7 +145,10 @@ export class WindowManager {
 
         Logger.log(`[WindowManager] Splash window #${win.id} created`);
 
-        await this._expandToWorkArea(win, animationDuration);
+        if(expandToWorkArea) {
+            await (() => new Promise((r) => setTimeout(r, 500)))();
+            await this._expandToWorkArea(win, animationDuration);
+        }
 
         return win;
     }
@@ -169,10 +186,12 @@ export class WindowManager {
     /** Closes and destroys a window by id. */
     public close(id: number): void {
         const win = this._windows.get(id);
+
         if (!win) {
             Logger.warn(`[WindowManager] Window #${id} not found`);
             return;
         }
+
         win.destroy();
     }
 
@@ -203,10 +222,27 @@ export class WindowManager {
      */
     public broadcast(channel: string, ...args: unknown[]): void {
         for (const win of this._windows.values()) {
-            if (!win.isDestroyed()) win.webContents.send(channel, ...args);
+            if (!win.isDestroyed()) {
+                win.webContents.send(channel, ...args);
+            }
         }
     }
 
+    // -------------------------------------------------------------------------
+    // Events
+    // -------------------------------------------------------------------------
+
+    public on(event: WindowEvent, handler: (win: BrowserWindow) => void): () => void {
+        const set = this.listeners.get(event) ?? new Set();
+        set.add(handler);
+        this.listeners.set(event, set);
+        return () => set.delete(handler); // retourne unsubscribe
+    }
+
+    private _emit(event: WindowEvent, win: BrowserWindow): void {
+        this.listeners.get(event)?.forEach(h => h(win));
+    }
+
     // -------------------------------------------------------------------------
     // Private
     // -------------------------------------------------------------------------
@@ -218,10 +254,21 @@ export class WindowManager {
             this._mainWindowId = win.id;
         }
 
+        this._emit('created', win);
+
+        win.on('focus', () => this._emit('focused', win));
+        win.on('blur', () => this._emit('blurred', win));
+
         win.once('closed', () => {
             this._windows.delete(win.id);
-            if (this._mainWindowId === win.id) this._mainWindowId = undefined;
+
+            if (this._mainWindowId === win.id) {
+                this._mainWindowId = undefined;
+            }
+
             Logger.log(`[WindowManager] Window #${win.id} closed`);
+
+            this._emit('closed', win);
         });
     }
 
@@ -232,9 +279,7 @@ export class WindowManager {
      */
     private _expandToWorkArea(win: BrowserWindow, animationDuration: number): Promise<void> {
         return new Promise((resolve) => {
-            const { x, y, width, height } = screen.getPrimaryDisplay().workArea;
-
-            win.setBounds({ x, y, width, height }, true);
+            win.maximize();
 
             // Wait for the animation to finish before resolving.
             // We listen to the 'resize' event which fires once the OS
@@ -242,14 +287,16 @@ export class WindowManager {
             let resolved = false;
 
             const done = (): void => {
-                if (resolved) return;
+                if (resolved) {
+                    return;
+                }
                 resolved = true;
                 win.removeListener('resize', done);
                 resolve();
             };
 
             win.once('resize', done);
-            setTimeout(done, animationDuration + 100); // safety fallback
+            setTimeout(done, animationDuration);
         });
     }
 }