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

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,9 +513,9 @@ class UserRepository {
 
 ```ts
 // preload.ts
-import { createPreloadBridge } from '@noxfly/noxus';
+import { exposeNoxusBridge } from '@noxfly/noxus/preload';
 
-createPreloadBridge(); // exposes window.__noxus__ to the renderer
+exposeNoxusBridge(); // exposes window.__noxus__ to the renderer
 ```
 
 ### IPC client
@@ -462,15 +524,24 @@ createPreloadBridge(); // 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' });
+
+// Per-request timeout override (takes precedence over the global requestTimeout)
+const report = await client.request<Report>(
+    { method: 'GET', path: 'reports/heavy' },
+    { timeout: 60_000 }, // 60s for this specific request
+);
 ```
 
 ### Push events (main → renderer)
@@ -511,7 +582,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 +642,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.
  */
@@ -237,7 +243,7 @@ interface InjectableOptions {
  *   constructor(private url: string) {}
  * }
  */
-declare function Injectable(options?: InjectableOptions): ClassDecorator;
+declare function Injectable(options?: InjectableOptions): <T extends new (...args: any[]) => unknown>(target: T, _context: ClassDecoratorContext) => T | void;
 
 /**
  * Logger is a utility class for logging messages to the console.
@@ -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.
  */
@@ -237,7 +243,7 @@ interface InjectableOptions {
  *   constructor(private url: string) {}
  * }
  */
-declare function Injectable(options?: InjectableOptions): ClassDecorator;
+declare function Injectable(options?: InjectableOptions): <T extends new (...args: any[]) => unknown>(target: T, _context: ClassDecoratorContext) => T | void;
 
 /**
  * Logger is a utility class for logging messages to the console.
@@ -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 };