@noxfly/noxus 2.1.1 → 2.2.0

package/README.md

@@ -311,6 +311,50 @@ import { MyClass } from 'src/myclass';
 const instance: MyClass = inject(MyClass);
 ```
 
+### Circular Dependencies
+
+Noxus solves circular dependencies using a forward reference pattern. When two classes depend on each other, you can use `forwardRef()` combined with either the `@Inject()` decorator or the `inject()` helper to lazily resolve the dependency.
+
+**Using Constructor Injection (`@Inject`)**
+
+```ts
+import { Injectable, Inject, forwardRef } from '@noxfly/noxus/main';
+
+@Injectable()
+class ServiceA {
+    constructor(
+        @Inject(forwardRef(() => ServiceB)) 
+        private readonly serviceB: ServiceB
+    ) {}
+}
+
+@Injectable()
+class ServiceB {
+    constructor(
+        private readonly serviceA: ServiceA
+    ) {}
+}
+```
+
+**Using Property Injection (`inject`)**
+
+```ts
+import { Injectable, inject, forwardRef } from '@noxfly/noxus/main';
+
+@Injectable()
+class ServiceA {
+    // Lazily resolves ServiceB, avoiding infinite recursion during instantiation
+    private readonly serviceB = inject(forwardRef(() => ServiceB));
+}
+
+@Injectable()
+class ServiceB {
+    private readonly serviceA = inject(ServiceA);
+}
+```
+
+In both cases, a `Proxy` is returned, meaning the actual instance is only resolved when you access a property or method on it.
+
 ### Middlewares
 
 Declare middlewares as follow :

package/dist/{index-CI3OMzNR.d.mts → index-Dr-ifUJj.d.mts}

@@ -110,6 +110,28 @@ declare const Delete: (path: string) => MethodDecorator;
 declare const ROUTE_METADATA_KEY: unique symbol;
 
 
+/**
+ * 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>;
+
+
 /**
  * Represents a lifetime of a binding in the dependency injection system.
  * It can be one of the following:
@@ -151,9 +173,9 @@ declare class AppInjector {
      * Called when resolving a dependency,
      * i.e., retrieving the instance of a given class.
      */
-    resolve<T extends Type<unknown>>(target: T): InstanceType<T>;
+    resolve<T>(target: Type<T> | ForwardReference<T>): T;
     /**
-     *
+     * Instantiates a class, resolving its dependencies.
      */
     private instantiate;
 }
@@ -165,7 +187,7 @@ declare class AppInjector {
  * @returns An instance of the type.
  * @throws If the type is not registered in the dependency injection system.
  */
-declare function inject<T>(t: Type<T>): T;
+declare function inject<T>(t: Type<T> | ForwardReference<T>): T;
 declare const RootInjector: AppInjector;
 
 
@@ -315,4 +337,4 @@ declare class NoxRendererClient {
     isElectronEnvironment(): boolean;
 }
 
-export { AppInjector as A, Delete as D, Get as G, type HttpMethod as H, type IResponse as I, type Lifetime as L, type MaybeAsync as M, NoxRendererClient as N, Post as P, Request as R, type Type as T, type IGuard as a, type IPortRequester as b, type IBinding as c, RootInjector as d, Authorize as e, getGuardForControllerAction as f, getGuardForController as g, type IRouteMetadata as h, inject as i, type AtomicHttpMethod as j, getRouteMetadata as k, Put as l, Patch as m, ROUTE_METADATA_KEY as n, type IRequest as o, type IBatchRequestItem as p, type IBatchRequestPayload as q, type IBatchResponsePayload as r, RENDERER_EVENT_TYPE as s, type IRendererEventMessage as t, createRendererEventMessage as u, isRendererEventMessage as v, type RendererEventHandler as w, type RendererEventSubscription as x, RendererEventRegistry as y, type RendererClientOptions as z };
+export { AppInjector as A, RendererEventRegistry as B, type RendererClientOptions as C, Delete as D, type ForwardRefFn as F, Get as G, type HttpMethod as H, type IResponse as I, type Lifetime as L, type MaybeAsync as M, NoxRendererClient as N, Post as P, Request as R, type Type as T, type IGuard as a, type IPortRequester as b, type IBinding as c, RootInjector as d, Authorize as e, getGuardForControllerAction as f, getGuardForController as g, type IRouteMetadata as h, inject as i, type AtomicHttpMethod as j, getRouteMetadata as k, Put as l, Patch as m, ROUTE_METADATA_KEY as n, ForwardReference as o, forwardRef as p, type IRequest as q, type IBatchRequestItem as r, type IBatchRequestPayload as s, type IBatchResponsePayload as t, RENDERER_EVENT_TYPE as u, type IRendererEventMessage as v, createRendererEventMessage as w, isRendererEventMessage as x, type RendererEventHandler as y, type RendererEventSubscription as z };

package/dist/{index-CI3OMzNR.d.ts → index-Dr-ifUJj.d.ts}

@@ -110,6 +110,28 @@ declare const Delete: (path: string) => MethodDecorator;
 declare const ROUTE_METADATA_KEY: unique symbol;
 
 
+/**
+ * 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>;
+
+
 /**
  * Represents a lifetime of a binding in the dependency injection system.
  * It can be one of the following:
@@ -151,9 +173,9 @@ declare class AppInjector {
      * Called when resolving a dependency,
      * i.e., retrieving the instance of a given class.
      */
-    resolve<T extends Type<unknown>>(target: T): InstanceType<T>;
+    resolve<T>(target: Type<T> | ForwardReference<T>): T;
     /**
-     *
+     * Instantiates a class, resolving its dependencies.
      */
     private instantiate;
 }
@@ -165,7 +187,7 @@ declare class AppInjector {
  * @returns An instance of the type.
  * @throws If the type is not registered in the dependency injection system.
  */
-declare function inject<T>(t: Type<T>): T;
+declare function inject<T>(t: Type<T> | ForwardReference<T>): T;
 declare const RootInjector: AppInjector;
 
 
@@ -315,4 +337,4 @@ declare class NoxRendererClient {
     isElectronEnvironment(): boolean;
 }
 
-export { AppInjector as A, Delete as D, Get as G, type HttpMethod as H, type IResponse as I, type Lifetime as L, type MaybeAsync as M, NoxRendererClient as N, Post as P, Request as R, type Type as T, type IGuard as a, type IPortRequester as b, type IBinding as c, RootInjector as d, Authorize as e, getGuardForControllerAction as f, getGuardForController as g, type IRouteMetadata as h, inject as i, type AtomicHttpMethod as j, getRouteMetadata as k, Put as l, Patch as m, ROUTE_METADATA_KEY as n, type IRequest as o, type IBatchRequestItem as p, type IBatchRequestPayload as q, type IBatchResponsePayload as r, RENDERER_EVENT_TYPE as s, type IRendererEventMessage as t, createRendererEventMessage as u, isRendererEventMessage as v, type RendererEventHandler as w, type RendererEventSubscription as x, RendererEventRegistry as y, type RendererClientOptions as z };
+export { AppInjector as A, RendererEventRegistry as B, type RendererClientOptions as C, Delete as D, type ForwardRefFn as F, Get as G, type HttpMethod as H, type IResponse as I, type Lifetime as L, type MaybeAsync as M, NoxRendererClient as N, Post as P, Request as R, type Type as T, type IGuard as a, type IPortRequester as b, type IBinding as c, RootInjector as d, Authorize as e, getGuardForControllerAction as f, getGuardForController as g, type IRouteMetadata as h, inject as i, type AtomicHttpMethod as j, getRouteMetadata as k, Put as l, Patch as m, ROUTE_METADATA_KEY as n, ForwardReference as o, forwardRef as p, type IRequest as q, type IBatchRequestItem as r, type IBatchRequestPayload as s, type IBatchResponsePayload as t, RENDERER_EVENT_TYPE as u, type IRendererEventMessage as v, createRendererEventMessage as w, isRendererEventMessage as x, type RendererEventHandler as y, type RendererEventSubscription as z };

package/dist/main.d.mts

@@ -1,5 +1,5 @@
-import { R as Request, I as IResponse, M as MaybeAsync, T as Type, a as IGuard, L as Lifetime, b as IPortRequester } from './index-CI3OMzNR.mjs';
-export { A as AppInjector, j as AtomicHttpMethod, e as Authorize, D as Delete, G as Get, H as HttpMethod, p as IBatchRequestItem, q as IBatchRequestPayload, r as IBatchResponsePayload, c as IBinding, t as IRendererEventMessage, o as IRequest, h as IRouteMetadata, N as NoxRendererClient, m as Patch, P as Post, l as Put, s as RENDERER_EVENT_TYPE, n as ROUTE_METADATA_KEY, z as RendererClientOptions, w as RendererEventHandler, y as RendererEventRegistry, x as RendererEventSubscription, d as RootInjector, u as createRendererEventMessage, g as getGuardForController, f as getGuardForControllerAction, k as getRouteMetadata, i as inject, v as isRendererEventMessage } from './index-CI3OMzNR.mjs';
+import { R as Request, I as IResponse, M as MaybeAsync, T as Type, a as IGuard, L as Lifetime, b as IPortRequester } from './index-Dr-ifUJj.mjs';
+export { A as AppInjector, j as AtomicHttpMethod, e as Authorize, D as Delete, F as ForwardRefFn, o as ForwardReference, G as Get, H as HttpMethod, r as IBatchRequestItem, s as IBatchRequestPayload, t as IBatchResponsePayload, c as IBinding, v as IRendererEventMessage, q as IRequest, h as IRouteMetadata, N as NoxRendererClient, m as Patch, P as Post, l as Put, u as RENDERER_EVENT_TYPE, n as ROUTE_METADATA_KEY, C as RendererClientOptions, y as RendererEventHandler, B as RendererEventRegistry, z as RendererEventSubscription, d as RootInjector, w as createRendererEventMessage, p as forwardRef, g as getGuardForController, f as getGuardForControllerAction, k as getRouteMetadata, i as inject, x as isRendererEventMessage } from './index-Dr-ifUJj.mjs';
 
 /**
  * @copyright 2025 NoxFly
@@ -374,6 +374,16 @@ declare function hasInjectableMetadata(target: Function): boolean;
 declare function Injectable(lifetime?: Lifetime): ClassDecorator;
 
 
+declare const INJECT_METADATA_KEY = "custom:inject";
+/**
+ * Decorator to manually inject a dependency.
+ * Useful for handling circular dependencies with `forwardRef` or injecting specific tokens.
+ *
+ * @param token The token or forward reference to inject.
+ */
+declare function Inject(token: any): ParameterDecorator;
+
+
 interface IModuleMetadata {
     imports?: Type<unknown>[];
     exports?: Type<unknown>[];
@@ -508,4 +518,4 @@ declare namespace Logger {
     };
 }
 
-export { BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, ForbiddenException, GatewayTimeoutException, HttpVersionNotSupportedException, type IApp, type IControllerMetadata, IGuard, type IMiddleware, type IModuleMetadata, INJECTABLE_METADATA_KEY, IPortRequester, IResponse, type IRouteDefinition, Injectable, InsufficientStorageException, InternalServerException, Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, NoxSocket, type NoxusPreloadAPI, type NoxusPreloadOptions, PaymentRequiredException, Request, RequestTimeoutException, ResponseException, Router, ServiceUnavailableException, TooManyRequestsException, Type, UnauthorizedException, UpgradeRequiredException, UseMiddlewares, VariantAlsoNegotiatesException, bootstrapApplication, exposeNoxusBridge, getControllerMetadata, getInjectableMetadata, getMiddlewaresForController, getMiddlewaresForControllerAction, getModuleMetadata, hasInjectableMetadata };
+export { BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, ForbiddenException, GatewayTimeoutException, HttpVersionNotSupportedException, type IApp, type IControllerMetadata, IGuard, type IMiddleware, type IModuleMetadata, INJECTABLE_METADATA_KEY, INJECT_METADATA_KEY, IPortRequester, IResponse, type IRouteDefinition, Inject, Injectable, InsufficientStorageException, InternalServerException, Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, NoxSocket, type NoxusPreloadAPI, type NoxusPreloadOptions, PaymentRequiredException, Request, RequestTimeoutException, ResponseException, Router, ServiceUnavailableException, TooManyRequestsException, Type, UnauthorizedException, UpgradeRequiredException, UseMiddlewares, VariantAlsoNegotiatesException, bootstrapApplication, exposeNoxusBridge, getControllerMetadata, getInjectableMetadata, getMiddlewaresForController, getMiddlewaresForControllerAction, getModuleMetadata, hasInjectableMetadata };

package/dist/main.d.ts

@@ -1,5 +1,5 @@
-import { R as Request, I as IResponse, M as MaybeAsync, T as Type, a as IGuard, L as Lifetime, b as IPortRequester } from './index-CI3OMzNR.js';
-export { A as AppInjector, j as AtomicHttpMethod, e as Authorize, D as Delete, G as Get, H as HttpMethod, p as IBatchRequestItem, q as IBatchRequestPayload, r as IBatchResponsePayload, c as IBinding, t as IRendererEventMessage, o as IRequest, h as IRouteMetadata, N as NoxRendererClient, m as Patch, P as Post, l as Put, s as RENDERER_EVENT_TYPE, n as ROUTE_METADATA_KEY, z as RendererClientOptions, w as RendererEventHandler, y as RendererEventRegistry, x as RendererEventSubscription, d as RootInjector, u as createRendererEventMessage, g as getGuardForController, f as getGuardForControllerAction, k as getRouteMetadata, i as inject, v as isRendererEventMessage } from './index-CI3OMzNR.js';
+import { R as Request, I as IResponse, M as MaybeAsync, T as Type, a as IGuard, L as Lifetime, b as IPortRequester } from './index-Dr-ifUJj.js';
+export { A as AppInjector, j as AtomicHttpMethod, e as Authorize, D as Delete, F as ForwardRefFn, o as ForwardReference, G as Get, H as HttpMethod, r as IBatchRequestItem, s as IBatchRequestPayload, t as IBatchResponsePayload, c as IBinding, v as IRendererEventMessage, q as IRequest, h as IRouteMetadata, N as NoxRendererClient, m as Patch, P as Post, l as Put, u as RENDERER_EVENT_TYPE, n as ROUTE_METADATA_KEY, C as RendererClientOptions, y as RendererEventHandler, B as RendererEventRegistry, z as RendererEventSubscription, d as RootInjector, w as createRendererEventMessage, p as forwardRef, g as getGuardForController, f as getGuardForControllerAction, k as getRouteMetadata, i as inject, x as isRendererEventMessage } from './index-Dr-ifUJj.js';
 
 /**
  * @copyright 2025 NoxFly
@@ -374,6 +374,16 @@ declare function hasInjectableMetadata(target: Function): boolean;
 declare function Injectable(lifetime?: Lifetime): ClassDecorator;
 
 
+declare const INJECT_METADATA_KEY = "custom:inject";
+/**
+ * Decorator to manually inject a dependency.
+ * Useful for handling circular dependencies with `forwardRef` or injecting specific tokens.
+ *
+ * @param token The token or forward reference to inject.
+ */
+declare function Inject(token: any): ParameterDecorator;
+
+
 interface IModuleMetadata {
     imports?: Type<unknown>[];
     exports?: Type<unknown>[];
@@ -508,4 +518,4 @@ declare namespace Logger {
     };
 }
 
-export { BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, ForbiddenException, GatewayTimeoutException, HttpVersionNotSupportedException, type IApp, type IControllerMetadata, IGuard, type IMiddleware, type IModuleMetadata, INJECTABLE_METADATA_KEY, IPortRequester, IResponse, type IRouteDefinition, Injectable, InsufficientStorageException, InternalServerException, Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, NoxSocket, type NoxusPreloadAPI, type NoxusPreloadOptions, PaymentRequiredException, Request, RequestTimeoutException, ResponseException, Router, ServiceUnavailableException, TooManyRequestsException, Type, UnauthorizedException, UpgradeRequiredException, UseMiddlewares, VariantAlsoNegotiatesException, bootstrapApplication, exposeNoxusBridge, getControllerMetadata, getInjectableMetadata, getMiddlewaresForController, getMiddlewaresForControllerAction, getModuleMetadata, hasInjectableMetadata };
+export { BadGatewayException, BadRequestException, CONTROLLER_METADATA_KEY, ConflictException, Controller, type ControllerAction, ForbiddenException, GatewayTimeoutException, HttpVersionNotSupportedException, type IApp, type IControllerMetadata, IGuard, type IMiddleware, type IModuleMetadata, INJECTABLE_METADATA_KEY, INJECT_METADATA_KEY, IPortRequester, IResponse, type IRouteDefinition, Inject, Injectable, InsufficientStorageException, InternalServerException, Lifetime, type LogLevel, Logger, LoopDetectedException, MODULE_METADATA_KEY, MaybeAsync, MethodNotAllowedException, Module, NetworkAuthenticationRequiredException, NetworkConnectTimeoutException, type NextFunction, NotAcceptableException, NotExtendedException, NotFoundException, NotImplementedException, NoxApp, NoxSocket, type NoxusPreloadAPI, type NoxusPreloadOptions, PaymentRequiredException, Request, RequestTimeoutException, ResponseException, Router, ServiceUnavailableException, TooManyRequestsException, Type, UnauthorizedException, UpgradeRequiredException, UseMiddlewares, VariantAlsoNegotiatesException, bootstrapApplication, exposeNoxusBridge, getControllerMetadata, getInjectableMetadata, getMiddlewaresForController, getMiddlewaresForControllerAction, getModuleMetadata, hasInjectableMetadata };

package/dist/main.js

@@ -47,10 +47,13 @@ __export(main_exports, {
   Controller: () => Controller,
   Delete: () => Delete,
   ForbiddenException: () => ForbiddenException,
+  ForwardReference: () => ForwardReference,
   GatewayTimeoutException: () => GatewayTimeoutException,
   Get: () => Get,
   HttpVersionNotSupportedException: () => HttpVersionNotSupportedException,
   INJECTABLE_METADATA_KEY: () => INJECTABLE_METADATA_KEY,
+  INJECT_METADATA_KEY: () => INJECT_METADATA_KEY,
+  Inject: () => Inject,
   Injectable: () => Injectable,
   InsufficientStorageException: () => InsufficientStorageException,
   InternalServerException: () => InternalServerException,
@@ -89,6 +92,7 @@ __export(main_exports, {
   bootstrapApplication: () => bootstrapApplication,
   createRendererEventMessage: () => createRendererEventMessage,
   exposeNoxusBridge: () => exposeNoxusBridge,
+  forwardRef: () => forwardRef,
   getControllerMetadata: () => getControllerMetadata,
   getGuardForController: () => getGuardForController,
   getGuardForControllerAction: () => getGuardForControllerAction,
@@ -104,7 +108,19 @@ __export(main_exports, {
 module.exports = __toCommonJS(main_exports);
 
 // src/DI/app-injector.ts
+var import_reflect_metadata2 = require("reflect-metadata");
+
+// src/decorators/inject.decorator.ts
 var import_reflect_metadata = require("reflect-metadata");
+var INJECT_METADATA_KEY = "custom:inject";
+function Inject(token) {
+  return (target, propertyKey, parameterIndex) => {
+    const existingParameters = Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) || [];
+    existingParameters[parameterIndex] = token;
+    Reflect.defineMetadata(INJECT_METADATA_KEY, existingParameters, target);
+  };
+}
+__name(Inject, "Inject");
 
 // src/exceptions.ts
 var _ResponseException = class _ResponseException extends Error {
@@ -310,6 +326,20 @@ var _NetworkConnectTimeoutException = class _NetworkConnectTimeoutException exte
 __name(_NetworkConnectTimeoutException, "NetworkConnectTimeoutException");
 var NetworkConnectTimeoutException = _NetworkConnectTimeoutException;
 
+// src/utils/forward-ref.ts
+var _ForwardReference = class _ForwardReference {
+  constructor(forwardRefFn) {
+    __publicField(this, "forwardRefFn");
+    this.forwardRefFn = forwardRefFn;
+  }
+};
+__name(_ForwardReference, "ForwardReference");
+var ForwardReference = _ForwardReference;
+function forwardRef(fn) {
+  return new ForwardReference(fn);
+}
+__name(forwardRef, "forwardRef");
+
 // src/DI/app-injector.ts
 var _AppInjector = class _AppInjector {
   constructor(name = null) {
@@ -336,9 +366,34 @@ var _AppInjector = class _AppInjector {
    * i.e., retrieving the instance of a given class.
    */
   resolve(target) {
+    if (target instanceof ForwardReference) {
+      return new Proxy({}, {
+        get: /* @__PURE__ */ __name((obj, prop, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          const value = Reflect.get(instance, prop, receiver);
+          return typeof value === "function" ? value.bind(instance) : value;
+        }, "get"),
+        set: /* @__PURE__ */ __name((obj, prop, value, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          return Reflect.set(instance, prop, value, receiver);
+        }, "set"),
+        getPrototypeOf: /* @__PURE__ */ __name(() => {
+          const realType = target.forwardRefFn();
+          return realType.prototype;
+        }, "getPrototypeOf")
+      });
+    }
     const binding = this.bindings.get(target);
-    if (!binding) throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${target.name}.
+    if (!binding) {
+      if (target === void 0) {
+        throw new InternalServerException("Failed to resolve a dependency injection : Undefined target type.\nThis might be caused by a circular dependency.");
+      }
+      const name = target.name || "unknown";
+      throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${name}.
 Did you forget to use @Injectable() decorator ?`);
