@noxfly/noxus 3.0.0-dev.0 → 3.0.0-dev.10

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,26 +513,35 @@ 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
 
 ```ts
 // In the renderer (Angular, React, Vue, Vanilla...)
-import { NoxusClient } from '@noxfly/noxus';
+import { NoxRendererClient } from '@noxfly/noxus';
 
-const client = new NoxusClient();
-await client.connect();
+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.get<User[]>('users/list');
-const user  = await client.get<User>('users/42');
-await client.post('users/create', { name: 'Bob' });
-await client.put('users/42', { name: 'Bob Updated' });
-await client.delete('users/42');
+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)
@@ -495,9 +566,12 @@ class NotificationService {
 On the renderer side:
 
 ```ts
-client.on('notification', (payload) => {
+const sub = client.events.subscribe<INotification>('notification', (payload) => {
     console.log(payload.message);
 });
+
+// Unsubscribe when done
+sub.unsubscribe();
 ```
 
 ---
@@ -508,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: { ... } },
 ]);
@@ -568,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

@@ -1,11 +1,125 @@
-import { L as Lifetime, a as TokenKey } from './app-injector-Bz3Upc0y.mjs';
-export { A as AppInjector, F as ForwardRefFn, b as ForwardReference, I as IBinding, M as MaybeAsync, R as RootInjector, c as Token, T as Type, f as forwardRef, i as inject } from './app-injector-Bz3Upc0y.mjs';
-
 /**
  * @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>;
+
+
+/**
+ * A DI token uniquely identifies a dependency.
+ * It can wrap a class (Type<T>) or be a named symbol token.
+ *
+ * Using tokens instead of reflect-metadata means dependencies are
+ * declared explicitly — no magic type inference, no emitDecoratorMetadata.
+ *
+ * @example
+ * // Class token (most common)
+ * const MY_SERVICE = token(MyService);
+ *
+ * // Named symbol token (for interfaces or non-class values)
+ * const DB_URL = token<string>('DB_URL');
+ */
+declare class Token<T> {
+    readonly target: Type<T> | string;
+    readonly description: string;
+    constructor(target: Type<T> | string);
+    toString(): string;
+}
+/**
+ * The key used to look up a class token in the registry.
+ * For class tokens, the key is the class constructor itself.
+ * For named tokens, the key is the Token instance.
+ */
+type TokenKey<T = unknown> = Type<T> | Token<T>;
+
+
+/**
+ * Lifetime of a binding in the DI container.
+ * - singleton: created once, shared for the lifetime of the app.
+ * - scope:     created once per request scope.
+ * - transient: new instance every time it is resolved.
+ */
+type Lifetime = 'singleton' | 'scope' | 'transient';
+/**
+ * Internal representation of a registered binding.
+ */
+interface IBinding<T = unknown> {
+    lifetime: Lifetime;
+    implementation: Type<T>;
+    /** Explicit constructor dependencies, declared by the class itself. */
+    deps: ReadonlyArray<TokenKey>;
+    instance?: T;
+}
+/**
+ * AppInjector is the core DI container.
+ * It no longer uses reflect-metadata — all dependency information
+ * comes from explicitly declared `deps` arrays on each binding.
+ */
+declare class AppInjector {
+    readonly name: string | null;
+    readonly bindings: Map<Type<unknown> | Token<unknown>, IBinding<unknown>>;
+    readonly singletons: Map<Type<unknown> | Token<unknown>, unknown>;
+    readonly scoped: Map<Type<unknown> | Token<unknown>, unknown>;
+    constructor(name?: string | null);
+    /**
+     * Creates a child scope for per-request lifetime resolution.
+     */
+    createScope(): AppInjector;
+    /**
+     * Registers a binding explicitly.
+     */
+    register<T>(key: TokenKey<T>, implementation: Type<T>, lifetime: Lifetime, deps?: ReadonlyArray<TokenKey>): void;
+    /**
+     * Resolves a dependency by token or class reference.
+     */
+    resolve<T>(target: TokenKey<T> | ForwardReference<T>): T;
+    private _resolveForwardRef;
+    private _instantiate;
+}
+/**
+ * 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.
+ */
+declare function inject<T>(t: TokenKey<T> | ForwardReference<T>): T;
+
 declare class ResponseException extends Error {
     readonly status: number;
     constructor(message?: string);
@@ -232,4 +346,4 @@ declare namespace Logger {
     };
 }
 
-export { BadGatewayException, BadRequestException, ConflictException, ForbiddenException, GatewayTimeoutException, HttpVersionNotSupportedException, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, Lifetime, type LogLevel, Logger, LoopDetectedException, MethodNotAllowedException, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, PaymentRequiredException, RequestTimeoutException, ResponseException, ServiceUnavailableException, TokenKey, TooManyRequestsException, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException };
+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

@@ -1,11 +1,125 @@
-import { L as Lifetime, a as TokenKey } from './app-injector-Bz3Upc0y.js';
-export { A as AppInjector, F as ForwardRefFn, b as ForwardReference, I as IBinding, M as MaybeAsync, R as RootInjector, c as Token, T as Type, f as forwardRef, i as inject } from './app-injector-Bz3Upc0y.js';
-
 /**
  * @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>;
+
+
+/**
+ * A DI token uniquely identifies a dependency.
+ * It can wrap a class (Type<T>) or be a named symbol token.
+ *
+ * Using tokens instead of reflect-metadata means dependencies are
+ * declared explicitly — no magic type inference, no emitDecoratorMetadata.
+ *
+ * @example
+ * // Class token (most common)
+ * const MY_SERVICE = token(MyService);
+ *
+ * // Named symbol token (for interfaces or non-class values)
+ * const DB_URL = token<string>('DB_URL');
+ */
+declare class Token<T> {
+    readonly target: Type<T> | string;
+    readonly description: string;
+    constructor(target: Type<T> | string);
+    toString(): string;
+}
+/**
+ * The key used to look up a class token in the registry.
+ * For class tokens, the key is the class constructor itself.
+ * For named tokens, the key is the Token instance.
+ */
+type TokenKey<T = unknown> = Type<T> | Token<T>;
+
+
+/**
+ * Lifetime of a binding in the DI container.
+ * - singleton: created once, shared for the lifetime of the app.
+ * - scope:     created once per request scope.
+ * - transient: new instance every time it is resolved.
+ */
+type Lifetime = 'singleton' | 'scope' | 'transient';
+/**
+ * Internal representation of a registered binding.
+ */
+interface IBinding<T = unknown> {
+    lifetime: Lifetime;
+    implementation: Type<T>;
+    /** Explicit constructor dependencies, declared by the class itself. */
+    deps: ReadonlyArray<TokenKey>;
+    instance?: T;
+}
+/**
+ * AppInjector is the core DI container.
+ * It no longer uses reflect-metadata — all dependency information
+ * comes from explicitly declared `deps` arrays on each binding.
+ */
+declare class AppInjector {
+    readonly name: string | null;
+    readonly bindings: Map<Type<unknown> | Token<unknown>, IBinding<unknown>>;
+    readonly singletons: Map<Type<unknown> | Token<unknown>, unknown>;
+    readonly scoped: Map<Type<unknown> | Token<unknown>, unknown>;
+    constructor(name?: string | null);
+    /**
+     * Creates a child scope for per-request lifetime resolution.
+     */
+    createScope(): AppInjector;
+    /**
+     * Registers a binding explicitly.
+     */
+    register<T>(key: TokenKey<T>, implementation: Type<T>, lifetime: Lifetime, deps?: ReadonlyArray<TokenKey>): void;
+    /**
+     * Resolves a dependency by token or class reference.
+     */
+    resolve<T>(target: TokenKey<T> | ForwardReference<T>): T;
+    private _resolveForwardRef;
+    private _instantiate;
+}
+/**
+ * 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.
+ */
+declare function inject<T>(t: TokenKey<T> | ForwardReference<T>): T;
+
 declare class ResponseException extends Error {
     readonly status: number;
     constructor(message?: string);
@@ -232,4 +346,4 @@ declare namespace Logger {
     };
 }
 
-export { BadGatewayException, BadRequestException, ConflictException, ForbiddenException, GatewayTimeoutException, HttpVersionNotSupportedException, Injectable, type InjectableOptions, InsufficientStorageException, InternalServerException, Lifetime, type LogLevel, Logger, LoopDetectedException, MethodNotAllowedException, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, PaymentRequiredException, RequestTimeoutException, ResponseException, ServiceUnavailableException, TokenKey, TooManyRequestsException, UnauthorizedException, UpgradeRequiredException, VariantAlsoNegotiatesException };
+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 };