@noxfly/noxus 3.0.0-dev.1 → 3.0.0-dev.11

package/dist/main.d.ts

@@ -119,6 +119,12 @@ declare class AppInjector {
  * The global root injector. All singletons live here.
  */
 declare const RootInjector: AppInjector;
+/**
+ * Resets the root injector to a clean state.
+ * **Intended for testing only** — clears all bindings, singletons, and scoped instances
+ * so that each test can start from a fresh DI container without restarting the process.
+ */
+declare function resetRootInjector(): void;
 /**
  * Convenience function: resolve a token from the root injector.
  */
@@ -154,11 +160,11 @@ interface IRouteMetadata {
     middlewares: Middleware[];
 }
 declare function getRouteMetadata(target: object): IRouteMetadata[];
-declare const Get: (path: string, options?: IRouteOptions) => MethodDecorator;
-declare const Post: (path: string, options?: IRouteOptions) => MethodDecorator;
-declare const Put: (path: string, options?: IRouteOptions) => MethodDecorator;
-declare const Patch: (path: string, options?: IRouteOptions) => MethodDecorator;
-declare const Delete: (path: string, options?: IRouteOptions) => MethodDecorator;
+declare const Get: (path: string, options?: IRouteOptions) => (value: Function, context: ClassMethodDecoratorContext) => void;
+declare const Post: (path: string, options?: IRouteOptions) => (value: Function, context: ClassMethodDecoratorContext) => void;
+declare const Put: (path: string, options?: IRouteOptions) => (value: Function, context: ClassMethodDecoratorContext) => void;
+declare const Patch: (path: string, options?: IRouteOptions) => (value: Function, context: ClassMethodDecoratorContext) => void;
+declare const Delete: (path: string, options?: IRouteOptions) => (value: Function, context: ClassMethodDecoratorContext) => void;
 
 
 /**
@@ -172,10 +178,11 @@ declare class Request {
     readonly id: string;
     readonly method: HttpMethod;
     readonly path: string;
-    readonly body: any;
+    readonly body: unknown;
     readonly context: AppInjector;
     readonly params: Record<string, string>;
-    constructor(event: Electron.MessageEvent, senderId: number, id: string, method: HttpMethod, path: string, body: any);
+    readonly query: Record<string, unknown>;
+    constructor(event: Electron.MessageEvent, senderId: number, id: string, method: HttpMethod, path: string, body: unknown, query?: Record<string, unknown>);
 }
 /**
  * The IRequest interface defines the structure of a request object.
@@ -188,12 +195,14 @@ interface IRequest<TBody = unknown> {
     path: string;
     method: HttpMethod;
     body?: TBody;
+    query?: Record<string, unknown>;
 }
 interface IBatchRequestItem<TBody = unknown> {
     requestId?: string;
     path: string;
     method: AtomicHttpMethod;
     body?: TBody;
+    query?: Record<string, unknown>;
 }
 interface IBatchRequestPayload {
     requests: IBatchRequestItem[];
@@ -249,9 +258,18 @@ declare class Router {
     private readonly routes;
     private readonly rootMiddlewares;
     private readonly lazyRoutes;
+    private lazyLoadLock;
     registerController(controllerClass: Type<unknown>, pathPrefix: string, routeGuards?: Guard[], routeMiddlewares?: Middleware[]): this;
     registerLazyRoute(pathPrefix: string, load: () => Promise<unknown>, guards?: Guard[], middlewares?: Middleware[]): this;
     defineRootMiddleware(middleware: Middleware): this;
+    getRegisteredRoutes(): Array<{
+        method: string;
+        path: string;
+    }>;
+    getLazyRoutes(): Array<{
+        prefix: string;
+        loaded: boolean;
+    }>;
     handle(request: Request): Promise<IResponse>;
     private handleAtomic;
     private handleBatch;
@@ -290,6 +308,11 @@ interface WindowRecord {
     window: BrowserWindow;
     id: number;
 }
+/**
+ * @description
+ * The events emitted by WindowManager when windows are created, closed, focused, or blurred.
+ */
+type WindowEvent = 'created' | 'closed' | 'focused' | 'blurred';
 /**
  * WindowManager is a singleton service that centralizes BrowserWindow lifecycle.
  *
@@ -314,6 +337,7 @@ interface WindowRecord {
  */
 declare class WindowManager {
     private readonly _windows;
+    private readonly listeners;
     private _mainWindowId;
     /**
      * Creates a BrowserWindow, optionally performs an animated expand to the
@@ -347,6 +371,7 @@ declare class WindowManager {
      */
     createSplash(options?: Electron.BrowserWindowConstructorOptions & {
         animationDuration?: number;
+        expandToWorkArea?: boolean;
     }): Promise<BrowserWindow>;
     /** Returns all currently open windows. */
     getAll(): BrowserWindow[];
@@ -371,6 +396,8 @@ declare class WindowManager {
      * Broadcasts a message to all open windows.
      */
     broadcast(channel: string, ...args: unknown[]): void;
+    on(event: WindowEvent, handler: (win: BrowserWindow) => void): () => void;
+    private _emit;
     private _register;
     /**
      * Animates the window to the full work area of the primary display.
@@ -380,6 +407,20 @@ declare class WindowManager {
     private _expandToWorkArea;
 }
 
+interface RendererChannels {
+    request: Electron.MessageChannelMain;
+    socket: Electron.MessageChannelMain;
+}
+declare class NoxSocket {
+    private readonly channels;
+    register(senderId: number, requestChannel: Electron.MessageChannelMain, socketChannel: Electron.MessageChannelMain): void;
+    get(senderId: number): RendererChannels | undefined;
+    unregister(senderId: number): void;
+    getSenderIds(): number[];
+    emit<TPayload = unknown>(eventName: string, payload?: TPayload, targetSenderIds?: number[]): void;
+    emitToRenderer<TPayload = unknown>(senderId: number, eventName: string, payload?: TPayload): boolean;
+}
+
 
 /**
  * Your application service should implement IApp.
@@ -409,10 +450,11 @@ interface IApp {
     onActivated(): Promise<void>;
 }
 declare class NoxApp {
-    private appService;
     private readonly router;
     private readonly socket;
     readonly windowManager: WindowManager;
+    private appService;
+    constructor(router: Router, socket: NoxSocket, windowManager: WindowManager);
     init(): Promise<this>;
     /**
      * Registers a lazy route. The file behind this prefix is dynamically
@@ -454,6 +496,107 @@ declare class NoxApp {
     private shutdownChannel;
 }
 
+/**
+ * Logger is a utility class for logging messages to the console.
+ */
+type LogLevel = 'debug' | 'comment' | 'log' | 'info' | 'warn' | 'error' | 'critical';
+declare namespace Logger {
+    /**
+     * Sets the log level for the logger.
+     * This function allows you to change the log level dynamically at runtime.
+     * This won't affect the startup logs.
+     *
+     * If the parameter is a single LogLevel, all log levels with equal or higher severity will be enabled.
+
+    * If the parameter is an array of LogLevels, only the specified levels will be enabled.
+     *
+     * @param level Sets the log level for the logger.
+     */
+    function setLogLevel(level: LogLevel | LogLevel[]): void;
+    /**
+     * Logs a message to the console with log level LOG.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
+    function log(...args: any[]): void;
+    /**
+     * Logs a message to the console with log level INFO.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
+    function info(...args: any[]): void;
+    /**
+     * Logs a message to the console with log level WARN.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
+    function warn(...args: any[]): void;
+    /**
+     * Logs a message to the console with log level ERROR.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
+    function error(...args: any[]): void;
+    /**
+     * Logs a message to the console with log level ERROR and a grey color scheme.
+     */
+    function errorStack(...args: any[]): void;
+    /**
+     * Logs a message to the console with log level DEBUG.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
+    function debug(...args: any[]): void;
+    /**
+     * Logs a message to the console with log level COMMENT.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
+    function comment(...args: any[]): void;
+    /**
+     * Logs a message to the console with log level CRITICAL.
+     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
+     * It uses different colors for different log levels to enhance readability.
+     * @param args The arguments to log.
+     */
+    function critical(...args: any[]): void;
+    /**
+     * Enables logging to a file output for the specified log levels.
+     * @param filepath The path to the log file.
+     * @param levels The log levels to enable file logging for. Defaults to all levels.
+     */
+    function enableFileLogging(filepath: string, levels?: LogLevel[]): void;
+    /**
+     * Disables logging to a file output for the specified log levels.
+     * @param levels The log levels to disable file logging for. Defaults to all levels.
+     */
+    function disableFileLogging(levels?: LogLevel[]): void;
+    const colors: {
+        black: string;
+        grey: string;
+        red: string;
+        green: string;
+        brown: string;
+        blue: string;
+        purple: string;
+        darkGrey: string;
+        lightRed: string;
+        lightGreen: string;
+        yellow: string;
+        lightBlue: string;
+        magenta: string;
+        cyan: string;
+        white: string;
+        initial: string;
+    };
+}
+
 
 /**
  * A single route entry in the application routing table.
@@ -468,10 +611,12 @@ 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.
      * Merged with action-level guards.
@@ -482,6 +627,11 @@ 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[];
 }
 /**
  * Defines the application routing table.
@@ -490,6 +640,9 @@ 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([
  *     {
@@ -498,16 +651,17 @@ 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') },
+ *         ],
  *     },
  * ]);
  */
 declare function defineRoutes(routes: RouteDefinition[]): RouteDefinition[];
 
-
 /**
  * A singleton value override: provides an already-constructed instance
  * for a given token, bypassing the DI factory.
@@ -562,6 +716,15 @@ interface BootstrapConfig {
      * ]
      */
     eagerLoad?: Array<() => Promise<unknown>>;
+    /**
+     * Controls framework log verbosity.
+     * - `'debug'`: all messages (default during development).
+     * - `'info'`: info, warn, error, critical only.
+     * - `'none'`: completely silent — no framework logs.
+     *
+     * You can also pass an array of specific log levels to enable.
+     */
+    logLevel?: 'debug' | 'info' | 'none' | LogLevel[];
 }
 /**
  * Bootstraps the Noxus application.
@@ -667,7 +830,7 @@ interface IControllerMetadata {
  *   getUserById(req: Request) { ... }
  * }
  */
-declare function Controller(options?: ControllerOptions): ClassDecorator;
+declare function Controller(options?: ControllerOptions): <T extends new (...args: any[]) => unknown>(target: T, _context: ClassDecoratorContext) => T | void;
 declare function getControllerMetadata(target: object): IControllerMetadata | undefined;
 
 
@@ -718,121 +881,6 @@ interface InjectableOptions {
  *   constructor(private url: string) {}
  * }
  */
-declare function Injectable(options?: InjectableOptions): ClassDecorator;
-
-/**
- * Logger is a utility class for logging messages to the console.
- */
-type LogLevel = 'debug' | 'comment' | 'log' | 'info' | 'warn' | 'error' | 'critical';
-declare namespace Logger {
-    /**
-     * Sets the log level for the logger.
-     * This function allows you to change the log level dynamically at runtime.
-     * This won't affect the startup logs.
-     *
-     * If the parameter is a single LogLevel, all log levels with equal or higher severity will be enabled.
-
-    * If the parameter is an array of LogLevels, only the specified levels will be enabled.
-     *
-     * @param level Sets the log level for the logger.
-     */
-    function setLogLevel(level: LogLevel | LogLevel[]): void;
-    /**
-     * Logs a message to the console with log level LOG.
-     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
-     * It uses different colors for different log levels to enhance readability.
-     * @param args The arguments to log.
-     */
-    function log(...args: any[]): void;
-    /**
-     * Logs a message to the console with log level INFO.
-     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
-     * It uses different colors for different log levels to enhance readability.
-     * @param args The arguments to log.
-     */
-    function info(...args: any[]): void;
-    /**
-     * Logs a message to the console with log level WARN.
-     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
-     * It uses different colors for different log levels to enhance readability.
-     * @param args The arguments to log.
-     */
-    function warn(...args: any[]): void;
-    /**
-     * Logs a message to the console with log level ERROR.
-     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
-     * It uses different colors for different log levels to enhance readability.
-     * @param args The arguments to log.
-     */
-    function error(...args: any[]): void;
-    /**
-     * Logs a message to the console with log level ERROR and a grey color scheme.
-     */
-    function errorStack(...args: any[]): void;
-    /**
-     * Logs a message to the console with log level DEBUG.
-     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
-     * It uses different colors for different log levels to enhance readability.
-     * @param args The arguments to log.
-     */
-    function debug(...args: any[]): void;
-    /**
-     * Logs a message to the console with log level COMMENT.
-     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
-     * It uses different colors for different log levels to enhance readability.
-     * @param args The arguments to log.
-     */
-    function comment(...args: any[]): void;
-    /**
-     * Logs a message to the console with log level CRITICAL.
-     * This function formats the message with a timestamp, process ID, and the name of the caller function or class.
-     * It uses different colors for different log levels to enhance readability.
-     * @param args The arguments to log.
-     */
-    function critical(...args: any[]): void;
-    /**
-     * Enables logging to a file output for the specified log levels.
-     * @param filepath The path to the log file.
-     * @param levels The log levels to enable file logging for. Defaults to all levels.
-     */
-    function enableFileLogging(filepath: string, levels?: LogLevel[]): void;
-    /**
-     * Disables logging to a file output for the specified log levels.
-     * @param levels The log levels to disable file logging for. Defaults to all levels.
-     */
-    function disableFileLogging(levels?: LogLevel[]): void;
-    const colors: {
-        black: string;
-        grey: string;
-        red: string;
-        green: string;
-        brown: string;
-        blue: string;
-        purple: string;
-        darkGrey: string;
-        lightRed: string;
-        lightGreen: string;
-        yellow: string;
-        lightBlue: string;
-        magenta: string;
-        cyan: string;
-        white: string;
-        initial: string;
-    };
-}
-
-interface RendererChannels {
-    request: Electron.MessageChannelMain;
-    socket: Electron.MessageChannelMain;
-}
-declare class NoxSocket {
-    private readonly channels;
-    register(senderId: number, requestChannel: Electron.MessageChannelMain, socketChannel: Electron.MessageChannelMain): void;
-    get(senderId: number): RendererChannels | undefined;
-    unregister(senderId: number): void;
-    getSenderIds(): number[];
-    emit<TPayload = unknown>(eventName: string, payload?: TPayload, targetSenderIds?: number[]): number;
-    emitToRenderer<TPayload = unknown>(senderId: number, eventName: string, payload?: TPayload): boolean;
-}
+declare function Injectable(options?: InjectableOptions): <T extends new (...args: any[]) => unknown>(target: T, _context: ClassDecoratorContext) => T | void;
 
-export { AppInjector, type AtomicHttpMethod, BadGatewayException, BadRequestException, type BootstrapConfig, ConflictException, Controller, type ControllerAction, type ControllerOptions, Delete, ForbiddenException, type ForwardRefFn, ForwardReference, GatewayTimeoutException, Get, type Guard, type HttpMethod, HttpVersionNotSupportedException, type IApp, type IBatchRequestItem, type IBatchRequestPayload, type IBatchResponsePayload, type IBinding, type IControllerMetadata, type ILazyRoute, type IRendererEventMessage, type IRequest, type IResponse, type IRouteDefinition, type IRouteMetadata, type IRouteOptions, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, type MaybeAsync, MethodNotAllowedException, type Middleware, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, NoxSocket, Patch, PaymentRequiredException, Post, Put, RENDERER_EVENT_TYPE, Request, RequestTimeoutException, ResponseException, RootInjector, type RouteDefinition, Router, ServiceUnavailableException, type SingletonOverride, Token, type TokenKey, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, type WindowConfig, WindowManager, type WindowRecord, bootstrapApplication, createRendererEventMessage, defineRoutes, forwardRef, getControllerMetadata, getRouteMetadata, inject, isAtomicHttpMethod, isRendererEventMessage, token };
+export { AppInjector, type AtomicHttpMethod, BadGatewayException, BadRequestException, type BootstrapConfig, ConflictException, Controller, type ControllerAction, type ControllerOptions, Delete, ForbiddenException, type ForwardRefFn, ForwardReference, GatewayTimeoutException, Get, type Guard, type HttpMethod, HttpVersionNotSupportedException, type IApp, type IBatchRequestItem, type IBatchRequestPayload, type IBatchResponsePayload, type IBinding, type IControllerMetadata, type ILazyRoute, type IRendererEventMessage, type IRequest, type IResponse, type IRouteDefinition, type IRouteMetadata, type IRouteOptions, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, type MaybeAsync, MethodNotAllowedException, type Middleware, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, NoxSocket, Patch, PaymentRequiredException, Post, Put, RENDERER_EVENT_TYPE, Request, RequestTimeoutException, ResponseException, RootInjector, type RouteDefinition, Router, ServiceUnavailableException, type SingletonOverride, Token, type TokenKey, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, type WindowConfig, type WindowEvent, WindowManager, type WindowRecord, bootstrapApplication, createRendererEventMessage, defineRoutes, forwardRef, getControllerMetadata, getRouteMetadata, inject, isAtomicHttpMethod, isRendererEventMessage, resetRootInjector, token };