@noxfly/noxus 1.1.10 → 2.0.0

package/.github/copilot-instructions.md

@@ -0,0 +1,32 @@
+# 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.
+- 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.
+## 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.
+- 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.
+- When adjusting preload or renderer glue, ensure window.postMessage('init-port', ...) forwards both ports so the socket channel stays alive alongside the request channel.
+## 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.
+## 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.
+- 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.
+## 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.
+- 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.

package/README.md

@@ -34,19 +34,13 @@ Noxus fills that gap.
 
 ## Installation
 
-Install the package in your main process application :
+Install the package in your main process application, and in your renderer as well :
 
 ```sh
 npm i @noxfly/noxus
 ```
 
-If you have a separated renderer from the main process, you'd like to install the package as well to get typed requests/responses models, for development purposes :
-
-```sh
-npm i -D @noxfly/noxus
-```
-
-Because you only need types during development, using the `-D` argument will make this package a `devDependency`, thus won't be present on your build.
+> ⚠️ The default entry (`@noxfly/noxus`) only exposes renderer-friendly helpers and types. Import Electron main-process APIs from `@noxfly/noxus/main`.
 
 ## Basic use
 
@@ -61,7 +55,7 @@ However, you can feel free to keep both merged, this won't change anything, but
 ```ts
 // main/index.ts
 
-import { bootstrapApplication } from '@noxfly/noxus';
+import { bootstrapApplication } from '@noxfly/noxus/main';
 import { AppModule } from './modules/app.module.ts';
 import { Application } from './modules/app.service.ts';
 
@@ -81,7 +75,7 @@ main();
 ```ts
 // main/modules/app.service.ts
 