+    }
     switch (binding.lifetime) {
       case "transient":
         return this.instantiate(binding.implementation);
@@ -360,11 +415,16 @@ Did you forget to use @Injectable() decorator ?`);
     }
   }
   /**
-   *
+   * Instantiates a class, resolving its dependencies.
    */
   instantiate(target) {
     const paramTypes = Reflect.getMetadata("design:paramtypes", target) || [];
-    const params = paramTypes.map((p) => this.resolve(p));
+    const injectParams = Reflect.getMetadata(INJECT_METADATA_KEY, target) || [];
+    const params = paramTypes.map((paramType, index) => {
+      const overrideToken = injectParams[index];
+      const actualToken = overrideToken !== void 0 ? overrideToken : paramType;
+      return this.resolve(actualToken);
+    });
     return new target(...params);
   }
 };
@@ -377,7 +437,7 @@ __name(inject, "inject");
 var RootInjector = new AppInjector("root");
 
 // src/router.ts
-var import_reflect_metadata3 = require("reflect-metadata");
+var import_reflect_metadata4 = require("reflect-metadata");
 
 // src/decorators/guards.decorator.ts
 function Authorize(...guardClasses) {
@@ -864,7 +924,7 @@ __name(getMiddlewaresForControllerAction, "getMiddlewaresForControllerAction");
 var middlewares = /* @__PURE__ */ new Map();
 
 // src/request.ts
-var import_reflect_metadata2 = require("reflect-metadata");
+var import_reflect_metadata3 = require("reflect-metadata");
 var _Request = class _Request {
   constructor(event, senderId, id, method, path2, body) {
     __publicField(this, "event");
@@ -2063,10 +2123,13 @@ var NoxRendererClient = _NoxRendererClient;
   Controller,
   Delete,
   ForbiddenException,
+  ForwardReference,
   GatewayTimeoutException,
   Get,
   HttpVersionNotSupportedException,
   INJECTABLE_METADATA_KEY,
+  INJECT_METADATA_KEY,
+  Inject,
   Injectable,
   InsufficientStorageException,
   InternalServerException,
@@ -2105,6 +2168,7 @@ var NoxRendererClient = _NoxRendererClient;
   bootstrapApplication,
   createRendererEventMessage,
   exposeNoxusBridge,
+  forwardRef,
   getControllerMetadata,
   getGuardForController,
   getGuardForControllerAction,

package/dist/main.mjs

@@ -11,6 +11,18 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/DI/app-injector.ts
 import "reflect-metadata";
 
+// src/decorators/inject.decorator.ts
+import "reflect-metadata";
+var INJECT_METADATA_KEY = "custom:inject";
+function Inject(token) {
+  return (target, propertyKey, parameterIndex) => {
+    const existingParameters = Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) || [];
+    existingParameters[parameterIndex] = token;
+    Reflect.defineMetadata(INJECT_METADATA_KEY, existingParameters, target);
+  };
+}
+__name(Inject, "Inject");
+
 // src/exceptions.ts
 var _ResponseException = class _ResponseException extends Error {
   constructor(statusOrMessage, message) {
@@ -215,6 +227,20 @@ var _NetworkConnectTimeoutException = class _NetworkConnectTimeoutException exte
 __name(_NetworkConnectTimeoutException, "NetworkConnectTimeoutException");
 var NetworkConnectTimeoutException = _NetworkConnectTimeoutException;
 
+// src/utils/forward-ref.ts
+var _ForwardReference = class _ForwardReference {
+  constructor(forwardRefFn) {
+    __publicField(this, "forwardRefFn");
+    this.forwardRefFn = forwardRefFn;
+  }
+};
+__name(_ForwardReference, "ForwardReference");
+var ForwardReference = _ForwardReference;
+function forwardRef(fn) {
+  return new ForwardReference(fn);
+}
+__name(forwardRef, "forwardRef");
+
 // src/DI/app-injector.ts
 var _AppInjector = class _AppInjector {
   constructor(name = null) {
@@ -241,9 +267,34 @@ var _AppInjector = class _AppInjector {
    * i.e., retrieving the instance of a given class.
    */
   resolve(target) {
+    if (target instanceof ForwardReference) {
+      return new Proxy({}, {
+        get: /* @__PURE__ */ __name((obj, prop, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          const value = Reflect.get(instance, prop, receiver);
+          return typeof value === "function" ? value.bind(instance) : value;
+        }, "get"),
+        set: /* @__PURE__ */ __name((obj, prop, value, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          return Reflect.set(instance, prop, value, receiver);
+        }, "set"),
+        getPrototypeOf: /* @__PURE__ */ __name(() => {
+          const realType = target.forwardRefFn();
+          return realType.prototype;
+        }, "getPrototypeOf")
+      });
+    }
     const binding = this.bindings.get(target);
-    if (!binding) throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${target.name}.
+    if (!binding) {
+      if (target === void 0) {
+        throw new InternalServerException("Failed to resolve a dependency injection : Undefined target type.\nThis might be caused by a circular dependency.");
+      }
+      const name = target.name || "unknown";
+      throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${name}.
 Did you forget to use @Injectable() decorator ?`);
