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

package/.github/copilot-instructions.md

@@ -1,32 +1,128 @@
 # Copilot Instructions
+
 ## Core Architecture
-- bootstrapApplication in [src/bootstrap.ts](src/bootstrap.ts) waits for Electron app readiness, resolves NoxApp via DI, and returns a configured instance.
-- [src/app.ts](src/app.ts) wires ipcMain events, spawns paired request/socket MessageChannels per renderer, and delegates handling to Router and NoxSocket.
-- Package exports are split between renderer and main targets in [package.json](package.json); import Electron main APIs from @noxfly/noxus/main and renderer helpers from @noxfly/noxus or @noxfly/noxus/renderer.
+- bootstrapApplication in [src/internal/bootstrap.ts](src/internal/bootstrap.ts) waits for Electron app readiness, applies log level config, wires the controller registrar, flushes DI, resolves NoxApp, registers routes and eager-loads, then returns a configured instance.
+- [src/internal/app.ts](src/internal/app.ts) wires ipcMain events, spawns paired request/socket MessageChannels per renderer, and delegates handling to Router and NoxSocket.
+- Package exports are split between renderer and main targets in [package.json](package.json); import Electron main APIs from @noxfly/noxus/main, renderer helpers from @noxfly/noxus or @noxfly/noxus/renderer, and preload helpers from @noxfly/noxus/preload.
 - Dependency injection centers on RootInjector in [src/DI/app-injector.ts](src/DI/app-injector.ts); @Injectable triggers auto-registration through [src/DI/injector-explorer.ts](src/DI/injector-explorer.ts) and supports singleton, scope, and transient lifetimes.
-- Modules decorated via [src/decorators/module.decorator.ts](src/decorators/module.decorator.ts) compose providers, controllers, and nested modules; bootstrapApplication rejects roots lacking Module metadata.
+- resetRootInjector() in [src/DI/app-injector.ts](src/DI/app-injector.ts) clears all bindings, singletons, and scoped instances — use it in tests to get a clean DI state between test suites.
+- There is no Module decorator — controllers and services are standalone, registered via @Injectable and @Controller decorators with explicit deps arrays.
+
 ## Request Lifecycle
-- Request objects from [src/request.ts](src/request.ts) wrap Electron MessageEvents and spawn per-request DI scopes on Request.context.
-- Router in [src/router.ts](src/router.ts) indexes routes in a radix tree, merges controller-level and method-level decorators, and enforces root middlewares, route middlewares, then guards before invoking controller actions.
-- ResponseException subclasses in [src/exceptions.ts](src/exceptions.ts) propagate status codes; throwing one short-circuits the pipeline so Router returns a structured error payload.
+- Request objects from [src/internal/request.ts](src/internal/request.ts) wrap Electron MessageEvents and spawn per-request DI scopes on Request.context. They expose params, body, and query (Record<string, string>).
+- Router in [src/internal/router.ts](src/internal/router.ts) indexes routes in a radix tree, merges controller-level and method-level decorators, and enforces root middlewares, route middlewares, then guards before invoking controller actions.
+- The radix tree in [src/utils/radix-tree.ts](src/utils/radix-tree.ts) prioritizes static segments over parameter segments during search, so `addNote/:id` won't be shadowed by `:id`.
+- ResponseException subclasses in [src/internal/exceptions.ts](src/internal/exceptions.ts) propagate status codes; throwing one short-circuits the pipeline so Router returns a structured error payload.
 - Batch requests use HTTP method BATCH and normalization logic in Router.handleBatch; payloads must satisfy IBatchRequestPayload to fan out atomic subrequests.
+
 ## Communication Channels
 - ipcMain listens for gimme-my-port and posts two transferable ports back to the renderer: index 0 carries request/response traffic, index 1 is reserved for socket-style push messages.
