@noxfly/noxus 2.4.0 → 3.0.0-dev.0

package/src/routes.ts

@@ -0,0 +1,78 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { Guard } from './decorators/guards.decorator';
+import { Middleware } from './decorators/middleware.decorator';
+
+/**
+ * A single route entry in the application routing table.
+ */
+export interface RouteDefinition {
+    /**
+     * The path prefix for this route (e.g. 'users', 'orders').
+     * All actions defined in the controller will be prefixed with this path.
+     */
+    path: string;
+
+    /**
+     * Dynamic import function returning the controller file.
+     * The controller is loaded lazily on the first IPC request targeting this prefix.
+     *
+     * @example
+     * load: () => import('./modules/users/users.controller')
+     */
+    load: () => Promise<unknown>;
+
+    /**
+     * Guards applied to every action in this controller.
+     * Merged with action-level guards.
+     */
+    guards?: Guard[];
+
+    /**
+     * Middlewares applied to every action in this controller.
+     * Merged with action-level middlewares.
+     */
+    middlewares?: Middleware[];
+}
+
+/**
+ * Defines the application routing table.
+ * Each entry maps a path prefix to a lazily-loaded controller.
+ *
+ * This is the single source of truth for routing — no path is declared
+ * in @Controller(), preventing duplicate route prefixes across controllers.
+ *
+ * @example
+ * export const routes = defineRoutes([
+ *     {
+ *         path: 'users',
+ *         load: () => import('./modules/users/users.controller'),
+ *         guards: [authGuard],
+ *     },
+ *     {
+ *         path: 'orders',
+ *         load: () => import('./modules/orders/orders.controller'),
+ *         guards: [authGuard],
+ *         middlewares: [logMiddleware],
+ *     },
+ * ]);
+ */
+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);
+
+    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, ''),
+    }));
+}

package/src/socket.ts

@@ -8,16 +8,16 @@
  * 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';
+import { Injectable } from './decorators/injectable.decorator';
+import { createRendererEventMessage } from './request';
+import { Logger } from './utils/logger';
 
 interface RendererChannels {
     request: Electron.MessageChannelMain;
     socket: Electron.MessageChannelMain;
 }
 