+    }
     switch (binding.lifetime) {
       case "transient":
         return this.instantiate(binding.implementation);
@@ -265,11 +316,16 @@ Did you forget to use @Injectable() decorator ?`);
     }
   }
   /**
-   *
+   * Instantiates a class, resolving its dependencies.
    */
   instantiate(target) {
     const paramTypes = Reflect.getMetadata("design:paramtypes", target) || [];
-    const params = paramTypes.map((p) => this.resolve(p));
+    const injectParams = Reflect.getMetadata(INJECT_METADATA_KEY, target) || [];
+    const params = paramTypes.map((paramType, index) => {
+      const overrideToken = injectParams[index];
+      const actualToken = overrideToken !== void 0 ? overrideToken : paramType;
+      return this.resolve(actualToken);
+    });
     return new target(...params);
   }
 };
@@ -1967,10 +2023,13 @@ export {
   Controller,
   Delete,
   ForbiddenException,
+  ForwardReference,
   GatewayTimeoutException,
   Get,
   HttpVersionNotSupportedException,
   INJECTABLE_METADATA_KEY,
+  INJECT_METADATA_KEY,
+  Inject,
   Injectable,
   InsufficientStorageException,
   InternalServerException,
@@ -2009,6 +2068,7 @@ export {
   bootstrapApplication,
   createRendererEventMessage,
   exposeNoxusBridge,
+  forwardRef,
   getControllerMetadata,
   getGuardForController,
   getGuardForControllerAction,

package/dist/renderer.d.mts

@@ -1 +1 @@
-export { p as IBatchRequestItem, q as IBatchRequestPayload, r as IBatchResponsePayload, b as IPortRequester, t as IRendererEventMessage, o as IRequest, I as IResponse, N as NoxRendererClient, s as RENDERER_EVENT_TYPE, z as RendererClientOptions, w as RendererEventHandler, y as RendererEventRegistry, x as RendererEventSubscription, R as Request, u as createRendererEventMessage, v as isRendererEventMessage } from './index-CI3OMzNR.mjs';
+export { r as IBatchRequestItem, s as IBatchRequestPayload, t as IBatchResponsePayload, b as IPortRequester, v as IRendererEventMessage, q as IRequest, I as IResponse, N as NoxRendererClient, u as RENDERER_EVENT_TYPE, C as RendererClientOptions, y as RendererEventHandler, B as RendererEventRegistry, z as RendererEventSubscription, R as Request, w as createRendererEventMessage, x as isRendererEventMessage } from './index-Dr-ifUJj.mjs';

package/dist/renderer.d.ts

@@ -1 +1 @@
-export { p as IBatchRequestItem, q as IBatchRequestPayload, r as IBatchResponsePayload, b as IPortRequester, t as IRendererEventMessage, o as IRequest, I as IResponse, N as NoxRendererClient, s as RENDERER_EVENT_TYPE, z as RendererClientOptions, w as RendererEventHandler, y as RendererEventRegistry, x as RendererEventSubscription, R as Request, u as createRendererEventMessage, v as isRendererEventMessage } from './index-CI3OMzNR.js';
+export { r as IBatchRequestItem, s as IBatchRequestPayload, t as IBatchResponsePayload, b as IPortRequester, v as IRendererEventMessage, q as IRequest, I as IResponse, N as NoxRendererClient, u as RENDERER_EVENT_TYPE, C as RendererClientOptions, y as RendererEventHandler, B as RendererEventRegistry, z as RendererEventSubscription, R as Request, w as createRendererEventMessage, x as isRendererEventMessage } from './index-Dr-ifUJj.js';

package/dist/renderer.js

@@ -38,10 +38,14 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/request.ts
-var import_reflect_metadata2 = require("reflect-metadata");
+var import_reflect_metadata3 = require("reflect-metadata");
 
 // src/DI/app-injector.ts
+var import_reflect_metadata2 = require("reflect-metadata");
+
+// src/decorators/inject.decorator.ts
 var import_reflect_metadata = require("reflect-metadata");
+var INJECT_METADATA_KEY = "custom:inject";
 
 // src/exceptions.ts
 var _ResponseException = class _ResponseException extends Error {
@@ -71,6 +75,16 @@ var _InternalServerException = class _InternalServerException extends ResponseEx
 __name(_InternalServerException, "InternalServerException");
 var InternalServerException = _InternalServerException;
 
+// src/utils/forward-ref.ts
+var _ForwardReference = class _ForwardReference {
+  constructor(forwardRefFn) {
+    __publicField(this, "forwardRefFn");
+    this.forwardRefFn = forwardRefFn;
+  }
+};
+__name(_ForwardReference, "ForwardReference");
+var ForwardReference = _ForwardReference;
+
 // src/DI/app-injector.ts
 var _AppInjector = class _AppInjector {
   constructor(name = null) {
@@ -97,9 +111,34 @@ var _AppInjector = class _AppInjector {
    * i.e., retrieving the instance of a given class.
    */
   resolve(target) {
+    if (target instanceof ForwardReference) {
+      return new Proxy({}, {
+        get: /* @__PURE__ */ __name((obj, prop, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          const value = Reflect.get(instance, prop, receiver);
+          return typeof value === "function" ? value.bind(instance) : value;
+        }, "get"),
+        set: /* @__PURE__ */ __name((obj, prop, value, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          return Reflect.set(instance, prop, value, receiver);
+        }, "set"),
+        getPrototypeOf: /* @__PURE__ */ __name(() => {
+          const realType = target.forwardRefFn();
+          return realType.prototype;
+        }, "getPrototypeOf")
+      });
+    }
     const binding = this.bindings.get(target);
-    if (!binding) throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${target.name}.
+    if (!binding) {
+      if (target === void 0) {
+        throw new InternalServerException("Failed to resolve a dependency injection : Undefined target type.\nThis might be caused by a circular dependency.");
+      }
+      const name = target.name || "unknown";
+      throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${name}.
 Did you forget to use @Injectable() decorator ?`);