-- NoxSocket in [src/socket.ts](src/socket.ts) maps sender IDs to {request, socket} channels and emits renderer events exclusively through channels.socket.port1.
-- Renderer helpers in [src/renderer-events.ts](src/renderer-events.ts) expose RendererEventRegistry.tryDispatchFromMessageEvent to route push events; the preload script must start both ports and hand the second to this registry.
-- Renderer-facing bootstrap lives in [src/renderer-client.ts](src/renderer-client.ts); NoxRendererClient requests ports, wires request/socket handlers, tracks pending promises, and surfaces RendererEventRegistry for push consumption.
-- Preload scripts should call exposeNoxusBridge from [src/preload-bridge.ts](src/preload-bridge.ts) to publish window.noxus.requestPort; the helper sends 'gimme-my-port' and forwards both transferable ports with the configured init message.
+- NoxSocket in [src/internal/socket.ts](src/internal/socket.ts) maps sender IDs to {request, socket} channels and emits renderer events exclusively through channels.socket.port1. emit() returns void.
+- Renderer helpers in [src/internal/renderer-events.ts](src/internal/renderer-events.ts) expose RendererEventRegistry.tryDispatchFromMessageEvent to route push events; the preload script must start both ports and hand the second to this registry.
+- Renderer-facing bootstrap lives in [src/internal/renderer-client.ts](src/internal/renderer-client.ts); NoxRendererClient requests ports, wires request/socket handlers, tracks pending promises with configurable timeout (default 10s), and surfaces RendererEventRegistry for push consumption.
+- Preload scripts should call exposeNoxusBridge from [src/internal/preload-bridge.ts](src/internal/preload-bridge.ts) to publish window.noxus.requestPort; the helper sends 'gimme-my-port' and forwards both transferable ports with the configured init message.
 - When adjusting preload or renderer glue, ensure window.postMessage('init-port', ...) forwards both ports so the socket channel stays alive alongside the request channel.
+
+## Route Definitions
+- defineRoutes in [src/internal/routes.ts](src/internal/routes.ts) is the single source of truth for routing. It validates for duplicate and overlapping prefixes and supports nested children with inherited guards/middlewares.
+- Parent routes can omit the load function and serve only as shared prefix containers for children.
+- flattenRoutes recursively merges parent guards and middlewares into each child before validation.
+
 ## Decorator Conventions
 - Controller paths omit leading/trailing slashes; method decorators (Get, Post, etc.) auto-trim segments via [src/decorators/method.decorator.ts](src/decorators/method.decorator.ts).
 - Guards registered through Authorize in [src/decorators/guards.decorator.ts](src/decorators/guards.decorator.ts) aggregate at controller and action scope; they must resolve truthy or Router throws UnauthorizedException.
 - Injectable lifetimes default to scope; use singleton for app-wide utilities (window managers, sockets) and transient for short-lived resources.
+
+## Dependency Injection Internals
+- InjectorExplorer in [src/DI/injector-explorer.ts](src/DI/injector-explorer.ts) accumulates registrations at import time and flushes in two phases (bind then resolve).
+- To avoid a circular dependency between InjectorExplorer and Router, controller registration is decoupled via a ControllerRegistrar callback set by bootstrapApplication through setControllerRegistrar(). There is no require() call.
+- flushAccumulated is serialized through a Promise-based lock (loadingLock) to prevent concurrent lazy module loads from corrupting the queue. Use waitForFlush() to await completion.
+- Phase 2 validates that declared deps have a corresponding binding or singleton, and emits warnings for missing ones at startup.
+
 ## Logging and Utilities
-- Logger in [src/utils/logger.ts](src/utils/logger.ts) standardizes color-coded log, warn, error, and comment output; use it when extending framework behavior.
+- Logger in [src/utils/logger.ts](src/utils/logger.ts) standardizes color-coded log, warn, error, and comment output; it supports configurable log levels via Logger.setLogLevel() and file output via Logger.enableFileLogging().
+- bootstrapApplication accepts a logLevel option ('debug' | 'info' | 'none' | LogLevel[]) to control framework verbosity.
 - Path resolution relies on RadixTree from [src/utils/radix-tree.ts](src/utils/radix-tree.ts); normalize controller and route paths to avoid duplicate slashes.
-- Request.params are filled by Router.extractParams; controllers read route params directly from Request without decorator helpers yet.
+- Request.params are filled by Router.extractParams; Request.query carries query parameters passed from the renderer; controllers read both directly from the Request object.
+
 ## Build and Tooling
 - Run npm run build to invoke tsup with dual ESM/CJS outputs configured in [tsup.config.ts](tsup.config.ts); the postbuild script at [scripts/postbuild.js](scripts/postbuild.js) deduplicates license banners.
-- Node 20 or newer is required; reflect-metadata is a peer dependency so host apps must install and import it before using decorators.
+- Node 20 or newer is required; no reflect-metadata is needed — all dependency information comes from explicit deps arrays.
 - Source uses baseUrl ./ with tsc-alias, so prefer absolute imports like src/module/file when editing framework code to match existing style.
 - Dist artifacts live under dist/ and are published outputs; regenerate them via the build script rather than editing directly.