-@Injectable('singleton')
+@Injectable({ lifetime: 'singleton' })
 export class NoxSocket {
     private readonly channels = new Map<number, RendererChannels>();
 

package/src/window/window-manager.ts

@@ -0,0 +1,255 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { BrowserWindow, screen } from 'electron/main';
+import { Injectable } from '../decorators/injectable.decorator';
+import { Logger } from '../utils/logger';
+
+export interface WindowConfig extends Electron.BrowserWindowConstructorOptions {
+    /**
+     * If true, the window expands to fill the work area after creation
+     * using an animated setBounds. The content is loaded only after
+     * the animation completes, preventing the viewbox freeze issue.
+     * @default false
+     */
+    expandToWorkArea?: boolean;
+
+    /**
+     * Duration in ms to wait for the setBounds animation to complete
+     * before loading content. Only used when expandToWorkArea is true.
+     * @default 600
+     */
+    expandAnimationDuration?: number;
+}
+
+export interface WindowRecord {
+    window: BrowserWindow;
+    id: number;
+}
+
+/**
+ * WindowManager is a singleton service that centralizes BrowserWindow lifecycle.
+ *
+ * Features:
+ * - Creates and tracks all application windows.
+ * - Handles the animated expand-to-work-area pattern correctly,
+ *   loading content only after the animation ends to avoid the viewbox freeze.
+ * - Provides convenience methods to get windows by id, get the main window, etc.
+ * - Automatically removes windows from the registry on close.
+ *
+ * @example
+ * // In your IApp.onReady():
+ * const wm = inject(WindowManager);
+ *
+ * const win = await wm.create({
+ *   width: 600, height: 600, center: true,
+ *   expandToWorkArea: true,
+ *   webPreferences: { preload: path.join(__dirname, 'preload.js') },
+ * });
+ *
+ * win.loadFile('index.html');
+ */
+@Injectable({ lifetime: 'singleton' })
+export class WindowManager {
+    private readonly _windows = new Map<number, BrowserWindow>();
+    private _mainWindowId: number | undefined;
+
+    // -------------------------------------------------------------------------
+    // Creation
+    // -------------------------------------------------------------------------
+
+    /**
+     * Creates a BrowserWindow, optionally performs an animated expand to the
+     * work area, and registers it in the manager.
+     *
+     * If expandToWorkArea is true:
+     * 1. The window is created at the given initial size (defaults to 600×600, centered).
+     * 2. An animated setBounds expands it to the full work area.
+     * 3. The returned promise resolves only after the animation, so callers
+     *    can safely call win.loadFile() without the viewbox freeze.
+     *
+     * @param config Window configuration.
+     * @param isMain Mark this window as the main window (accessible via getMain()).
+     */
+    public async create(config: WindowConfig, isMain = false): Promise<BrowserWindow> {
+        const {
+            expandToWorkArea = false,
+            expandAnimationDuration = 600,
+            ...bwOptions
+        } = config;
+
+        // show: false by default during creation — we control visibility
+        const win = new BrowserWindow({ show: false, ...bwOptions });
+
+        this._register(win, isMain);
+
+        if (expandToWorkArea) {
+            await this._expandToWorkArea(win, expandAnimationDuration);
+        }
+
+        win.once('ready-to-show', () => win.show());
+
+        Logger.log(`[WindowManager] Created window #${win.id}${isMain ? ' (main)' : ''}`);
+
+        return win;
+    }
+
+    /**
+     * Creates the initial "splash" window that is shown immediately after
+     * app.whenReady(). It is displayed instantly (show: true, no preload
+     * loading) and then expanded to the work area with animation.
+     *
+     * After the animation completes you can call win.loadFile() without
+     * experiencing the viewbox freeze.
+     *
+     * This is the recommended way to get pixels on screen as fast as possible.
+     *
+     * @example
+     * const win = await wm.createSplash({
+     *   webPreferences: { preload: path.join(__dirname, 'preload.js') }
+     * });
+     * win.loadFile('index.html');
+     */
+    public async createSplash(
+        options: Electron.BrowserWindowConstructorOptions & { animationDuration?: number } = {},
+    ): Promise<BrowserWindow> {
+        const { animationDuration = 600, ...bwOptions } = options;
+
+        const win = new BrowserWindow({
+            width: 600,
+            height: 600,
+            center: true,
+            frame: false,
+            show: true,
+            ...bwOptions,
+        });
+
+        this._register(win, true);
+
+        Logger.log(`[WindowManager] Splash window #${win.id} created`);
+
+        await this._expandToWorkArea(win, animationDuration);
+
+        return win;
+    }
+
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+
+    /** Returns all currently open windows. */
+    public getAll(): BrowserWindow[] {
+        return [...this._windows.values()];
+    }
+
+    /** Returns the window designated as main, or undefined. */
+    public getMain(): BrowserWindow | undefined {
+        return this._mainWindowId !== undefined
+            ? this._windows.get(this._mainWindowId)
+            : undefined;
+    }
+
+    /** Returns a window by its Electron id, or undefined. */
+    public getById(id: number): BrowserWindow | undefined {
+        return this._windows.get(id);
+    }
+
+    /** Returns the number of open windows. */
+    public get count(): number {
+        return this._windows.size;
+    }
+
+    // -------------------------------------------------------------------------
+    // Actions
+    // -------------------------------------------------------------------------
+
+    /** 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();
+    }
+
+    /** Closes all windows. */
+    public closeAll(): void {
+        for (const win of this._windows.values()) {
+            win.destroy();
+        }
+    }
+
+    /**
+     * Sends a message to a specific window via webContents.send.
+     * @param id Target window id.
+     * @param channel IPC channel name.
+     * @param args Payload.
+     */
+    public send(id: number, channel: string, ...args: unknown[]): void {
+        const win = this._windows.get(id);
+        if (!win || win.isDestroyed()) {
+            Logger.warn(`[WindowManager] Cannot send to window #${id}: not found or destroyed`);
+            return;
+        }
+        win.webContents.send(channel, ...args);
+    }
+
+    /**
+     * Broadcasts a message to all open windows.
+     */
+    public broadcast(channel: string, ...args: unknown[]): void {
+        for (const win of this._windows.values()) {
+            if (!win.isDestroyed()) win.webContents.send(channel, ...args);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+
+    private _register(win: BrowserWindow, isMain: boolean): void {
+        this._windows.set(win.id, win);
+
+        if (isMain && this._mainWindowId === undefined) {
+            this._mainWindowId = win.id;
+        }
+
+        win.once('closed', () => {
+            this._windows.delete(win.id);
+            if (this._mainWindowId === win.id) this._mainWindowId = undefined;
+            Logger.log(`[WindowManager] Window #${win.id} closed`);
+        });
+    }
+
+    /**
+     * Animates the window to the full work area of the primary display.
+     * Resolves only after the animation is complete, so that content loaded
+     * afterward gets the correct surface size (no viewbox freeze).
+     */
+    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);
+
+            // Wait for the animation to finish before resolving.
+            // We listen to the 'resize' event which fires once the OS
+            // animation completes, with a safety timeout as fallback.
+            let resolved = false;
+
+            const done = (): void => {
+                if (resolved) return;
+                resolved = true;
+                win.removeListener('resize', done);
+                resolve();
+            };
+
+            win.once('resize', done);
+            setTimeout(done, animationDuration + 100); // safety fallback
+        });
+    }
+}