-import { IApp, Injectable, Logger } from '@noxfly/noxus';
+import { IApp, Injectable, Logger } from '@noxfly/noxus/main';
 
 @Injectable('singleton')
 export class Application implements IApp {
@@ -101,7 +95,7 @@ export class Application implements IApp {
 ```ts
 // main/modules/app.module.ts
 
-import { Module } from '@noxfly/noxus';
+import { Module } from '@noxfly/noxus/main';
 
 @Module({
     imports: [UsersModule], // import modules to be found here
@@ -116,7 +110,7 @@ export class AppModule {}
 ```ts
 // main/modules/users/users.module.ts
 
-import { Module } from '@noxfly/noxus';
+import { Module } from '@noxfly/noxus/main';
 
 @Module({
     providers: [UsersService],
@@ -128,7 +122,7 @@ export class UsersModule {}
 ```ts
 // main/modules/users/users.service.ts
 
-import { Injectable } from '@noxfly/noxus';
+import { Injectable } from '@noxfly/noxus/main';
 
 @Injectable()
 export class UsersService {
@@ -147,7 +141,7 @@ export class UsersService {
 ```ts
 // main/modules/users/users.controller.ts
 
-import { Controller, Get } from '@noxfly/noxus';
+import { Controller, Get } from '@noxfly/noxus/main';
 import { UsersService } from './users.service.ts';
 
 @Controller('users')
@@ -174,7 +168,7 @@ Further upgrades might include new decorators like `@Param()`, `@Body()` etc...
 ```ts
 // main/guards/auth.guard.ts
 
-import { IGuard, Injectable, MaybeAsync, Request } from '@noxfly/noxus';
+import { IGuard, Injectable, MaybeAsync, Request } from '@noxfly/noxus/main';
 
 @Injectable()
 export class AuthGuard implements IGuard {
@@ -200,145 +194,62 @@ We need some configuration on the preload so the main process can give the rende
 ```ts
 // main/preload.ts
 
-import { contextBridge, ipcRenderer } from 'electron/renderer';
+import { exposeNoxusBridge } from '@noxfly/noxus';
 
-// .invoke -> front sends to back
-// .on -> back sends to front
-
-type fn = (...args: any[]) => void;
-
-contextBridge.exposeInMainWorld('ipcRenderer', {
-    requestPort: () => ipcRenderer.send('gimme-my-port'),
-    
-    hereIsMyPort: () => ipcRenderer.once('port', (e, message) => {
-        e.ports[0]?.start();
-        window.postMessage({ type: 'init-port', senderId: message.senderId }, '*', [e.ports[0]!]);
-    }),
-});
+exposeNoxusBridge();
 ```
 
-> ⚠️ As the Electron documentation warns well, you should NEVER expose the whole ipcRenderer to the renderer. Expose only restricted API that your renderer could use.
+The helper uses `ipcRenderer.send('gimme-my-port')`, waits for the `'port'` response, starts both transferred `MessagePort`s, and forwards them to the renderer with `window.postMessage({ type: 'init-port', ... }, '*', [requestPort, socketPort])`. If you need to customise any channel names or the exposed property, pass `exposeNoxusBridge({ exposeAs: 'customNoxus', requestChannel: 'my-port', responseChannel: 'my-port-ready', initMessageType: 'custom-init' })`.
 
-We need to use `window.postMessage()` and not a custom callback function, otherwise the port would have been structuredCloned and would only arrive to the renderer with the `onmessage` function, and nothing else (a bit frustrating to not request, isn't it).
+> ⚠️ As the Electron documentation warns, never expose the full `ipcRenderer` object. The helper only reveals a minimal `{ requestPort }` surface under `window.noxus` by default.
 
 
 ### Setup Renderer
 
-I am personnally using Angular as renderer, so there might be some changes if you use another framework or vanilla js, but it is only about typescript's configuration and types.
+Noxus ships with a `NoxRendererClient` helper that performs the renderer bootstrap: it asks the preload bridge for a port, expects two transferable `MessagePort`s (index `0` for request/response and index `1` for socket pushes), wires both, and exposes a promise-based `request`/`batch` API plus the `RendererEventRegistry` instance.
 
-Maybe this should become a class directly available from @noxfly/noxus;
+By default it calls `window.noxus.requestPort()`—the value registered by `exposeNoxusBridge()`—but you can pass a custom bridge through the constructor options if needed.
 
-```ts
-// renderer/anyFileAtStartup.ts
+Call `await client.setup()` early in your renderer startup (for example inside the first Angular service that needs IPC). Once the promise resolves, `client.request(...)` automatically includes the negotiated `senderId`, and socket events are routed through `client.events`.
 
-import { IRequest, IResponse } from '@noxfly/noxus';
-
-interface PendingRequestHandlers<T> {
-    resolve: (value: IResponse<T>) => void;
-    reject: (reason?: IResponse<T>) => void;
-    request: IRequest;
-}
-
-// might be a singleton service
-class ElectronService {
-    private readonly bridge: any;
-    private readonly ipcRenderer: any; // if you know how to get a type, tell me
-
-    private port: MessagePort | undefined;
-    private senderId: number | undefined;
-    private readonly pendingRequests = new Map<string, PendingRequestsHandlers<any>>();
-
-    constructor() {
-        this.bridge = window as any;
-        this.ipcRenderer = this.bridge.ipcRenderer;
-
-        // when receiving the port given by the main renderer -> preload -> renderer
-        window.addEventListener('message', (event: MessageEvent) => {
-            if(event.data?.type === 'init-port' && event.ports.length > 0) {
-                this.port = event.ports[0]!;
-                this.senderId = event.data.senderId;
-                this.port.onmessage = onResponse;
-            }
-        });
-
-        ipcRenderer.requestPort();
+```ts
+// renderer/services/noxus.service.ts
+
+import { Injectable } from '@angular/core';
+import { from, Observable } from 'rxjs';
+import {
+    IBatchRequestItem,
+    IBatchResponsePayload,
+    IRequest,
+    NoxRendererClient,
+} from '@noxfly/noxus';
+
+@Injectable({ providedIn: 'root' })
+export class NoxusService extends NoxRendererClient {
+    public async init(): Promise<void> {
+        await this.setup();
     }
 
-    /**
-     * Resolve the signal-based response
-     */
-    private onResponse(event: MessageEvent): void {
-        const response: IResponse<unknown> = event.data;
-
-        if(!response || !response.requestId) {
-            console.error('Received invalid response:', response);
-            return;
-        }
-
-        const pending = this.pendingRequests.get(response.requestId);
-        
-        if(!pending) {
-            console.error(`No handler found for request ID: ${response.requestId}`);
-            return;
-        }
-        
-        this.pendingRequests.delete(response.requestId);
-
-        let fn: (response: IResponse<unknown>) => void = pending.resolve;
-
-        console.groupCollapsed(`${response.status} ${pending.request.method} /${pending.request.path}`);
-        
-        if(response.error) {
-            console.error('error message:', response.error);
-            fn = pending.reject;
-        }
-        
-        console.info('response:', response.body);
-        console.info('request:', pending.request);
-
-        console.groupEnd();
-
-        fn(response);
+    public request$<T, U = unknown>(request: Omit<IRequest<U>, 'requestId' | 'senderId'>): Observable<T> {
+        return from(this.request<T, U>(request));
     }
 
-    /**
-     * Initiate a request to the main process
-     */
-    public request<T>(request: Omit<IRequest, 'requestId' | 'senderId'>): Promise<T> {
-        return new Promise<T>((resolve, reject) => {
-            if(!this.port || !this.senderId) {
-                return reject(new Error("MessagePort is not available"));
-            }
-        
-            const req: IRequest = {
-                requestId: /* Create a random ID with the function of your choice */,
-                senderId: this.senderId,
-                ...request,
-            };
-        
-            this.pendingRequests.set(req.requestId, {
-                resolve: (response: IResponse<T>) => (response.status < 400)
-                    ? resolve(response.body as T)
-                    : reject(response);
-                reject: (response?: IResponse<T>) => reject(response),
-                request: req,
-            });
-        
-            this.port.postMessage(req);
-        });
+    public batch$<T = IBatchResponsePayload>(requests: Omit<IBatchRequestItem<unknown>, 'requestId'>[]): Observable<T> {
+        return from(this.batch(requests) as Promise<T>);
     }
 }
-```
 
-Use it like that :
+// Somewhere during app bootstrap
+await noxusService.init();
 
-```ts
-const response: User[] = await electronService.request<User[]>({
-    method: 'GET',
-    path: 'users/all',
+// Subscribe to push notifications
+const subscription = noxusService.events.subscribe('users.updated', (payload) => {
+    console.log('Users updated:', payload);
 });
 ```
 
+If you need a custom bridge (for example a different preload shape), pass it via the constructor: `super({ bridge: window.customBridge })`. The class keeps promise-based semantics so frameworks can layer their own reactive wrappers as shown above.
+
 ![Startup image](./images/screenshot-requests.png)
 
 
@@ -352,7 +263,7 @@ If you throw any of these exception, the response to the renderer will contains
 
 You can specify a message in the constructor.
 
-You throw it as follow : 
+You throw it as follow :
 ```ts
 throw new UnauthorizedException("Invalid credentials");
 throw new BadRequestException("id is missing in the body");
@@ -394,7 +305,7 @@ throw new UnavailableException();
 You can decide to inject an Injectable without passing by the constructor, as follow :
 
 ```ts
-import { inject } from '@noxfly/noxus';
+import { inject } from '@noxfly/noxus/main';
 import { MyClass } from 'src/myclass';
 
 const instance: MyClass = inject(MyClass);
@@ -407,7 +318,7 @@ Declare middlewares as follow :
 ```ts
 // renderer/middlewares.ts
 
-import { IMiddleware, Injectable, Request, IResponse, NextFunction } from '@noxfly/noxus';
+import { IMiddleware, Injectable, Request, IResponse, NextFunction } from '@noxfly/noxus/main';
 
 @Injectable()
 export class MiddlewareA implements IMiddleware {
@@ -481,6 +392,64 @@ A -> B -> C -> D -> AuthGuard -> RoleGuard -> [action] -> D -> C -> B -> A.
 
 if a middleware throw any exception or put the response status higher or equal to 400, the pipeline immediatly stops and the response is returned, weither it is done before or after the call to the next function.
 
+
+
+
+
+## Listening to events from the main process
+
+Starting from v1.2, the main process can push messages to renderer processes without the request/response flow.
+
+```ts
+// main/users/users.controller.ts
+import { Controller, Post, Request, NoxSocket } from '@noxfly/noxus/main';
+
+@Controller('users')
+export class UsersController {
+    constructor(private readonly socket: NoxSocket) {}
+
+    @Post('create')
+    public async create(request: Request): Promise<void> {
+        const payload = { nickname: request.body.nickname };
+
+        this.socket.emitToRenderer(request.event.senderId, 'users:created', payload);
+        // or broadcast to every connected renderer: this.socket.emit('users:created', payload);
+    }
+}
+```
+
+On the renderer side, leverage the `RendererEventRegistry` to register and clean up listeners. The registry only handles push events, so it plays nicely with the existing request handling code above.
+
+```ts
+import { RendererEventRegistry, RendererEventSubscription } from '@noxfly/noxus';
+
+private readonly events = new RendererEventRegistry();
+
+constructor() {
+    // ... after the MessagePort is ready
+    this.port.onmessage = (event) => {
+        if(this.events.tryDispatchFromMessageEvent(event)) {
+            return;
+        }
+
+        this.onMessage(event); // existing request handling
+    };
+}
+
+public onUsersCreated(): RendererEventSubscription {
+    return this.events.subscribe('users:created', (payload) => {
+        // react to the event
+    });
+}
+
+public teardown(): void {
+    this.events.clear();
+}
+```
+
+
+
+
 ## Contributing
 
 1. Clone the repo