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

package/src/app.ts

@@ -1,217 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { app, BrowserWindow, ipcMain, MessageChannelMain } from 'electron/main';
-import { Injectable } from './decorators/injectable.decorator';
-import { Middleware } from './decorators/middleware.decorator';
-import { inject } from './DI/app-injector';
-import { InjectorExplorer } from './DI/injector-explorer';
-import { IResponse, Request } from './request';
-import { Router } from './router';
-import { NoxSocket } from './socket';
-import { Logger } from './utils/logger';
-import { Type } from './utils/types';
-import { WindowManager } from './window/window-manager';
-import { Guard } from "src/main";
-
-/**
- * Your application service should implement IApp.
- * Noxus calls these lifecycle methods at the appropriate time.
- *
- * Unlike v2, IApp no longer receives a BrowserWindow in onReady.
- * Use the injected WindowManager instead — it is more flexible and
- * does not couple the lifecycle to a single pre-created window.
- *
- * @example
- * @Injectable({ lifetime: 'singleton', deps: [WindowManager, MyService] })
- * class AppService implements IApp {
- *   constructor(private wm: WindowManager, private svc: MyService) {}
- *
- *   async onReady() {
- *     const win = await this.wm.createSplash({ webPreferences: { preload: ... } });
- *     win.loadFile('index.html');
- *   }
- *
- *   async onActivated() { ... }
- *   async dispose() { ... }
- * }
- */
-export interface IApp {
-    dispose(): Promise<void>;
-    onReady(): Promise<void>;
-    onActivated(): Promise<void>;
-}
-
-@Injectable({ lifetime: 'singleton', deps: [Router, NoxSocket, WindowManager] })
-export class NoxApp {
-    private appService: IApp | undefined;
-
-    private readonly router = inject(Router);
-    private readonly socket = inject(NoxSocket);
-    public readonly windowManager = inject(WindowManager);
-
-    // -------------------------------------------------------------------------
-    // Initialisation
-    // -------------------------------------------------------------------------
-
-    public async init(): Promise<this> {
-        ipcMain.on('gimme-my-port', this.giveTheRendererAPort.bind(this));
-        app.once('activate', this.onAppActivated.bind(this));
-        app.once('window-all-closed', this.onAllWindowsClosed.bind(this));
-        console.log('');
-        return this;
-    }
-
-    // -------------------------------------------------------------------------
-    // Public API
-    // -------------------------------------------------------------------------
-
-    /**
-     * Registers a lazy route. The file behind this prefix is dynamically
-     * imported on the first IPC request that targets it.
-     *
-     * The import function should NOT statically reference heavy modules —
-     * the whole point is to defer their loading.
-     *
-     * @example
-     * noxApp.lazy('auth', () => import('./modules/auth/auth.controller.js'));
-     * noxApp.lazy('reporting', () => import('./modules/reporting/index.js'));
-     */
-    public lazy(
-        pathPrefix: string,
-        load: () => Promise<unknown>,
-        guards: Guard[] = [],
-        middlewares: Middleware[] = [],
-    ): this {
-        this.router.registerLazyRoute(pathPrefix, load, guards, middlewares);
-        return this;
-    }
-
-    /**
-     * Eagerly loads a set of modules (controllers + services) before start().
-     * Use this for modules that provide services needed by your IApp.onReady().
-     *
-     * All imports run in parallel; DI is flushed with the two-phase guarantee.
-     */
-    public async load(importFns: Array<() => Promise<unknown>>): Promise<this> {
-        InjectorExplorer.beginAccumulate();
-        await Promise.all(importFns.map((fn) => fn()));
-        InjectorExplorer.flushAccumulated();
-        return this;
-    }
-
-    /**
-     * Registers a global middleware applied to every route.
-     */
-    public use(middleware: Middleware): this {
-        this.router.defineRootMiddleware(middleware);
-        return this;
-    }
-
-    /**
-     * Sets the application service (implements IApp) that receives lifecycle events.
-     * @param appClass - Class decorated with @Injectable that implements IApp.
-     */
-    public configure(appClass: Type<IApp>): this {
-        this.appService = inject(appClass);
-        return this;
-    }
-
-    /**
-     * Calls IApp.onReady(). Should be called after configure() and any lazy()
-     * registrations are set up.
-     */
-    public start(): this {
-        this.appService?.onReady();
-        return this;
-    }
-
-    // -------------------------------------------------------------------------
-    // IPC
-    // -------------------------------------------------------------------------
-
-    private readonly onRendererMessage = async (event: Electron.MessageEvent): Promise<void> => {
-        const { senderId, requestId, path, method, body }: import('./request').IRequest = event.data;
-        const channels = this.socket.get(senderId);
-
-        if (!channels) {
-            Logger.error(`No message channel found for sender ID: ${senderId}`);
-            return;
-        }
-
-        try {
-            const request = new Request(event, senderId, requestId, method, path, body);
-            const response = await this.router.handle(request);
-            channels.request.port1.postMessage(response);
-        }
-        catch (err: unknown) {
-            const response: IResponse = {
-                requestId,
-                status: 500,
-                body: null,
-                error: err instanceof Error ? err.message : 'Internal Server Error',
-            };
-            channels.request.port1.postMessage(response);
-        }
-    };
-
-    private giveTheRendererAPort(event: Electron.IpcMainInvokeEvent): void {
-        const senderId = event.sender.id;
-
-        if (this.socket.get(senderId)) {
-            this.shutdownChannel(senderId);
-        }
-
-        const requestChannel = new MessageChannelMain();
-        const socketChannel = new MessageChannelMain();
-
-        requestChannel.port1.on('message', this.onRendererMessage);
-        requestChannel.port1.start();
-        socketChannel.port1.start();
-
-        event.sender.once('destroyed', () => this.shutdownChannel(senderId));
-
-        this.socket.register(senderId, requestChannel, socketChannel);
-        event.sender.postMessage('port', { senderId }, [requestChannel.port2, socketChannel.port2]);
-    }
-
-    // -------------------------------------------------------------------------
-    // Lifecycle
-    // -------------------------------------------------------------------------
-
-    private onAppActivated(): void {
-        if (process.platform === 'darwin' && BrowserWindow.getAllWindows().length === 0) {
-            this.appService?.onActivated();
-        }
-    }
-
-    private async onAllWindowsClosed(): Promise<void> {
-        for (const senderId of this.socket.getSenderIds()) {
-            this.shutdownChannel(senderId);
-        }
-
-        Logger.info('All windows closed, shutting down application...');
-        await this.appService?.dispose();
-
-        if (process.platform !== 'darwin') app.quit();
-    }
-
-    private shutdownChannel(channelSenderId: number): void {
-        const channels = this.socket.get(channelSenderId);
-
-        if (!channels) {
-            return;
-        }
-
-        channels.request.port1.off('message', this.onRendererMessage);
-        channels.request.port1.close();
-        channels.request.port2.close();
-        channels.socket.port1.close();
-        channels.socket.port2.close();
-
-        this.socket.unregister(channelSenderId);
-    }
-}