+    }
     switch (binding.lifetime) {
       case "transient":
         return this.instantiate(binding.implementation);
@@ -121,11 +160,16 @@ Did you forget to use @Injectable() decorator ?`);
     }
   }
   /**
-   *
+   * Instantiates a class, resolving its dependencies.
    */
   instantiate(target) {
     const paramTypes = Reflect.getMetadata("design:paramtypes", target) || [];
-    const params = paramTypes.map((p) => this.resolve(p));
+    const injectParams = Reflect.getMetadata(INJECT_METADATA_KEY, target) || [];
+    const params = paramTypes.map((paramType, index) => {
+      const overrideToken = injectParams[index];
+      const actualToken = overrideToken !== void 0 ? overrideToken : paramType;
+      return this.resolve(actualToken);
+    });
     return new target(...params);
   }
 };

package/dist/renderer.mjs

@@ -14,6 +14,10 @@ import "reflect-metadata";
 // src/DI/app-injector.ts
 import "reflect-metadata";
 
+// src/decorators/inject.decorator.ts
+import "reflect-metadata";
+var INJECT_METADATA_KEY = "custom:inject";
+
 // src/exceptions.ts
 var _ResponseException = class _ResponseException extends Error {
   constructor(statusOrMessage, message) {
@@ -42,6 +46,16 @@ var _InternalServerException = class _InternalServerException extends ResponseEx
 __name(_InternalServerException, "InternalServerException");
 var InternalServerException = _InternalServerException;
 
+// src/utils/forward-ref.ts
+var _ForwardReference = class _ForwardReference {
+  constructor(forwardRefFn) {
+    __publicField(this, "forwardRefFn");
+    this.forwardRefFn = forwardRefFn;
+  }
+};
+__name(_ForwardReference, "ForwardReference");
+var ForwardReference = _ForwardReference;
+
 // src/DI/app-injector.ts
 var _AppInjector = class _AppInjector {
   constructor(name = null) {
@@ -68,9 +82,34 @@ var _AppInjector = class _AppInjector {
    * i.e., retrieving the instance of a given class.
    */
   resolve(target) {
+    if (target instanceof ForwardReference) {
+      return new Proxy({}, {
+        get: /* @__PURE__ */ __name((obj, prop, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          const value = Reflect.get(instance, prop, receiver);
+          return typeof value === "function" ? value.bind(instance) : value;
+        }, "get"),
+        set: /* @__PURE__ */ __name((obj, prop, value, receiver) => {
+          const realType = target.forwardRefFn();
+          const instance = this.resolve(realType);
+          return Reflect.set(instance, prop, value, receiver);
+        }, "set"),
+        getPrototypeOf: /* @__PURE__ */ __name(() => {
+          const realType = target.forwardRefFn();
+          return realType.prototype;
+        }, "getPrototypeOf")
+      });
+    }
     const binding = this.bindings.get(target);
-    if (!binding) throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${target.name}.
+    if (!binding) {
+      if (target === void 0) {
+        throw new InternalServerException("Failed to resolve a dependency injection : Undefined target type.\nThis might be caused by a circular dependency.");
+      }
+      const name = target.name || "unknown";
+      throw new InternalServerException(`Failed to resolve a dependency injection : No binding for type ${name}.
 Did you forget to use @Injectable() decorator ?`);
+    }
     switch (binding.lifetime) {
       case "transient":
         return this.instantiate(binding.implementation);
@@ -92,11 +131,16 @@ Did you forget to use @Injectable() decorator ?`);
     }
   }
   /**
-   *
+   * Instantiates a class, resolving its dependencies.
    */
   instantiate(target) {
     const paramTypes = Reflect.getMetadata("design:paramtypes", target) || [];
-    const params = paramTypes.map((p) => this.resolve(p));
+    const injectParams = Reflect.getMetadata(INJECT_METADATA_KEY, target) || [];
+    const params = paramTypes.map((paramType, index) => {
+      const overrideToken = injectParams[index];
+      const actualToken = overrideToken !== void 0 ? overrideToken : paramType;
+      return this.resolve(actualToken);
+    });
     return new target(...params);
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@noxfly/noxus",
-    "version": "2.1.1",
+    "version": "2.2.0",
     "main": "dist/main.js",
     "module": "dist/main.mjs",
     "types": "dist/main.d.ts",

package/src/DI/app-injector.ts

@@ -5,7 +5,9 @@
  */
 
 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';
 
 /**
@@ -61,28 +63,59 @@ export class AppInjector {
      * Called when resolving a dependency,
      * i.e., retrieving the instance of a given class.
      */
-    public resolve<T extends Type<unknown>>(target: T): InstanceType<T> {
+    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;
+        }
+
         const binding = this.bindings.get(target);
 
-        if(!binding)
+        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."
+                );
+            }
+
+            const name = target.name || "unknown";
+
             throw new InternalServerException(
-                `Failed to resolve a dependency injection : No binding for type ${target.name}.\n`
+                `Failed to resolve a dependency injection : No binding for type ${name}.\n`
                 + `Did you forget to use @Injectable() decorator ?`
             );