+
+
+## Validating TypeScript changes
+
+MANDATORY: Always check for compilation errors before running any tests or validation scripts, or declaring work complete, then fix all compilation errors before moving forward.
+
+## Coding Guidelines
+
+### Indentation
+
+Use spaces, 4 for any file type, except yml that are 2 spaces.
+
+### Naming Conventions
+
+    Use PascalCase for type names
+    Use PascaleCase for class names and interfaces
+    Prefix interface names by an 'I'
+    Use PascalCase for enum values
+    Choose wisely enum over union types or consts
+    Prefer interfaces over types when possible
+    Use camelCase for function and method names
+    Use camelCase for property names and local variables
+    Use whole words in names when possible
+    Use kebab-case for file names, and avoid using the same name for multiple files in different directories to prevent confusion
+    suffix file names with their type (e.g., .service.ts, .controller.ts, .component.ts) to make it clear what the file contains and its role in the architecture
+
+### Types
+
+    Do not export types or functions unless you need to share it across multiple components
+    Do not introduce new types or values to the global namespace unless they are truly global concepts
+
+### Comments
+
+    Use JSDoc style comments for functions, interfaces, enums, and classes
+    Always include a description of what the function/class/interface/enum does, its parameters, its return value and an example (if applicable)
+    Use inline comments to explain why a particular implementation was chosen, especially if it's not obvious. Avoid stating what the code is doing, and instead focus on the reasoning behind it.
+
+### Strings
+
+    Always use "double quotes" for strings.
+    Use template literals for string interpolation and multi-line strings instead of concatenation.
+
+### Style
+
+    Use arrow functions => over anonymous function expressions.
+    Only surround arrow function parameters when necessary.
+    Only surround arrow function bodies with curly braces when they are not a direct return of an expression.
+    Always surround loop and conditional bodies with curly braces.
+    Open curly braces always go on the same line as whatever necessitates them
+    Use StrouStrup style for control statements (the else is on a new line after the closing brace of the if).
+    Whenever possible, use in top-level scopes export function x(…) {…} instead of export const x = (…) => {…}. One advantage of using the function keyword is that the stack-trace shows a good name when debugging.
+
+### Code Quality
+
+    All files must include the NoxFly copyright header
+    Prefer async and await over Promise and then calls
+    Always await a promise to make the function appearable in the stack trace, unless you have a good reason not to (e.g., you want it to run in the background and don't care about errors).
+    Look for existing test patterns before creating new structures
+    Prefer regex capture groups with names over numbered capture groups.
+    If you create any temporary new files, scripts, or helper files for iteration, clean up these files by removing them at the end of the task
+    Never duplicate imports. Always reuse existing imports if they are present.
+    When removing an import, do not leave behind blank lines where the import was. Ensure the surrounding code remains compact.
+    Do not use any or unknown as the type for variables, parameters, or return values unless absolutely necessary. If they need type annotations, they should have proper types or interfaces defined.
+    Do not duplicate code. Always look for existing utility functions, helpers, or patterns in the codebase before implementing new functionality. Reuse and extend existing code whenever possible.
+    Avoid using bind(), call() and apply() solely to control this or partially apply arguments; prefer arrow functions or closures to capture the necessary context, and use these methods only when required by an API or interoperability.
+    Always think for the most performant code for future scalability, even if it requires more upfront work. Consider time and space complexity when designing algorithms and data structures, and prefer efficient patterns that will scale well as the codebase grows.
+    Always specify the `public`, `private`, or `protected` access modifier for class members, even if the default is public. This improves readability and makes the intended encapsulation clear to other developers.
+    Always use explicit return types for functions and methods, even when TypeScript can infer them. This improves readability and helps catch unintended return values or changes in the function's behavior over time.
+    Avoid using non-null assertions (!). Instead, handle potential null or undefined values explicitly through type guards, default values, or proper error handling to ensure safer and more robust code.
+    Always prefer composition over inheritance. Favor creating small, reusable functions and classes that can be combined to achieve complex behavior, rather than relying on deep inheritance hierarchies which can lead to tight coupling and reduced flexibility.
+    Always use strict equality (=== and !==) instead of loose equality (== and !=) to avoid unexpected type coercion and ensure more predictable comparisons.
+    Always ensure readme and copilot-instructions files are updated to reflect any architectural, structural, or convention changes made to the codebase. These documents serve as the primary reference for other developers and must accurately represent the current state of the project.
+    Do not hesitate to refactor existing code to improve readability, maintainability, or performance, even if it is not directly related to the task at hand. Continuous improvement of the codebase is essential for long-term success and developer satisfaction.
+    Do not hesitate to ask for help or clarification if a request is unclear.
+    Do not hesitate to suggest improvements or optimizations if you see an opportunity, even if it's outside the scope of your current task.
+    Always write unit tests for new functionality and bug fixes, and ensure existing tests are updated as necessary to reflect changes in the codebase. Aim for high test coverage and meaningful test cases that validate the expected behavior of the code.

package/AGENTS.md

@@ -0,0 +1,5 @@
+# Agents
+
+All project conventions, architecture details, and coding guidelines are maintained in the [Copilot Instructions](.github/copilot-instructions.md) file.
+
+Please refer to that file for context before making changes to this codebase.

package/README.md

@@ -120,19 +120,30 @@ export class AppService implements IApp {
 }
 ```
 
-### 4. Bootstrap the application
+### 4. Define routes
+
+```ts
+// routes.ts
+import { defineRoutes } from '@noxfly/noxus/main';
+
+export const routes = defineRoutes([
+    { path: 'users',  load: () => import('./controllers/user.controller.js') },
+    { path: 'orders', load: () => import('./controllers/order.controller.js') },
+]);
+```
+
+### 5. Bootstrap the application
 
 ```ts
 // main.ts
 import { bootstrapApplication } from '@noxfly/noxus/main';
 import { AppService } from './app.service';
+import { routes } from './routes';
 
-const noxApp = await bootstrapApplication();
+const noxApp = await bootstrapApplication({ routes });
 
 noxApp
     .configure(AppService)
-    .lazy('users',  () => import('./controllers/user.controller.js'))
-    .lazy('orders', () => import('./controllers/order.controller.js'))
     .start();
 ```
 
@@ -195,6 +206,9 @@ import { inject } from '@noxfly/noxus/main';
 const userService = inject(UserService);
 ```
 
+When you decide to inject manually with `inject()`, you may not duplicate the dependency in the `deps` array of `@Injectable`.
+The resolve dependency in deps will be ignored in the constructor and will be re-solved at runtime by `inject()`.
+
 Useful outside a constructor — in callbacks, factories, etc.
 
 ### `forwardRef()` — Circular dependencies
@@ -238,6 +252,21 @@ getProduct(req: Request) {
 }
 ```
 
+### Query parameters
+
+```ts
+// Renderer side:
+await client.request({ method: 'GET', path: 'users/list', query: { role: 'admin', page: '1' } });
+
+// Controller side:
+@Get('list')
+list(req: Request) {
+    const role = req.query['role'];  // 'admin'
+    const page = req.query['page'];  // '1'
+    return this.svc.findAll({ role, page: parseInt(page!) });
+}
+```
+
 ### Request body
 
 ```ts
@@ -261,10 +290,43 @@ create(req: Request, res: IResponse) {
 
 ---
 
+## Route definitions (`defineRoutes`)
+
+`defineRoutes` is the single source of truth for your routing table. It validates prefixes, detects duplicates and overlapping paths, and supports nested routes:
+
+```ts
+import { defineRoutes } from '@noxfly/noxus/main';
+
+export const routes = defineRoutes([
+    { path: 'users',  load: () => import('./modules/users/users.controller.js'), guards: [authGuard] },
+    { path: 'orders', load: () => import('./modules/orders/orders.controller.js') },
+]);
+```
+
+### Nested routes
+
+Parent routes can omit `load` and only serve as a shared prefix with inherited guards/middlewares:
+
+```ts
+export const routes = defineRoutes([
+    {
+        path: 'admin',
+        guards: [authGuard, adminGuard],
+        children: [
+            { path: 'users',    load: () => import('./admin/users.controller.js') },
+            { path: 'products', load: () => import('./admin/products.controller.js') },
+        ],
+    },
+]);
+// Produces flat routes: admin/users and admin/products, both inheriting authGuard + adminGuard.
+```
+
 ## Lazy loading
 
 This is the core mechanism for keeping startup fast. A lazy controller is never imported until an IPC request targets its prefix.
 
+Routes declared via `defineRoutes` are lazy by default. You can also register lazy routes manually:
+
 ```ts
 noxApp
     .lazy('users',    () => import('./modules/users/users.controller.js'))
@@ -451,7 +513,7 @@ class UserRepository {
 
 ```ts
 // preload.ts
-import { exposeNoxusBridge } from '@noxfly/noxus/renderer';
+import { exposeNoxusBridge } from '@noxfly/noxus/preload';
 
 exposeNoxusBridge(); // exposes window.__noxus__ to the renderer
 ```
@@ -462,12 +524,15 @@ exposeNoxusBridge(); // exposes window.__noxus__ to the renderer
 // In the renderer (Angular, React, Vue, Vanilla...)
 import { NoxRendererClient } from '@noxfly/noxus';
 
-const client = new NoxRendererClient();
+const client = new NoxRendererClient({
+    requestTimeout: 10_000, // 10s (default). Set to 0 to disable.
+});
 await client.setup(); // requests the MessagePort from main
 
 // Requests
 const users  = await client.request<User[]>({ method: 'GET',    path: 'users/list' });
 const user   = await client.request<User>  ({ method: 'GET',    path: 'users/42' });
+await client.request({ method: 'GET',    path: 'users/list',          query: { role: 'admin' } });
 await client.request({ method: 'POST',   path: 'users/create',        body: { name: 'Bob' } });
 await client.request({ method: 'PUT',    path: 'users/42',            body: { name: 'Bob Updated' } });
 await client.request({ method: 'DELETE', path: 'users/42' });
@@ -511,7 +576,7 @@ Multiple IPC requests in a single round-trip:
 
 ```ts
 const results = await client.batch([
-    { method: 'GET',  path: 'users/list' },
+    { method: 'GET',  path: 'users/list', query: { role: 'admin' } },
     { method: 'GET',  path: 'products/list' },
     { method: 'POST', path: 'orders/create', body: { ... } },
 ]);
@@ -571,3 +636,45 @@ src/
 ```
 
 Each `module/` folder is **self-contained** — the controller imports its own services directly, with no central declaration. `main.ts` only knows the lazy loading paths.
+
+---
+
+## Log level
+
+By default, all framework logs are enabled (`debug` level). Control verbosity via `bootstrapApplication`:
+
+```ts
+const noxApp = await bootstrapApplication({
+    logLevel: 'none',   // 'debug' | 'info' | 'none'
+});
+```
+
+You can also pass an array of specific levels:
+
+```ts
+bootstrapApplication({ logLevel: ['warn', 'error', 'critical'] });
+```
+
+Or change it at runtime:
+
+```ts
+import { Logger } from '@noxfly/noxus/main';
+
+Logger.setLogLevel('info');
+```
+
+---
+
+## Testing
+
+To reset the DI container between tests (avoids leaking singletons across test suites):
+
+```ts
+import { resetRootInjector } from '@noxfly/noxus/main';
+
+afterEach(() => {
+    resetRootInjector();
+});
+```
+
+This clears all bindings, singletons, and scoped instances from the root injector.

package/dist/child.d.mts

@@ -109,6 +109,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.
  */
@@ -340,4 +346,4 @@ declare namespace Logger {
     };
 }
 
-export { AppInjector, BadGatewayException, BadRequestException, ConflictException, ForbiddenException, type ForwardRefFn, ForwardReference, GatewayTimeoutException, HttpVersionNotSupportedException, type IBinding, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, type MaybeAsync, MethodNotAllowedException, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, PaymentRequiredException, RequestTimeoutException, ResponseException, RootInjector, ServiceUnavailableException, Token, type TokenKey, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, forwardRef, inject };
+export { AppInjector, BadGatewayException, BadRequestException, ConflictException, ForbiddenException, type ForwardRefFn, ForwardReference, GatewayTimeoutException, HttpVersionNotSupportedException, type IBinding, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, type MaybeAsync, MethodNotAllowedException, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, PaymentRequiredException, RequestTimeoutException, ResponseException, RootInjector, ServiceUnavailableException, Token, type TokenKey, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, forwardRef, inject, resetRootInjector };

package/dist/child.d.ts

@@ -109,6 +109,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.
  */
@@ -340,4 +346,4 @@ declare namespace Logger {
     };
 }
 
-export { AppInjector, BadGatewayException, BadRequestException, ConflictException, ForbiddenException, type ForwardRefFn, ForwardReference, GatewayTimeoutException, HttpVersionNotSupportedException, type IBinding, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, type MaybeAsync, MethodNotAllowedException, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, PaymentRequiredException, RequestTimeoutException, ResponseException, RootInjector, ServiceUnavailableException, Token, type TokenKey, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, forwardRef, inject };
+export { AppInjector, BadGatewayException, BadRequestException, ConflictException, ForbiddenException, type ForwardRefFn, ForwardReference, GatewayTimeoutException, HttpVersionNotSupportedException, type IBinding, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, type Lifetime, type LogLevel, Logger, LoopDetectedException, type MaybeAsync, MethodNotAllowedException, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, PaymentRequiredException, RequestTimeoutException, ResponseException, RootInjector, ServiceUnavailableException, Token, type TokenKey, TooManyRequestsException, type Type, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException, forwardRef, inject, resetRootInjector };