package/src/bootstrap.ts

@@ -1,108 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { app } from 'electron/main';
-import { NoxApp } from './app';
-import { inject, RootInjector } from './DI/app-injector';
-import { InjectorExplorer } from './DI/injector-explorer';
-import { TokenKey } from './DI/token';
-import { RouteDefinition } from "src/routes";
-
-/**
- * A singleton value override: provides an already-constructed instance
- * for a given token, bypassing the DI factory.
- *
- * Useful for injecting external singletons (e.g. a database connection,
- * a logger already configured, a third-party SDK wrapper) that cannot
- * or should not be constructed by the DI container.
- *
- * @example
- * { token: MikroORM, useValue: await MikroORM.init(config) }
- * { token: DB_URL,   useValue: process.env.DATABASE_URL }
- */
-export interface SingletonOverride<T = unknown> {
-    token: TokenKey<T>;
-    useValue: T;
-}
-
-/**
- * Configuration object for bootstrapApplication.
- */
-export interface BootstrapConfig {
-    /**
-     * Application routing table, produced by defineRoutes().
-     * All lazy routes are registered before the app starts.
-     */
-    routes?: RouteDefinition[];
-
-    /**
-     * Pre-built singleton instances to inject into the DI container
-     * before the application starts.
-     *
-     * This replaces the v2 module/provider declaration pattern for
-     * external singletons.
-     *
-     * @example
-     * singletons: [
-     *   { token: MikroORM, useValue: await MikroORM.init(ormConfig) },
-     *   { token: DB_URL,   useValue: process.env.DATABASE_URL! },
-     * ]
-     */
-    singletons?: SingletonOverride[];
-
-    /**
-     * Controllers and services to eagerly load before NoxApp.start() is called.
-     * Each entry is a dynamic import function — files are imported in parallel.
-     *
-     * Use this only for things needed at startup (e.g. if your IApp service
-     * depends on a service in an otherwise lazy module).
-     *
-     * Everything else should be registered via noxApp.lazy().
-     *
-     * @example
-     * eagerLoad: [
-     *   () => import('./modules/auth/auth.controller.js'),
-     * ]
-     */
-    eagerLoad?: Array<() => Promise<unknown>>;
-}
-
-/**
- * Bootstraps the Noxus application.
- */
-export async function bootstrapApplication(config: BootstrapConfig = {}): Promise<NoxApp> {
-    await app.whenReady();
-
-    // Build override map for the DI flush phase
-    const overrides = new Map<TokenKey, unknown>();
-    for (const { token, useValue } of config.singletons ?? []) {
-        overrides.set(token, useValue);
-        // Pre-register the binding so the injector knows the token exists
-        RootInjector.singletons.set(token as any, useValue);
-    }
-
-    // Flush all classes enqueued by decorators at import time (two-phase)
-    InjectorExplorer.processPending(overrides);
-
-    // Resolve core framework singletons
-    const noxApp = inject(NoxApp);
-
-    // Register routes from the routing table
-    if (config.routes?.length) {
-        for (const route of config.routes) {
-            noxApp.lazy(route.path, route.load, route.guards, route.middlewares);
-        }
-    }
-
-    // Eagerly load optional modules
-    if (config.eagerLoad?.length) {
-        await noxApp.load(config.eagerLoad);
-    }
-
-    await noxApp.init();
-
-    return noxApp;
-}

