@noxfly/noxus 2.4.0 → 3.0.0-dev.0

package/src/DI/app-injector.ts

@@ -4,159 +4,148 @@
  * @author NoxFly
  */
 
-import 'reflect-metadata';
-import { INJECT_METADATA_KEY } from 'src/decorators/inject.decorator';
-import { InternalServerException } from 'src/exceptions';
-import { ForwardReference } from 'src/utils/forward-ref';
-import { Type } from 'src/utils/types';
+import { ForwardReference } from '../utils/forward-ref';
+import { Type } from '../utils/types';
+import { Token, TokenKey } from './token';
 
 /**
- * Represents a lifetime of a binding in the dependency injection system.
- * It can be one of the following:
- * - 'singleton': The instance is created once and shared across the application.
- * - 'scope': The instance is created once per scope (e.g., per request).
- * - 'transient': A new instance is created every time it is requested.
+ * 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.
  */
 export type Lifetime = 'singleton' | 'scope' | 'transient';
 
 /**
- * Represents a binding in the dependency injection system.
- * It contains the lifetime of the binding, the implementation type, and optionally an instance.
+ * Internal representation of a registered binding.
  */
-export interface IBinding {
+export interface IBinding<T = unknown> {
     lifetime: Lifetime;
-    implementation: Type<unknown>;
-    instance?: InstanceType<Type<unknown>>;
+    implementation: Type<T>;
+    /** Explicit constructor dependencies, declared by the class itself. */
+    deps: ReadonlyArray<TokenKey>;
+    instance?: T;
+}
+
+function keyOf<T>(k: TokenKey<T>): Type<T> | Token<T> {
+    return k;
 }
 
 /**
- * AppInjector is the root dependency injection container.
- * It is used to register and resolve dependencies in the application.
- * It supports different lifetimes for dependencies:
- * This should not be manually instantiated, outside of the framework.
- * Use the `RootInjector` instance instead.
+ * AppInjector is the core DI container.
+ * It no longer uses reflect-metadata — all dependency information
+ * comes from explicitly declared `deps` arrays on each binding.
  */
 export class AppInjector {
-    public bindings = new Map<Type<unknown>, IBinding>();
-    public singletons = new Map<Type<unknown>, InstanceType<Type<unknown>>>();
-    public scoped = new Map<Type<unknown>, InstanceType<Type<unknown>>>();
+    public readonly bindings = new Map<Type<unknown> | Token<unknown>, IBinding<unknown>>();
+    public readonly singletons = new Map<Type<unknown> | Token<unknown>, unknown>();
+    public readonly scoped = new Map<Type<unknown> | Token<unknown>, unknown>();
 
-    constructor(
-        public readonly name: string | null = null,
-    ) {}
+    constructor(public readonly name: string | null = null) {}
 
     /**
-     * Typically used to create a dependency injection scope
-     * at the "scope" level (i.e., per-request lifetime).
-     *
-     * SHOULD NOT BE USED by anything else than the framework itself.
+     * Creates a child scope for per-request lifetime resolution.
      */
     public createScope(): AppInjector {
         const scope = new AppInjector();
-        scope.bindings = this.bindings; // pass injectable declarations
-        scope.singletons = this.singletons; // share parent's singletons to avoid recreating them
-        // do not keep parent's scoped instances
+        (scope as any).bindings = this.bindings;
+        (scope as any).singletons = this.singletons;
         return scope;
     }
 
     /**
-     * Called when resolving a dependency,
-     * i.e., retrieving the instance of a given class.
+     * Registers a binding explicitly.
      */
-    public resolve<T>(target: Type<T> | ForwardReference<T>): T {
-        if (target instanceof ForwardReference) {
-            return new Proxy({}, {
-                get: (obj, prop, receiver) => {
-                    const realType = target.forwardRefFn();
-                    const instance = this.resolve(realType) as any;
-                    const value = Reflect.get(instance, prop, receiver);
-                    
-                    return typeof value === 'function' ? value.bind(instance) : value;
-                },
-                set: (obj, prop, value, receiver) => {
-                     const realType = target.forwardRefFn();
-                     const instance = this.resolve(realType) as any;
-                     return Reflect.set(instance, prop, value, receiver);
-                },
-                getPrototypeOf: () => {
-                     const realType = target.forwardRefFn();
-                     return (realType as any).prototype;
-                }
-            }) as T;
+    public register<T>(
+        key: TokenKey<T>,
+        implementation: Type<T>,
+        lifetime: Lifetime,
+        deps: ReadonlyArray<TokenKey> = [],
+    ): void {
+        const k = keyOf(key) as TokenKey<unknown>;
+        if (!this.bindings.has(k)) {
+            this.bindings.set(k, { lifetime, implementation: implementation as Type<unknown>, deps });
         }
+    }
 
-        const binding = this.bindings.get(target);
-
-        if(!binding) {
-            if(target === undefined) {
-                throw new InternalServerException(
-                    "Failed to resolve a dependency injection : Undefined target type.\n"
-                    + "This might be caused by a circular dependency."
-                );
-            }
+    /**
+     * Resolves a dependency by token or class reference.
+     */
+    public resolve<T>(target: TokenKey<T> | ForwardReference<T>): T {
+        if (target instanceof ForwardReference) {
+            return this._resolveForwardRef(target);
+        }
 
-            const name = target.name || "unknown";
+        const k = keyOf(target) as TokenKey<unknown>;
+        const binding = this.bindings.get(k);
 
-            throw new InternalServerException(
-                `Failed to resolve a dependency injection : No binding for type ${name}.\n`
-                + `Did you forget to use @Injectable() decorator ?`
+        if (!binding) {
+            const name = target instanceof Token ? target.description : (target as Type<unknown>).name ?? 'unknown';
+            throw new Error(
+                `[Noxus DI] No binding found for "${name}".\n`
+                + `Did you forget to declare it in @Injectable({ deps }) or in bootstrapApplication({ singletons })?`,
             );
         }
 
-        switch(binding.lifetime) {
+        switch (binding.lifetime) {
             case 'transient':
-                return this.instantiate(binding.implementation) as T;
+                return this._instantiate(binding) as T;
 
             case 'scope': {
-                if(this.scoped.has(target)) {
-                    return this.scoped.get(target) as T;
-                }
-
-                const instance = this.instantiate(binding.implementation);
-                this.scoped.set(target, instance);
-
-                return instance as T;
+                if (this.scoped.has(k)) return this.scoped.get(k) as T;
+                const inst = this._instantiate(binding);
+                this.scoped.set(k, inst);
+                return inst as T;
             }
 
             case 'singleton': {
-                if(binding.instance === undefined && this.name === 'root') {
-                    binding.instance = this.instantiate(binding.implementation);
-                    this.singletons.set(target, binding.instance);
+                if (this.singletons.has(k)) return this.singletons.get(k) as T;
+                const inst = this._instantiate(binding);
+                this.singletons.set(k, inst);
+                if (binding.instance === undefined) {
+                    (binding as IBinding<unknown>).instance = inst as unknown;
                 }
-
-                return binding.instance as T;
+                return inst as T;
             }
         }
     }
 
-    /**
-     * Instantiates a class, resolving its dependencies.
-     */
-    private instantiate<T extends Type<unknown>>(target: T): InstanceType<T> {
-        const paramTypes = Reflect.getMetadata('design:paramtypes', target) || [];
-        const injectParams = Reflect.getMetadata(INJECT_METADATA_KEY, target) || [];
-
-        const params = paramTypes.map((paramType: any, index: number) => {
-            const overrideToken = injectParams[index];
-            const actualToken = overrideToken !== undefined ? overrideToken : paramType;
-
-            return this.resolve(actualToken);
-        });
+    // -------------------------------------------------------------------------
+
+    private _resolveForwardRef<T>(ref: ForwardReference<T>): T {
+        return new Proxy({} as object, {
+            get: (_obj, prop, receiver) => {
+                const realType = ref.forwardRefFn();
+                const instance = this.resolve(realType) as Record<string | symbol, unknown>;
+                const value = Reflect.get(instance, prop, receiver);
+                return typeof value === 'function' ? (value as Function).bind(instance) : value;
+            },
+            set: (_obj, prop, value, receiver) => {
+                const realType = ref.forwardRefFn();
+                const instance = this.resolve(realType) as object;
+                return Reflect.set(instance, prop, value, receiver);
+            },
+            getPrototypeOf: () => {
+                const realType = ref.forwardRefFn();
+                return (realType as unknown as { prototype: object }).prototype;
+            },
+        }) as T;
+    }
 
-        return new target(...params) as InstanceType<T>;
+    private _instantiate<T>(binding: IBinding<T>): T {
+        const resolvedDeps = binding.deps.map((dep) => this.resolve(dep));
+        return new binding.implementation(...resolvedDeps) as T;
     }
 }
 
 /**
- * Injects a type from the dependency injection system.
- * This function is used to retrieve an instance of a type that has been registered in the dependency injection system.
- * It is typically used in the constructor of a class to inject dependencies.
- * @param t - The type to inject.
- * @returns An instance of the type.
- * @throws If the type is not registered in the dependency injection system.
+ * The global root injector. All singletons live here.
  */
-export function inject<T>(t: Type<T> | ForwardReference<T>): T {
+export const RootInjector = new AppInjector('root');
+
+/**
+ * Convenience function: resolve a token from the root injector.
+ */
+export function inject<T>(t: TokenKey<T> | ForwardReference<T>): T {
     return RootInjector.resolve(t);
 }
-
-export const RootInjector = new AppInjector('root');

package/src/DI/injector-explorer.ts

@@ -4,121 +4,140 @@
  * @author NoxFly
  */
 
-import { getControllerMetadata } from "src/decorators/controller.decorator";
-import { getInjectableMetadata } from "src/decorators/injectable.metadata";
-import { getRouteMetadata } from "src/decorators/method.decorator";
-import { getModuleMetadata } from "src/decorators/module.decorator";
-import { Lifetime, RootInjector } from "src/DI/app-injector";
-import { Router } from "src/router";
-import { Logger } from "src/utils/logger";
-import { Type } from "src/utils/types";
-
-interface PendingRegistration {
-    target: Type<unknown>;
+import { Lifetime, RootInjector } from './app-injector';
+import { TokenKey } from './token';
+import { Type } from '../utils/types';
+import { Logger } from '../utils/logger';
+import { Guard, Middleware } from "src/main";
+
+export interface PendingRegistration {
+    key: TokenKey;
+    implementation: Type<unknown>;
     lifetime: Lifetime;
+    deps: ReadonlyArray<TokenKey>;
+    isController: boolean;
+    pathPrefix?: string;
 }
 
 /**
- * InjectorExplorer is a utility class that explores the dependency injection system at the startup.
- * It collects decorated classes during the import phase and defers their actual registration
- * and resolution to when {@link processPending} is called by bootstrapApplication.
+ * InjectorExplorer accumulates registrations emitted by decorators
+ * at import time, then flushes them in two phases (bind → resolve)
+ * once bootstrapApplication triggers processing.
+ *
+ * Because deps are now explicit arrays (no reflect-metadata), this class
+ * no longer needs to introspect constructor parameter types.
  */
 export class InjectorExplorer {
     private static readonly pending: PendingRegistration[] = [];
     private static processed = false;
+    private static accumulating = false;
 
-    /**
-     * Enqueues a class for deferred registration.
-     * Called by the @Injectable decorator at import time.
-     *
-     * If {@link processPending} has already been called (i.e. after bootstrap),
-     * the class is registered immediately so that late dynamic imports
-     * (e.g. middlewares loaded after bootstrap) work correctly.
-     */
-    public static enqueue(target: Type<unknown>, lifetime: Lifetime): void {
-        if(InjectorExplorer.processed) {
-            InjectorExplorer.registerImmediate(target, lifetime);
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+
+    public static enqueue(reg: PendingRegistration): void {
+        if (InjectorExplorer.processed && !InjectorExplorer.accumulating) {
+            InjectorExplorer._registerImmediate(reg);
             return;
         }
-
-        InjectorExplorer.pending.push({ target, lifetime });
+        InjectorExplorer.pending.push(reg);
     }
 
     /**
-     * Processes all pending registrations in two phases:
-     * 1. Register all bindings (no instantiation) so every dependency is known.
-     * 2. Resolve singletons, register controllers and log module readiness.
-     *
-     * This two-phase approach makes the system resilient to import ordering:
-     * all bindings exist before any singleton is instantiated.
+     * Two-phase flush of all pending registrations collected at startup.
+     * Called by bootstrapApplication after app.whenReady().
      */
-    public static processPending(): void {
-        const queue = InjectorExplorer.pending;
-
-        // Phase 1: register all bindings without instantiation
-        for(const { target, lifetime } of queue) {
-            if(!RootInjector.bindings.has(target)) {
-                RootInjector.bindings.set(target, {
-                    implementation: target,
-                    lifetime
-                });
-            }
-        }
+    public static processPending(singletonOverrides?: Map<TokenKey, unknown>): void {
+        const queue = [...InjectorExplorer.pending];
+        InjectorExplorer.pending.length = 0;
 
-        // Phase 2: resolve singletons, register controllers, log modules
-        for(const { target, lifetime } of queue) {
-            InjectorExplorer.processRegistration(target, lifetime);
-        }
+        InjectorExplorer._phaseOne(queue);
+        InjectorExplorer._phaseTwo(queue, singletonOverrides);
 
-        queue.length = 0;
         InjectorExplorer.processed = true;
     }
 
+    /** Enters accumulation mode for lazy-loaded batches. */
+    public static beginAccumulate(): void {
+        InjectorExplorer.accumulating = true;
+    }
+
     /**
-     * Registers a single class immediately (post-bootstrap path).
-     * Used for classes discovered via late dynamic imports.
+     * Exits accumulation mode and flushes queued registrations
+     * with the same two-phase guarantee as processPending.
      */
-    private static registerImmediate(target: Type<unknown>, lifetime: Lifetime): void {
-        if(RootInjector.bindings.has(target)) {
-            return;
+    public static flushAccumulated(
+        routeGuards: Guard[] = [],
+        routeMiddlewares: Middleware[] = [],
+        pathPrefix = '',
+    ): void {
+        InjectorExplorer.accumulating = false;
+        const queue = [...InjectorExplorer.pending];
+        InjectorExplorer.pending.length = 0;
+        InjectorExplorer._phaseOne(queue);
+
+        // Stamp the path prefix on controller registrations
+        for (const reg of queue) {
+            if (reg.isController) reg.pathPrefix = pathPrefix;
         }
 
-        RootInjector.bindings.set(target, {
-            implementation: target,
-            lifetime
-        });
-
-        InjectorExplorer.processRegistration(target, lifetime);
+        InjectorExplorer._phaseTwo(queue, undefined, routeGuards, routeMiddlewares);
     }
 
-    /**
-     * Performs phase-2 work for a single registration: resolve singletons,
-     * register controllers, and log module readiness.
-     */
-    private static processRegistration(target: Type<unknown>, lifetime: Lifetime): void {
-        if(lifetime === 'singleton') {
-            RootInjector.resolve(target);
-        }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
 
-        if(getModuleMetadata(target)) {
-            Logger.log(`${target.name} dependencies initialized`);
-            return;
+    /** Phase 1: register all bindings without instantiating anything. */
+    private static _phaseOne(queue: PendingRegistration[]): void {
+        for (const reg of queue) {
+            RootInjector.register(reg.key, reg.implementation, reg.lifetime, reg.deps);
         }
+    }
 
-        const controllerMeta = getControllerMetadata(target);
+    /** Phase 2: resolve singletons and register controllers in the router. */
+    private static _phaseTwo(
+        queue: PendingRegistration[],
+        overrides?: Map<TokenKey, unknown>,
+        routeGuards: Guard[] = [],
+        routeMiddlewares: Middleware[] = [],
+    ): void {
+        for (const reg of queue) {
+            // Apply value overrides (e.g. singleton instances provided via bootstrapApplication config)
+            if (overrides?.has(reg.key)) {
+                const override = overrides.get(reg.key);
+                RootInjector.singletons.set(reg.key as any, override);
+                Logger.log(`Registered ${reg.implementation.name} as singleton (overridden)`);
+                continue;
+            }
 
-        if(controllerMeta) {
-            const router = RootInjector.resolve(Router);
-            router?.registerController(target);
-            return;
+            if (reg.lifetime === 'singleton') {
+                RootInjector.resolve(reg.key);
+            }
+
+            if (reg.isController) {
+                // Lazily import Router to avoid circular dependency at module load time
+                const { Router } = require('../router') as { Router: { prototype: { registerController(t: Type<unknown>): void } } };
+                const router = RootInjector.resolve(Router as any) as { registerController(t: Type<unknown>, pathPrefix: string, routeGuards: Guard[], routeMiddlewares: Middleware[]): void };
+                router.registerController(reg.implementation, reg.pathPrefix ?? '', routeGuards, routeMiddlewares);
+            } else if (reg.lifetime !== 'singleton') {
+                Logger.log(`Registered ${reg.implementation.name} as ${reg.lifetime}`);
+            }
         }
+    }
 
-        if(getRouteMetadata(target).length > 0) {
-            return;
+    private static _registerImmediate(reg: PendingRegistration): void {
+        RootInjector.register(reg.key, reg.implementation, reg.lifetime, reg.deps);
+
+        if (reg.lifetime === 'singleton') {
+            RootInjector.resolve(reg.key);
         }
 
-        if(getInjectableMetadata(target)) {
-            Logger.log(`Registered ${target.name} as ${lifetime}`);
+        if (reg.isController) {
+            const { Router } = require('../router') as { Router: { prototype: { registerController(t: Type<unknown>): void } } };
+            const router = RootInjector.resolve(Router as any) as { registerController(t: Type<unknown>): void };
+            router.registerController(reg.implementation);
         }
     }
 }

package/src/DI/token.ts

@@ -0,0 +1,53 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { Type } from '../utils/types';
+
+/**
+ * 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');
+ */
+export class Token<T> {
+    public readonly description: string;
+
+    constructor(
+        public readonly target: Type<T> | string,
+    ) {
+        this.description = typeof target === 'string' ? target : target.name;
+    }
+
+    public toString(): string {
+        return `Token(${this.description})`;
+    }
+}
+
+/**
+ * Creates a DI token for a class type or a named value.
+ *
+ * @example
+ * export const MY_SERVICE = token(MyService);
+ * export const DB_URL = token<string>('DB_URL');
+ */
+export function token<T>(target: Type<T> | string): Token<T> {
+    return new Token<T>(target);
+}
+
+/**
+ * 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.
+ */
+export type TokenKey<T = unknown> = Type<T> | Token<T>;