package/tsconfig.json

@@ -4,7 +4,7 @@
         "rootDir": "./src",
         "baseUrl": "./",
         "moduleResolution": "node",
-        "target": "ES6",
+        "target": "ES2020",
         "module": "CommonJS",
         "forceConsistentCasingInFileNames": true,
         "strict": true,
@@ -13,22 +13,17 @@
         "noFallthroughCasesInSwitch": true,
         "sourceMap": true,
         "experimentalDecorators": true,
-        "emitDecoratorMetadata": true,
+        "emitDecoratorMetadata": false,
         "importHelpers": false,
         "esModuleInterop": true,
         "useDefineForClassFields": false,
         "noPropertyAccessFromIndexSignature": false,
         "noUncheckedIndexedAccess": true,
-        "skipLibCheck": true,
-        "types": ["reflect-metadata"],
-    },
-    "tsc-alias": {
-        "resolveFullPaths": true,
-        "verbose": false,
+        "skipLibCheck": true
     },
     "include": [
         "src/**/*.ts",
         "src/**/*.d.ts",
-        "node_modules/electron/electron.d.ts",
-    ],
+        "node_modules/electron/electron.d.ts"
+    ]
 }

package/tsup.config.ts

@@ -6,7 +6,7 @@ const copyrights = `
  * @license MIT
  * @author NoxFly
  */
-`.trim()
+`.trim();
 
 export default defineConfig({
     entry: {
@@ -30,5 +30,5 @@ export default defineConfig({
     treeshake: false,
     banner: {
         js: copyrights,
-    }
+    },
 });

package/dist/app-injector-B3MvgV3k.d.mts

@@ -1,95 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-interface Type<T> extends Function {
-    new (...args: any[]): T;
-}
-/**
- * Represents a generic type that can be either a value or a promise resolving to that value.
- */
-type MaybeAsync<T> = T | Promise<T>;
-
-
-/**
- * A function that returns a type.
- * Used for forward references to types that are not yet defined.
- */
-interface ForwardRefFn<T = any> {
-    (): Type<T>;
-}
-/**
- * A wrapper class for forward referenced types.
- */
-declare class ForwardReference<T = any> {
-    readonly forwardRefFn: ForwardRefFn<T>;
-    constructor(forwardRefFn: ForwardRefFn<T>);
-}
-/**
- * Creates a forward reference to a type.
- * @param fn A function that returns the type.
- * @returns A ForwardReference instance.
- */
-declare function forwardRef<T = any>(fn: ForwardRefFn<T>): ForwardReference<T>;
-
-
-/**
- * Represents a lifetime of a binding in the dependency injection system.
- * It can be one of the following:
- * - 'singleton': The instance is created once and shared across the application.
- * - 'scope': The instance is created once per scope (e.g., per request).
- * - 'transient': A new instance is created every time it is requested.
- */
-type Lifetime = 'singleton' | 'scope' | 'transient';
-/**
- * Represents a binding in the dependency injection system.
- * It contains the lifetime of the binding, the implementation type, and optionally an instance.
- */
-interface IBinding {
-    lifetime: Lifetime;
-    implementation: Type<unknown>;
-    instance?: InstanceType<Type<unknown>>;
-}
-/**
- * AppInjector is the root dependency injection container.
- * It is used to register and resolve dependencies in the application.
- * It supports different lifetimes for dependencies:
- * This should not be manually instantiated, outside of the framework.
- * Use the `RootInjector` instance instead.
- */
-declare class AppInjector {
-    readonly name: string | null;
-    bindings: Map<Type<unknown>, IBinding>;
-    singletons: Map<Type<unknown>, unknown>;
-    scoped: Map<Type<unknown>, unknown>;
-    constructor(name?: string | null);
-    /**
-     * Typically used to create a dependency injection scope
-     * at the "scope" level (i.e., per-request lifetime).
-     *
-     * SHOULD NOT BE USED by anything else than the framework itself.
-     */
-    createScope(): AppInjector;
-    /**
-     * Called when resolving a dependency,
-     * i.e., retrieving the instance of a given class.
-     */
-    resolve<T>(target: Type<T> | ForwardReference<T>): T;
-    /**
-     * Instantiates a class, resolving its dependencies.
-     */
-    private instantiate;
-}
-/**
- * Injects a type from the dependency injection system.
- * This function is used to retrieve an instance of a type that has been registered in the dependency injection system.
- * It is typically used in the constructor of a class to inject dependencies.
- * @param t - The type to inject.
- * @returns An instance of the type.
- * @throws If the type is not registered in the dependency injection system.
- */
-declare function inject<T>(t: Type<T> | ForwardReference<T>): T;
-declare const RootInjector: AppInjector;
-
-export { AppInjector as A, type ForwardRefFn as F, type IBinding as I, type Lifetime as L, type MaybeAsync as M, RootInjector as R, type Type as T, ForwardReference as a, forwardRef as f, inject as i };

package/dist/app-injector-B3MvgV3k.d.ts

@@ -1,95 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-interface Type<T> extends Function {
-    new (...args: any[]): T;
-}
-/**
- * Represents a generic type that can be either a value or a promise resolving to that value.
- */
-type MaybeAsync<T> = T | Promise<T>;
-
-
-/**
- * A function that returns a type.
- * Used for forward references to types that are not yet defined.
- */
-interface ForwardRefFn<T = any> {
-    (): Type<T>;
-}
-/**
- * A wrapper class for forward referenced types.
- */
-declare class ForwardReference<T = any> {
-    readonly forwardRefFn: ForwardRefFn<T>;
-    constructor(forwardRefFn: ForwardRefFn<T>);
-}
-/**
- * Creates a forward reference to a type.
- * @param fn A function that returns the type.
- * @returns A ForwardReference instance.
- */
-declare function forwardRef<T = any>(fn: ForwardRefFn<T>): ForwardReference<T>;
-
-
-/**
- * Represents a lifetime of a binding in the dependency injection system.
- * It can be one of the following:
- * - 'singleton': The instance is created once and shared across the application.
- * - 'scope': The instance is created once per scope (e.g., per request).
- * - 'transient': A new instance is created every time it is requested.
- */
-type Lifetime = 'singleton' | 'scope' | 'transient';
-/**
- * Represents a binding in the dependency injection system.
- * It contains the lifetime of the binding, the implementation type, and optionally an instance.
- */
-interface IBinding {
-    lifetime: Lifetime;
-    implementation: Type<unknown>;
-    instance?: InstanceType<Type<unknown>>;
-}
-/**
- * AppInjector is the root dependency injection container.
- * It is used to register and resolve dependencies in the application.
- * It supports different lifetimes for dependencies:
- * This should not be manually instantiated, outside of the framework.
- * Use the `RootInjector` instance instead.
- */
-declare class AppInjector {
-    readonly name: string | null;
-    bindings: Map<Type<unknown>, IBinding>;
-    singletons: Map<Type<unknown>, unknown>;
-    scoped: Map<Type<unknown>, unknown>;
-    constructor(name?: string | null);
-    /**
-     * Typically used to create a dependency injection scope
-     * at the "scope" level (i.e., per-request lifetime).
-     *
-     * SHOULD NOT BE USED by anything else than the framework itself.
-     */
-    createScope(): AppInjector;
-    /**
-     * Called when resolving a dependency,
-     * i.e., retrieving the instance of a given class.
-     */
-    resolve<T>(target: Type<T> | ForwardReference<T>): T;
-    /**
-     * Instantiates a class, resolving its dependencies.
-     */
-    private instantiate;
-}
-/**
- * Injects a type from the dependency injection system.
- * This function is used to retrieve an instance of a type that has been registered in the dependency injection system.
- * It is typically used in the constructor of a class to inject dependencies.
- * @param t - The type to inject.
- * @returns An instance of the type.
- * @throws If the type is not registered in the dependency injection system.
- */
-declare function inject<T>(t: Type<T> | ForwardReference<T>): T;
-declare const RootInjector: AppInjector;
-
-export { AppInjector as A, type ForwardRefFn as F, type IBinding as I, type Lifetime as L, type MaybeAsync as M, RootInjector as R, type Type as T, ForwardReference as a, forwardRef as f, inject as i };