package/src/decorators/controller.decorator.ts

@@ -1,58 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { InjectorExplorer } from '../DI/injector-explorer';
-import { TokenKey } from '../DI/token';
-import { Type } from '../utils/types';
-
-export interface ControllerOptions {
-    /**
-     * Explicit constructor dependencies.
-     */
-    deps?: ReadonlyArray<TokenKey>;
-}
-
-export interface IControllerMetadata {
-    deps: ReadonlyArray<TokenKey>;
-}
-
-const controllerMetaMap = new WeakMap<object, IControllerMetadata>();
-
-/**
- * Marks a class as a Noxus controller.
- * Controllers are always scope-scoped injectables.
- * The route prefix and guards/middlewares are declared in defineRoutes(), not here.
- *
- * @example
- * @Controller({ deps: [UserService] })
- * export class UserController {
- *   constructor(private svc: UserService) {}
- *
- *   @Get('byId/:userId')
- *   getUserById(req: Request) { ... }
- * }
- */
-export function Controller(options: ControllerOptions = {}): ClassDecorator {
-    return (target) => {
-        const meta: IControllerMetadata = {
-            deps: options.deps ?? [],
-        };
-
-        controllerMetaMap.set(target, meta);
-
-        InjectorExplorer.enqueue({
-            key: target as unknown as Type<unknown>,
-            implementation: target as unknown as Type<unknown>,
-            lifetime: 'scope',
-            deps: options.deps ?? [],
-            isController: true,
-        });
-    };
-}
-
-export function getControllerMetadata(target: object): IControllerMetadata | undefined {
-    return controllerMetaMap.get(target);
-}

package/src/decorators/guards.decorator.ts

@@ -1,15 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Request } from '../request';
-import { MaybeAsync } from '../utils/types';
-
-/**
- * A guard decides whether an incoming request should reach the handler.
- * Implement this interface and pass the class to @Controller({ guards }) or @Get('path', { guards }).
- */
-
-export type Guard = (request: Request) => MaybeAsync<boolean>;

package/src/decorators/injectable.decorator.ts