+        }
 
         switch(binding.lifetime) {
             case 'transient':
-                return this.instantiate(binding.implementation) as InstanceType<T>;
+                return this.instantiate(binding.implementation) as T;
 
             case 'scope': {
                 if(this.scoped.has(target)) {
-                    return this.scoped.get(target) as InstanceType<T>;
+                    return this.scoped.get(target) as T;
                 }
 
                 const instance = this.instantiate(binding.implementation);
                 this.scoped.set(target, instance);
 
-                return instance as InstanceType<T>;
+                return instance as T;
             }
 
             case 'singleton': {
@@ -91,17 +124,25 @@ export class AppInjector {
                     this.singletons.set(target, binding.instance);
                 }
 
-                return binding.instance as InstanceType<T>;
+                return binding.instance 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 params = paramTypes.map((p: any) => this.resolve(p));
+        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);
+        });
+
         return new target(...params) as InstanceType<T>;
     }
 }
@@ -114,7 +155,7 @@ export class AppInjector {
  * @returns An instance of the type.
  * @throws If the type is not registered in the dependency injection system.
  */
-export function inject<T>(t: Type<T>): T {
+export function inject<T>(t: Type<T> | ForwardReference<T>): T {
     return RootInjector.resolve(t);
 }
 

package/src/decorators/inject.decorator.ts

@@ -0,0 +1,24 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import 'reflect-metadata';
+
+export const INJECT_METADATA_KEY = 'custom:inject';
+
+/**
+ * Decorator to manually inject a dependency.
+ * Useful for handling circular dependencies with `forwardRef` or injecting specific tokens.
+ *
+ * @param token The token or forward reference to inject.
+ */
+export function Inject(token: any): ParameterDecorator {
+    return (target, propertyKey, parameterIndex) => {
+        // target is the constructor for constructor parameters
+        const existingParameters = Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) || [];
+        existingParameters[parameterIndex] = token;
+        Reflect.defineMetadata(INJECT_METADATA_KEY, existingParameters, target);
+    };
+}

package/src/main.ts

@@ -19,11 +19,13 @@ export * from './decorators/middleware.decorator';
 export * from './decorators/guards.decorator';
 export * from './decorators/controller.decorator';
 export * from './decorators/injectable.decorator';
+export * from './decorators/inject.decorator';
 export * from './decorators/method.decorator';
 export * from './decorators/module.decorator';
 export * from './preload-bridge';
 export * from './utils/logger';
 export * from './utils/types';
+export * from './utils/forward-ref';
 export * from './request';
 export * from './renderer-events';
 export * from './renderer-client';

package/src/utils/forward-ref.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { Type } from "./types";
+
+/**
+ * A function that returns a type.
+ * Used for forward references to types that are not yet defined.
+ */
+export interface ForwardRefFn<T = any> {
+    (): Type<T>;
+}
+
+/**
+ * A wrapper class for forward referenced types.
+ */
+export class ForwardReference<T = any> {
+    constructor(public readonly forwardRefFn: ForwardRefFn<T>) {}
+}
+
+/**
+ * Creates a forward reference to a type.
+ * @param fn A function that returns the type.
+ * @returns A ForwardReference instance.
+ */
+export function forwardRef<T = any>(fn: ForwardRefFn<T>): ForwardReference<T> {
+    return new ForwardReference(fn);
+}