@@ -1,81 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Lifetime } from '../DI/app-injector';
-import { InjectorExplorer } from '../DI/injector-explorer';
-import { Token, TokenKey } from '../DI/token';
-import { Type } from '../utils/types';
-
-export interface InjectableOptions {
-    /**
-     * Lifetime of this injectable.
-     * @default 'scope'
-     */
-    lifetime?: Lifetime;
-
-    /**
-     * Explicit list of constructor dependencies, in the same order as the constructor parameters.
-     * Each entry is either a class constructor or a Token created with token().
-     *
-     * This replaces reflect-metadata / emitDecoratorMetadata entirely.
-     *
-     * @example
-     * @Injectable({ lifetime: 'singleton', deps: [MyRepo, DB_URL] })
-     * class MyService {
-     *   constructor(private repo: MyRepo, private dbUrl: string) {}
-     * }
-     */
-    deps?: ReadonlyArray<TokenKey>;
-}
-
-/**
- * Marks a class as injectable into the Noxus DI container.
- *
- * Unlike the v2 @Injectable, this decorator:
- * - Does NOT require reflect-metadata or emitDecoratorMetadata.
- * - Requires you to declare deps explicitly when the class has constructor parameters.
- * - Supports standalone usage — no module declaration needed.
- *
- * @example
- * // No dependencies
- * @Injectable()
- * class Logger {}
- *
- * // With dependencies
- * @Injectable({ lifetime: 'singleton', deps: [Logger, MyRepo] })
- * class MyService {
- *   constructor(private logger: Logger, private repo: MyRepo) {}
- * }
- *
- * // With a named token
- * const DB_URL = token<string>('DB_URL');
- *
- * @Injectable({ deps: [DB_URL] })
- * class DbService {
- *   constructor(private url: string) {}
- * }
- */
-export function Injectable(options: InjectableOptions = {}): ClassDecorator {
-    const { lifetime = 'scope', deps = [] } = options;
-
-    return (target) => {
-        if (typeof target !== 'function' || !target.prototype) {
-            throw new Error(`@Injectable can only be applied to classes, not ${typeof target}`);
-        }
-
-        const key = target as unknown as Type<unknown>;
-
-        InjectorExplorer.enqueue({
-            key,
-            implementation: key,
-            lifetime,
-            deps,
-            isController: false,
-        });
-    };
-}
-
-export { Token, TokenKey };

package/src/decorators/method.decorator.ts

@@ -1,66 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Guard } from './guards.decorator';
-import { Middleware } from './middleware.decorator';
-
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'BATCH';
-export type AtomicHttpMethod = Exclude<HttpMethod, 'BATCH'>;
-
-const ATOMIC_METHODS = new Set<AtomicHttpMethod>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
-export function isAtomicHttpMethod(m: unknown): m is AtomicHttpMethod {
-    return typeof m === 'string' && ATOMIC_METHODS.has(m as AtomicHttpMethod);
-}
-
-export interface IRouteOptions {
-    /**
-     * Guards specific to this route (merged with controller guards).
-     */
-    guards?: Guard[];
-    /**
-     * Middlewares specific to this route (merged with controller middlewares).
-     */
-    middlewares?: Middleware[];
-}
-
-export interface IRouteMetadata {
-    method: HttpMethod;
-    path: string;
-    handler: string;
-    guards: Guard[];
-    middlewares: Middleware[];
-}
-
-const routeMetaMap = new WeakMap<object, IRouteMetadata[]>();
-
-function createRouteDecorator(verb: HttpMethod) {
-    return (path: string, options: IRouteOptions = {}): MethodDecorator => {
-        return (target, propertyKey) => {
-            const ctor = target.constructor;
-            const existing: IRouteMetadata[] = routeMetaMap.get(ctor) ?? [];
-
-            existing.push({
-                method: verb,
-                path: (path ?? '').trim().replace(/^\/|\/$/g, ''),
-                handler: propertyKey as string,
-                guards: options.guards ?? [],
-                middlewares: options.middlewares ?? [],
-            });
-
-            routeMetaMap.set(ctor, existing);
-        };
-    };
-}
-
-export function getRouteMetadata(target: object): IRouteMetadata[] {
-    return routeMetaMap.get(target) ?? [];
-}
-
-export const Get    = createRouteDecorator('GET');
-export const Post   = createRouteDecorator('POST');
-export const Put    = createRouteDecorator('PUT');
-export const Patch  = createRouteDecorator('PATCH');
-export const Delete = createRouteDecorator('DELETE');

package/src/decorators/middleware.decorator.ts

@@ -1,15 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { IResponse, Request } from '../request';
-import { MaybeAsync } from '../utils/types';
-
-/**
- * A middleware intercepts requests before they reach guards and the handler.
- * Implement this interface and pass the class to @Controller({ middlewares }) or per-route options.
- */
-export type Middleware = (request: Request, response: IResponse, next: NextFunction) => MaybeAsync<void>;
-export type NextFunction = () => Promise<void>;

package/src/exceptions.ts

@@ -1,57 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-export class ResponseException extends Error {
-    public readonly status: number = 0;
-
-    constructor(message?: string);
-    constructor(statusCode?: number, message?: string);
-    constructor(statusOrMessage?: number | string, message?: string) {
-        let statusCode: number | undefined;
-        
-        if(typeof statusOrMessage === 'number') {
-            statusCode = statusOrMessage;
-        }
-        else if(typeof statusOrMessage === 'string') {
-            message = statusOrMessage;
-        }
-
-        super(message ?? "");
-
-        if(statusCode !== undefined) {
-            this.status = statusCode;
-        }
-        
-        this.name = this.constructor.name
-            .replace(/([A-Z])/g, ' $1');
-    }
-}
-
-// 4XX
-export class BadRequestException extends ResponseException { public override readonly status = 400; }
-export class UnauthorizedException extends ResponseException { public override readonly status = 401; }
-export class PaymentRequiredException extends ResponseException { public override readonly status = 402; }
-export class ForbiddenException extends ResponseException { public override readonly status = 403; }
-export class NotFoundException extends ResponseException { public override readonly status = 404; }
-export class MethodNotAllowedException extends ResponseException { public override readonly status = 405; }
-export class NotAcceptableException extends ResponseException { public override readonly status = 406; }
-export class RequestTimeoutException extends ResponseException { public override readonly status = 408; }
-export class ConflictException extends ResponseException { public override readonly status = 409; }
-export class UpgradeRequiredException extends ResponseException { public override readonly status = 426; }
-export class TooManyRequestsException extends ResponseException { public override readonly status = 429; }
-// 5XX
-export class InternalServerException extends ResponseException { public override readonly status = 500; }
-export class NotImplementedException extends ResponseException { public override readonly status = 501; }
-export class BadGatewayException extends ResponseException { public override readonly status = 502; }
-export class ServiceUnavailableException extends ResponseException { public override readonly status = 503; }
-export class GatewayTimeoutException extends ResponseException { public override readonly status = 504; }
-export class HttpVersionNotSupportedException extends ResponseException { public override readonly status = 505; }
-export class VariantAlsoNegotiatesException extends ResponseException { public override readonly status = 506; }
-export class InsufficientStorageException extends ResponseException { public override readonly status = 507; }
-export class LoopDetectedException extends ResponseException { public override readonly status = 508; }
-export class NotExtendedException extends ResponseException { public override readonly status = 510; }
-export class NetworkAuthenticationRequiredException extends ResponseException { public override readonly status = 511; }
-export class NetworkConnectTimeoutException extends ResponseException { public override readonly status = 599; }

package/src/index.ts

@@ -1,13 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- *
- * Entry point for renderer process and preload consumers.
- */
-
-export * from './request';
-export * from './preload-bridge';
-export * from './renderer-events';
-export * from './renderer-client';
-export type { HttpMethod, AtomicHttpMethod } from './decorators/method.decorator';

package/src/main.ts

@@ -1,26 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- *
- * Entry point for Electron main-process consumers.
- */
-
-export * from './DI/app-injector';
-export * from './DI/token';
-export * from './router';
-export * from './app';
-export * from './bootstrap';
-export * from './exceptions';
-export * from './decorators/middleware.decorator';
-export * from './decorators/guards.decorator';
-export * from './decorators/controller.decorator';
-export * from './decorators/injectable.decorator';
-export * from './decorators/method.decorator';
-export * from './utils/logger';
-export * from './utils/types';
-export * from './utils/forward-ref';
-export * from './request';
-export * from './socket';
-export * from './window/window-manager';
-export * from './routes';

package/src/non-electron-process.ts

@@ -1,22 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-/**
- * Entry point for nodeJS non-electron process consumers.
- * For instance, if main process creates a child process that
- * wants to use Logger and DI.
- * Child processes must not try to communicate with the renderer
- * process.
- * order of exports here matters and can affect module resolution.
- * Please be cautious when modifying.
- */
-
-export * from './DI/app-injector';
-export * from './exceptions';
-export * from './decorators/injectable.decorator';
-export * from './utils/logger';
-export * from './utils/types';
-export * from './utils/forward-ref';