@abdokouta/ts-container 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1125 @@
+'use strict';
+
+require('reflect-metadata');
+
+// src/index.ts
+
+// src/constants/tokens.constant.ts
+var MODULE_METADATA = {
+  IMPORTS: "imports",
+  PROVIDERS: "providers",
+  EXPORTS: "exports"
+};
+var GLOBAL_MODULE_METADATA = "__module:global__";
+var INJECTABLE_WATERMARK = "__injectable__";
+var SCOPE_OPTIONS_METADATA = "scope:options";
+var PARAMTYPES_METADATA = "design:paramtypes";
+var SELF_DECLARED_DEPS_METADATA = "self:paramtypes";
+var OPTIONAL_DEPS_METADATA = "optional:paramtypes";
+var PROPERTY_DEPS_METADATA = "self:properties_metadata";
+var OPTIONAL_PROPERTY_DEPS_METADATA = "optional:properties_metadata";
+
+// src/decorators/injectable.decorator.ts
+function Injectable(options) {
+  return (target) => {
+    Reflect.defineMetadata(INJECTABLE_WATERMARK, true, target);
+    Reflect.defineMetadata(SCOPE_OPTIONS_METADATA, options, target);
+  };
+}
+function Inject(token) {
+  const hasExplicitToken = arguments.length > 0;
+  return (target, key, index) => {
+    let resolvedToken = token;
+    if (!resolvedToken && !hasExplicitToken) {
+      if (key !== void 0) {
+        resolvedToken = Reflect.getMetadata("design:type", target, key);
+      } else if (index !== void 0) {
+        const paramTypes = Reflect.getMetadata(PARAMTYPES_METADATA, target) || [];
+        resolvedToken = paramTypes[index];
+      }
+    }
+    if (resolvedToken && typeof resolvedToken === "object" && "forwardRef" in resolvedToken) {
+      resolvedToken = resolvedToken.forwardRef();
+    }
+    if (index !== void 0) {
+      const existingDeps = Reflect.getMetadata(SELF_DECLARED_DEPS_METADATA, target) || [];
+      Reflect.defineMetadata(
+        SELF_DECLARED_DEPS_METADATA,
+        [...existingDeps, { index, param: resolvedToken }],
+        target
+      );
+    } else {
+      const existingProps = Reflect.getMetadata(PROPERTY_DEPS_METADATA, target.constructor) || [];
+      Reflect.defineMetadata(
+        PROPERTY_DEPS_METADATA,
+        [...existingProps, { key, type: resolvedToken }],
+        target.constructor
+      );
+    }
+  };
+}
+function Optional() {
+  return (target, key, index) => {
+    if (index !== void 0) {
+      const existingOptional = Reflect.getMetadata(OPTIONAL_DEPS_METADATA, target) || [];
+      Reflect.defineMetadata(
+        OPTIONAL_DEPS_METADATA,
+        [...existingOptional, index],
+        target
+      );
+    } else {
+      const existingOptional = Reflect.getMetadata(OPTIONAL_PROPERTY_DEPS_METADATA, target.constructor) || [];
+      Reflect.defineMetadata(
+        OPTIONAL_PROPERTY_DEPS_METADATA,
+        [...existingOptional, key],
+        target.constructor
+      );
+    }
+  };
+}
+var VALID_MODULE_KEYS = /* @__PURE__ */ new Set(["imports", "providers", "exports"]);
+function Module(metadata) {
+  const invalidKeys = Object.keys(metadata).filter((key) => !VALID_MODULE_KEYS.has(key));
+  if (invalidKeys.length > 0) {
+    throw new Error(
+      `Invalid property '${invalidKeys.join("', '")}' passed into the @Module() decorator. Valid properties are: ${[...VALID_MODULE_KEYS].join(", ")}.`
+    );
+  }
+  return (target) => {
+    for (const property in metadata) {
+      if (Object.prototype.hasOwnProperty.call(metadata, property)) {
+        Reflect.defineMetadata(property, metadata[property], target);
+      }
+    }
+  };
+}
+function Global() {
+  return (target) => {
+    Reflect.defineMetadata(GLOBAL_MODULE_METADATA, true, target);
+  };
+}
+
+// src/interfaces/scope.enum.ts
+var Scope = /* @__PURE__ */ ((Scope2) => {
+  Scope2[Scope2["DEFAULT"] = 0] = "DEFAULT";
+  Scope2[Scope2["TRANSIENT"] = 1] = "TRANSIENT";
+  return Scope2;
+})(Scope || {});
+
+// src/utils/forward-ref.util.ts
+function forwardRef(fn) {
+  return { forwardRef: fn };
+}
+
+// src/interfaces/provider.interface.ts
+function isCustomProvider(provider) {
+  return provider !== null && typeof provider === "object" && "provide" in provider;
+}
+function isClassProvider(provider) {
+  return isCustomProvider(provider) && "useClass" in provider && provider.useClass !== void 0;
+}
+function isValueProvider(provider) {
+  return isCustomProvider(provider) && "useValue" in provider;
+}
+function isFactoryProvider(provider) {
+  return isCustomProvider(provider) && "useFactory" in provider && typeof provider.useFactory === "function";
+}
+function isExistingProvider(provider) {
+  return isCustomProvider(provider) && "useExisting" in provider && provider.useExisting !== void 0;
+}
+
+// src/injector/instance-wrapper.ts
+var InstanceWrapper = class {
+  /** 
+  * The injection token used to look up this provider. 
+  */
+  token;
+  /** 
+  * Human-readable name (class name or token string). 
+  */
+  name;
+  /**
+   * The class constructor or factory function.
+   * - For class providers: the class to `new`
+   * - For factory providers: the factory function
+   * - For value providers: `null`
+   */
+  metatype;
+  /**
+   * The resolved instance.
+   * - `null` before resolution
+   * - The actual instance after resolution
+   * - For value providers: set immediately at registration
+   */
+  instance = null;
+  /** 
+  * Whether this provider has been fully resolved (instance created). 
+  */
+  isResolved = false;
+  /** 
+  * The scope of this provider. 
+  */
+  scope = 0 /* DEFAULT */;
+  /**
+   * For factory providers: the tokens to inject as factory arguments.
+   * `null` for class and value providers.
+   */
+  inject = null;
+  /**
+   * Whether this is an alias (useExisting) provider.
+   * Alias providers delegate resolution to another token.
+   */
+  isAlias = false;
+  /** 
+  * Whether the instance is a Promise (async factory). 
+  */
+  async = false;
+  /** 
+  * The module this provider belongs to. 
+  */
+  host = null;
+  /**
+   * Create a new InstanceWrapper.
+   *
+   * @param metadata - Initial values for the wrapper properties
+   */
+  constructor(metadata = {}) {
+    this.token = metadata.token;
+    this.name = metadata.name ?? this.getTokenName(metadata.token);
+    this.metatype = metadata.metatype ?? null;
+    this.instance = metadata.instance ?? null;
+    this.isResolved = metadata.isResolved ?? false;
+    this.scope = metadata.scope ?? 0 /* DEFAULT */;
+    this.inject = metadata.inject ?? null;
+    this.isAlias = metadata.isAlias ?? false;
+    this.async = metadata.async ?? false;
+    this.host = metadata.host ?? null;
+  }
+  /**
+   * Whether this provider is a factory (has an `inject` array).
+   * Factory providers are invoked as functions, not constructed with `new`.
+   */
+  get isFactory() {
+    return this.inject !== null;
+  }
+  /**
+   * Whether this provider is transient (new instance per injection).
+   */
+  get isTransient() {
+    return this.scope === 1 /* TRANSIENT */;
+  }
+  /**
+   * Extract a human-readable name from a token.
+   */
+  getTokenName(token) {
+    if (typeof token === "function") return token.name;
+    if (typeof token === "symbol") return token.toString();
+    return String(token);
+  }
+};
+
+// src/injector/module.ts
+var Module2 = class {
+  /** 
+  * Unique identifier for this module instance. 
+  */
+  id;
+  /** 
+  * The original class decorated with @Module(). 
+  */
+  metatype;
+  /** 
+  * Whether this module is global (its exports are available everywhere). 
+  */
+  isGlobal = false;
+  /** 
+  * The opaque token used to identify this module in the container. 
+  */
+  token = "";
+  /**
+   * All providers registered in this module.
+   * Key: injection token, Value: InstanceWrapper
+   */
+  _providers = /* @__PURE__ */ new Map();
+  /** 
+  * Imported modules (their exports are available to this module). 
+  */
+  _imports = /* @__PURE__ */ new Set();
+  /** 
+  * Tokens that this module exports (available to modules that import this one). 
+  */
+  _exports = /* @__PURE__ */ new Set();
+  constructor(metatype) {
+    this.metatype = metatype;
+    this.id = `${metatype.name}_${Math.random().toString(36).slice(2, 8)}`;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Accessors
+  // ─────────────────────────────────────────────────────────────────────────
+  get name() {
+    return this.metatype.name;
+  }
+  get providers() {
+    return this._providers;
+  }
+  get imports() {
+    return this._imports;
+  }
+  get exports() {
+    return this._exports;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Provider registration
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Register a provider in this module.
+   *
+   * Handles all provider forms:
+   * - Class shorthand: `UserService`
+   * - Class provider: `{ provide: Token, useClass: UserService }`
+   * - Value provider: `{ provide: Token, useValue: someValue }`
+   * - Factory provider: `{ provide: Token, useFactory: fn, inject: [...] }`
+   * - Existing provider: `{ provide: Token, useExisting: OtherToken }`
+   *
+   * @param provider - The provider to register
+   * @returns The injection token for this provider
+   */
+  addProvider(provider) {
+    if (isCustomProvider(provider)) {
+      return this.addCustomProvider(provider);
+    }
+    const classRef = provider;
+    const scope = this.getClassScope(classRef);
+    this._providers.set(
+      classRef,
+      new InstanceWrapper({
+        token: classRef,
+        name: classRef.name,
+        metatype: classRef,
+        instance: null,
+        isResolved: false,
+        scope,
+        host: this
+      })
+    );
+    return classRef;
+  }
+  /**
+   * Register a custom provider (one with a `provide` property).
+   */
+  addCustomProvider(provider) {
+    if (isClassProvider(provider)) {
+      this.addClassProvider(provider);
+    } else if (isValueProvider(provider)) {
+      this.addValueProvider(provider);
+    } else if (isFactoryProvider(provider)) {
+      this.addFactoryProvider(provider);
+    } else if (isExistingProvider(provider)) {
+      this.addExistingProvider(provider);
+    }
+    return provider.provide;
+  }
+  /**
+   * Register a class provider: `{ provide: Token, useClass: SomeClass }`
+   */
+  addClassProvider(provider) {
+    const scope = provider.scope ?? this.getClassScope(provider.useClass);
+    this._providers.set(
+      provider.provide,
+      new InstanceWrapper({
+        token: provider.provide,
+        name: provider.useClass?.name ?? String(provider.provide),
+        metatype: provider.useClass,
+        instance: null,
+        isResolved: false,
+        scope,
+        host: this
+      })
+    );
+  }
+  /**
+   * Register a value provider: `{ provide: Token, useValue: value }`
+   *
+   * Value providers are immediately resolved — the value is stored as-is.
+   */
+  addValueProvider(provider) {
+    this._providers.set(
+      provider.provide,
+      new InstanceWrapper({
+        token: provider.provide,
+        name: this.getTokenName(provider.provide),
+        metatype: null,
+        instance: provider.useValue,
+        isResolved: true,
+        async: provider.useValue instanceof Promise,
+        host: this
+      })
+    );
+  }
+  /**
+   * Register a factory provider: `{ provide: Token, useFactory: fn, inject: [...] }`
+   *
+   * The factory function is stored as the metatype and will be called
+   * (not constructed with `new`) during resolution.
+   */
+  addFactoryProvider(provider) {
+    this._providers.set(
+      provider.provide,
+      new InstanceWrapper({
+        token: provider.provide,
+        name: this.getTokenName(provider.provide),
+        metatype: provider.useFactory,
+        instance: null,
+        isResolved: false,
+        inject: provider.inject ?? [],
+        scope: provider.scope ?? 0 /* DEFAULT */,
+        host: this
+      })
+    );
+  }
+  /**
+   * Register an existing (alias) provider: `{ provide: Token, useExisting: OtherToken }`
+   *
+   * Implemented as a factory that resolves the target token.
+   */
+  addExistingProvider(provider) {
+    this._providers.set(
+      provider.provide,
+      new InstanceWrapper({
+        token: provider.provide,
+        name: this.getTokenName(provider.provide),
+        metatype: ((instance) => instance),
+        instance: null,
+        isResolved: false,
+        inject: [provider.useExisting],
+        isAlias: true,
+        host: this
+      })
+    );
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Imports & Exports
+  // ─────────────────────────────────────────────────────────────────────────
+  /** 
+  * Add an imported module. 
+  */
+  addImport(moduleRef) {
+    this._imports.add(moduleRef);
+  }
+  /**
+   * Add an exported token.
+   *
+   * @param token - The token to export (class, string, symbol, or module class)
+   */
+  addExport(token) {
+    this._exports.add(token);
+  }
+  /**
+   * Check if this module has a provider for the given token.
+   */
+  hasProvider(token) {
+    return this._providers.has(token);
+  }
+  /**
+   * Get a provider wrapper by token.
+   */
+  getProviderByToken(token) {
+    return this._providers.get(token);
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Read the scope from a class's @Injectable() metadata.
+   */
+  getClassScope(type) {
+    const options = Reflect.getMetadata(SCOPE_OPTIONS_METADATA, type);
+    return options?.scope ?? 0 /* DEFAULT */;
+  }
+  /**
+   * Get a human-readable name from a token.
+   */
+  getTokenName(token) {
+    if (typeof token === "function") return token.name;
+    if (typeof token === "symbol") return token.toString();
+    return String(token);
+  }
+};
+
+// src/injector/container.ts
+var NestContainer = class {
+  /**
+   * All registered modules, keyed by their opaque token.
+   * The token is derived from the module class name (or a hash for dynamic modules).
+   */
+  modules = /* @__PURE__ */ new Map();
+  /**
+   * Global modules whose exports are available to all other modules.
+   */
+  globalModules = /* @__PURE__ */ new Set();
+  /**
+   * Dynamic module metadata, keyed by module token.
+   * Stored separately because dynamic metadata is merged with static @Module() metadata.
+   */
+  dynamicModulesMetadata = /* @__PURE__ */ new Map();
+  // ─────────────────────────────────────────────────────────────────────────
+  // Module registration
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Add a module to the container.
+   *
+   * If the module is already registered (by token), returns the existing one.
+   * Otherwise, creates a new Module instance and registers it.
+   *
+   * @param metatype - The module class or dynamic module
+   * @returns The Module instance and whether it was newly inserted
+   */
+  async addModule(metatype) {
+    const resolved = metatype instanceof Promise ? await metatype : metatype;
+    const { type, dynamicMetadata, token } = this.extractModuleMetadata(resolved);
+    if (this.modules.has(token)) {
+      return { moduleRef: this.modules.get(token), inserted: false };
+    }
+    const moduleRef = new Module2(type);
+    moduleRef.token = token;
+    this.modules.set(token, moduleRef);
+    if (dynamicMetadata) {
+      this.dynamicModulesMetadata.set(token, dynamicMetadata);
+    }
+    if (this.isGlobalModule(type, dynamicMetadata)) {
+      moduleRef.isGlobal = true;
+      this.globalModules.add(moduleRef);
+    }
+    return { moduleRef, inserted: true };
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Provider, Import, Export registration
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Add a provider to a module.
+   *
+   * @param provider - The provider to add
+   * @param token - The module token to add the provider to
+   */
+  addProvider(provider, token) {
+    const moduleRef = this.modules.get(token);
+    if (!moduleRef) {
+      throw new Error(`Module [${token}] not found in container.`);
+    }
+    moduleRef.addProvider(provider);
+  }
+  /**
+   * Add an import relationship between modules.
+   *
+   * @param relatedModule - The module being imported
+   * @param token - The token of the module doing the importing
+   */
+  addImport(relatedModule, token) {
+    const moduleRef = this.modules.get(token);
+    if (!moduleRef) return;
+    const { token: relatedToken } = this.extractModuleMetadata(relatedModule);
+    const related = this.modules.get(relatedToken);
+    if (related) {
+      moduleRef.addImport(related);
+    }
+  }
+  /**
+   * Add an export to a module.
+   *
+   * @param toExport - The token or provider to export
+   * @param token - The module token
+   */
+  addExport(toExport, token) {
+    const moduleRef = this.modules.get(token);
+    if (!moduleRef) return;
+    if (typeof toExport === "object" && toExport !== null && "module" in toExport) {
+      moduleRef.addExport(toExport.module);
+    } else if (typeof toExport === "object" && toExport !== null && "provide" in toExport) {
+      moduleRef.addExport(toExport.provide);
+    } else {
+      moduleRef.addExport(toExport);
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Global scope binding
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Link all global modules to all non-global modules as imports.
+   *
+   * Called after all modules have been scanned. This makes global modules'
+   * exports available everywhere without explicit imports.
+   */
+  bindGlobalScope() {
+    for (const moduleRef of this.modules.values()) {
+      for (const globalModule of this.globalModules) {
+        if (moduleRef !== globalModule) {
+          moduleRef.addImport(globalModule);
+        }
+      }
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Accessors
+  // ─────────────────────────────────────────────────────────────────────────
+  /** 
+  * Get all registered modules. 
+  */
+  getModules() {
+    return this.modules;
+  }
+  /** 
+  * Get a module by its token. 
+  */
+  getModuleByToken(token) {
+    return this.modules.get(token);
+  }
+  getDynamicMetadata(token, key) {
+    const metadata = this.dynamicModulesMetadata.get(token);
+    if (!metadata) return key ? [] : void 0;
+    return key ? metadata[key] ?? [] : metadata;
+  }
+  /** 
+  * Clear all modules (for testing). 
+  */
+  clear() {
+    this.modules.clear();
+    this.globalModules.clear();
+    this.dynamicModulesMetadata.clear();
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Extract the module class, dynamic metadata, and token from a module definition.
+   *
+   * Handles both static modules (just a class) and dynamic modules
+   * (objects with a `module` property).
+   */
+  extractModuleMetadata(metatype) {
+    if (this.isDynamicModule(metatype)) {
+      const { module: type, ...dynamicMetadata } = metatype;
+      return {
+        type,
+        dynamicMetadata,
+        token: type.name
+      };
+    }
+    return {
+      type: metatype,
+      dynamicMetadata: void 0,
+      token: metatype.name
+    };
+  }
+  /**
+   * Check if a module definition is a dynamic module (has a `module` property).
+   */
+  isDynamicModule(metatype) {
+    return metatype && !!metatype.module;
+  }
+  /**
+   * Check if a module should be global.
+   * A module is global if:
+   * - It has the @Global() decorator, OR
+   * - Its dynamic metadata has `global: true`
+   */
+  isGlobalModule(type, dynamicMetadata) {
+    if (dynamicMetadata?.global) return true;
+    return !!Reflect.getMetadata(GLOBAL_MODULE_METADATA, type);
+  }
+};
+var Injector = class {
+  /**
+   * Tracks which wrappers are currently being resolved, to detect circular dependencies.
+   * Uses a Set of tokens being resolved in the current chain.
+   */
+  resolutionStack = /* @__PURE__ */ new Set();
+  // ─────────────────────────────────────────────────────────────────────────
+  // Public API
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Resolve all providers in a module.
+   *
+   * Iterates over all providers and resolves each one.
+   * Value providers are already resolved at registration time.
+   *
+   * @param moduleRef - The module whose providers to resolve
+   */
+  async resolveProviders(moduleRef) {
+    const providers = moduleRef.providers;
+    for (const [_token, wrapper] of providers) {
+      if (!wrapper.isResolved) {
+        await this.resolveInstance(wrapper, moduleRef);
+      }
+    }
+  }
+  /**
+   * Resolve a single provider instance.
+   *
+   * This is the core resolution method. It handles:
+   * - Already-resolved singletons (returns cached instance)
+   * - Circular dependency detection
+   * - Factory providers (calls the factory function)
+   * - Class providers (resolves constructor deps, then `new`)
+   * - Property injection (after construction)
+   * - Async factories (awaits the result)
+   *
+   * @param wrapper - The InstanceWrapper to resolve
+   * @param moduleRef - The module context for dependency lookup
+   */
+  async resolveInstance(wrapper, moduleRef) {
+    if (wrapper.isResolved && !wrapper.isTransient) {
+      return wrapper.instance;
+    }
+    if (this.resolutionStack.has(wrapper.token)) {
+      throw new Error(
+        `Circular dependency detected: ${this.formatResolutionStack(wrapper.token)}`
+      );
+    }
+    this.resolutionStack.add(wrapper.token);
+    try {
+      let instance;
+      if (wrapper.isFactory) {
+        instance = await this.resolveFactory(wrapper, moduleRef);
+      } else if (wrapper.metatype) {
+        instance = await this.resolveClass(wrapper, moduleRef);
+      } else {
+        instance = wrapper.instance;
+      }
+      wrapper.instance = instance;
+      wrapper.isResolved = true;
+      return instance;
+    } finally {
+      this.resolutionStack.delete(wrapper.token);
+    }
+  }
+  /**
+   * Look up a provider by token, searching the module and its imports.
+   *
+   * Resolution order:
+   * 1. The module's own providers
+   * 2. Imported modules' exported providers (breadth-first)
+   *
+   * @param token - The injection token to look up
+   * @param moduleRef - The module context
+   * @returns The InstanceWrapper and the module it was found in
+   */
+  lookupProvider(token, moduleRef) {
+    if (moduleRef.providers.has(token)) {
+      return { wrapper: moduleRef.providers.get(token), host: moduleRef };
+    }
+    return this.lookupInImports(token, moduleRef, /* @__PURE__ */ new Set());
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Class resolution
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Resolve a class provider by:
+   * 1. Reading constructor parameter types from metadata
+   * 2. Resolving each dependency
+   * 3. Calling `new Class(...deps)`
+   * 4. Applying property injection
+   */
+  async resolveClass(wrapper, moduleRef) {
+    const metatype = wrapper.metatype;
+    const deps = this.getConstructorDependencies(metatype);
+    const optionalIndices = this.getOptionalDependencies(metatype);
+    const resolvedDeps = await Promise.all(
+      deps.map(async (dep, index) => {
+        if (dep === void 0 || dep === null || dep === Object) {
+          if (optionalIndices.includes(index)) return void 0;
+          throw new Error(
+            `Cannot resolve dependency at index [${index}] of ${metatype.name}. The dependency is undefined \u2014 this usually means a circular import or missing @Inject() decorator.`
+          );
+        }
+        try {
+          return await this.resolveDependency(dep, moduleRef);
+        } catch (err) {
+          if (optionalIndices.includes(index)) return void 0;
+          throw new Error(
+            `Cannot resolve dependency '${this.getTokenName(dep)}' at index [${index}] of ${metatype.name}. Make sure it is provided in the module or imported. Original: ${err.message}`
+          );
+        }
+      })
+    );
+    const instance = new metatype(...resolvedDeps);
+    await this.resolveProperties(instance, metatype, moduleRef);
+    return instance;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Factory resolution
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Resolve a factory provider by:
+   * 1. Resolving the factory's `inject` dependencies
+   * 2. Calling the factory function with the resolved deps
+   * 3. Awaiting the result if it's a Promise
+   */
+  async resolveFactory(wrapper, moduleRef) {
+    const factory = wrapper.metatype;
+    const injectTokens = wrapper.inject ?? [];
+    const resolvedDeps = await Promise.all(
+      injectTokens.map(async (token) => {
+        try {
+          return await this.resolveDependency(token, moduleRef);
+        } catch (err) {
+          throw new Error(
+            `Cannot resolve factory dependency '${this.getTokenName(token)}' for provider '${wrapper.name}'. ${err.message}`
+          );
+        }
+      })
+    );
+    const result = factory(...resolvedDeps);
+    return result instanceof Promise ? await result : result;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Dependency resolution
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Resolve a single dependency token to its instance.
+   *
+   * Looks up the provider, resolves it if needed, and returns the instance.
+   */
+  async resolveDependency(token, moduleRef) {
+    const result = this.lookupProvider(token, moduleRef);
+    if (!result) {
+      throw new Error(
+        `Provider '${this.getTokenName(token)}' not found. Is it provided in the current module or an imported module?`
+      );
+    }
+    const { wrapper, host } = result;
+    if (!wrapper.isResolved || wrapper.isTransient) {
+      return this.resolveInstance(wrapper, host);
+    }
+    if (wrapper.async && wrapper.instance instanceof Promise) {
+      wrapper.instance = await wrapper.instance;
+    }
+    return wrapper.instance;
+  }
+  /**
+   * Look up a provider in imported modules' exports.
+   *
+   * Searches breadth-first through the import tree, only considering
+   * providers that are in the imported module's exports set.
+   */
+  lookupInImports(token, moduleRef, visited) {
+    for (const importedModule of moduleRef.imports) {
+      if (visited.has(importedModule.id)) continue;
+      visited.add(importedModule.id);
+      if (importedModule.exports.has(token) && importedModule.providers.has(token)) {
+        return {
+          wrapper: importedModule.providers.get(token),
+          host: importedModule
+        };
+      }
+      const result = this.lookupInImports(token, importedModule, visited);
+      if (result) return result;
+    }
+    return void 0;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Metadata reading
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Get the constructor dependencies for a class.
+   *
+   * Merges TypeScript's auto-emitted `design:paramtypes` with
+   * explicitly declared `self:paramtypes` (from @Inject decorators).
+   * Explicit declarations override auto-detected types.
+   *
+   * @param type - The class to read metadata from
+   * @returns Array of injection tokens, one per constructor parameter
+   */
+  getConstructorDependencies(type) {
+    const paramTypes = [
+      ...Reflect.getMetadata(PARAMTYPES_METADATA, type) || []
+    ];
+    const selfDeclared = Reflect.getMetadata(SELF_DECLARED_DEPS_METADATA, type) || [];
+    for (const { index, param } of selfDeclared) {
+      paramTypes[index] = param;
+    }
+    return paramTypes;
+  }
+  /**
+   * Get the indices of optional constructor parameters.
+   */
+  getOptionalDependencies(type) {
+    return Reflect.getMetadata(OPTIONAL_DEPS_METADATA, type) || [];
+  }
+  /**
+   * Resolve property-injected dependencies and assign them to the instance.
+   */
+  async resolveProperties(instance, type, moduleRef) {
+    const properties = Reflect.getMetadata(PROPERTY_DEPS_METADATA, type) || [];
+    const optionalKeys = Reflect.getMetadata(OPTIONAL_PROPERTY_DEPS_METADATA, type) || [];
+    for (const prop of properties) {
+      const isOptional = optionalKeys.includes(prop.key);
+      try {
+        const resolved = await this.resolveDependency(prop.type, moduleRef);
+        instance[prop.key] = resolved;
+      } catch (err) {
+        if (!isOptional) throw err;
+      }
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Format the resolution stack for error messages.
+   */
+  formatResolutionStack(token) {
+    const stack = [...this.resolutionStack, token];
+    return stack.map((t) => this.getTokenName(t)).join(" \u2192 ");
+  }
+  /**
+   * Get a human-readable name from a token.
+   */
+  getTokenName(token) {
+    if (typeof token === "function") return token.name;
+    if (typeof token === "symbol") return token.toString();
+    return String(token);
+  }
+};
+
+// src/interfaces/lifecycle.interface.ts
+function hasOnModuleInit(instance) {
+  return instance && typeof instance.onModuleInit === "function";
+}
+function hasOnModuleDestroy(instance) {
+  return instance && typeof instance.onModuleDestroy === "function";
+}
+
+// src/injector/instance-loader.ts
+var InstanceLoader = class {
+  constructor(container) {
+    this.container = container;
+    this.injector = new Injector();
+  }
+  container;
+  injector;
+  /**
+   * Instantiate all providers in all modules.
+   *
+   * Iterates modules and resolves each module's providers.
+   * After all providers are resolved, calls `onModuleInit()` lifecycle hooks.
+   */
+  async createInstances() {
+    const modules = this.container.getModules();
+    for (const [, moduleRef] of modules) {
+      await this.injector.resolveProviders(moduleRef);
+    }
+    for (const [, moduleRef] of modules) {
+      await this.callModuleInitHooks(moduleRef);
+    }
+  }
+  /**
+   * Call `onModuleDestroy()` on all providers that implement it.
+   *
+   * Called during application shutdown. Iterates modules in reverse
+   * order (leaf modules first, root module last).
+   */
+  async destroy() {
+    const modules = [...this.container.getModules().values()].reverse();
+    for (const moduleRef of modules) {
+      await this.callModuleDestroyHooks(moduleRef);
+    }
+  }
+  /**
+   * Get the injector instance (for direct resolution outside the module system).
+   */
+  getInjector() {
+    return this.injector;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Lifecycle hooks
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Call `onModuleInit()` on all resolved providers in a module.
+   */
+  async callModuleInitHooks(moduleRef) {
+    for (const [, wrapper] of moduleRef.providers) {
+      if (wrapper.isResolved && wrapper.instance && hasOnModuleInit(wrapper.instance)) {
+        await wrapper.instance.onModuleInit();
+      }
+    }
+  }
+  /**
+   * Call `onModuleDestroy()` on all resolved providers in a module.
+   */
+  async callModuleDestroyHooks(moduleRef) {
+    for (const [, wrapper] of moduleRef.providers) {
+      if (wrapper.isResolved && wrapper.instance && hasOnModuleDestroy(wrapper.instance)) {
+        await wrapper.instance.onModuleDestroy();
+      }
+    }
+  }
+};
+var DependenciesScanner = class {
+  constructor(container) {
+    this.container = container;
+  }
+  container;
+  /**
+   * Scan the entire module tree starting from the root module.
+   *
+   * This is the main entry point. After this method completes,
+   * the container has all modules, providers, imports, and exports
+   * registered — but no instances created.
+   *
+   * @param rootModule - The root module class (your AppModule)
+   */
+  async scan(rootModule) {
+    await this.scanForModules(rootModule, []);
+    await this.scanModulesForDependencies();
+    this.container.bindGlobalScope();
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Phase 1: Module discovery
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Recursively discover and register all modules in the graph.
+   *
+   * Uses DFS traversal. Tracks visited modules to avoid infinite loops
+   * from circular imports.
+   *
+   * @param moduleDefinition - The module to scan (class or dynamic module)
+   * @param ctxRegistry - Already-visited modules (for cycle detection)
+   */
+  async scanForModules(moduleDefinition, ctxRegistry) {
+    const resolved = this.resolveForwardRef(moduleDefinition);
+    if (!resolved) return;
+    if (ctxRegistry.includes(resolved)) return;
+    ctxRegistry.push(resolved);
+    await this.container.addModule(resolved);
+    const imports = this.getModuleImports(resolved);
+    for (const importedModule of imports) {
+      if (importedModule === void 0 || importedModule === null) {
+        const moduleName = this.getModuleName(resolved);
+        throw new Error(
+          `An undefined module was imported by ${moduleName}. This is usually caused by a circular dependency. Use forwardRef() to resolve it.`
+        );
+      }
+      await this.scanForModules(importedModule, ctxRegistry);
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Phase 2: Dependency registration
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * For each registered module, read its metadata and register
+   * providers, imports, and exports.
+   */
+  async scanModulesForDependencies() {
+    const modules = this.container.getModules();
+    for (const [token, moduleRef] of modules) {
+      await this.reflectImports(moduleRef.metatype, token);
+      this.reflectProviders(moduleRef.metatype, token);
+      this.reflectExports(moduleRef.metatype, token);
+    }
+  }
+  /**
+   * Read and register a module's imports.
+   *
+   * Merges static @Module({ imports }) with dynamic module imports.
+   */
+  async reflectImports(metatype, token) {
+    const staticImports = Reflect.getMetadata(MODULE_METADATA.IMPORTS, metatype) || [];
+    const dynamicImports = this.container.getDynamicMetadata(token, "imports") || [];
+    const allImports = [...staticImports, ...dynamicImports];
+    for (const related of allImports) {
+      const resolved = this.resolveForwardRef(related);
+      if (resolved) {
+        this.container.addImport(resolved, token);
+      }
+    }
+  }
+  /**
+   * Read and register a module's providers.
+   *
+   * Merges static @Module({ providers }) with dynamic module providers.
+   */
+  reflectProviders(metatype, token) {
+    const staticProviders = Reflect.getMetadata(MODULE_METADATA.PROVIDERS, metatype) || [];
+    const dynamicProviders = this.container.getDynamicMetadata(token, "providers") || [];
+    const allProviders = [...staticProviders, ...dynamicProviders];
+    for (const provider of allProviders) {
+      this.container.addProvider(provider, token);
+    }
+  }
+  /**
+   * Read and register a module's exports.
+   *
+   * Merges static @Module({ exports }) with dynamic module exports.
+   */
+  reflectExports(metatype, token) {
+    const staticExports = Reflect.getMetadata(MODULE_METADATA.EXPORTS, metatype) || [];
+    const dynamicExports = this.container.getDynamicMetadata(token, "exports") || [];
+    const allExports = [...staticExports, ...dynamicExports];
+    for (const exported of allExports) {
+      const resolved = this.resolveForwardRef(exported);
+      this.container.addExport(resolved ?? exported, token);
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Get a module's imports from both static and dynamic sources.
+   */
+  getModuleImports(moduleDefinition) {
+    if (this.isDynamicModule(moduleDefinition)) {
+      const staticImports = Reflect.getMetadata(MODULE_METADATA.IMPORTS, moduleDefinition.module) || [];
+      const dynamicImports = moduleDefinition.imports || [];
+      return [...staticImports, ...dynamicImports];
+    }
+    return Reflect.getMetadata(MODULE_METADATA.IMPORTS, moduleDefinition) || [];
+  }
+  /**
+   * Resolve a forward reference to its actual value.
+   */
+  resolveForwardRef(ref) {
+    if (ref && typeof ref === "object" && "forwardRef" in ref) {
+      return ref.forwardRef();
+    }
+    return ref;
+  }
+  /**
+   * Check if a module definition is a dynamic module.
+   */
+  isDynamicModule(module) {
+    return module && !!module.module;
+  }
+  /**
+   * Get a human-readable name for a module.
+   */
+  getModuleName(module) {
+    if (this.isDynamicModule(module)) return module.module.name;
+    if (typeof module === "function") return module.name;
+    return String(module);
+  }
+};
+
+exports.DependenciesScanner = DependenciesScanner;
+exports.GLOBAL_MODULE_METADATA = GLOBAL_MODULE_METADATA;
+exports.Global = Global;
+exports.INJECTABLE_WATERMARK = INJECTABLE_WATERMARK;
+exports.Inject = Inject;
+exports.Injectable = Injectable;
+exports.Injector = Injector;
+exports.InstanceLoader = InstanceLoader;
+exports.InstanceWrapper = InstanceWrapper;
+exports.MODULE_METADATA = MODULE_METADATA;
+exports.Module = Module;
+exports.ModuleRef = Module2;
+exports.NestContainer = NestContainer;
+exports.OPTIONAL_DEPS_METADATA = OPTIONAL_DEPS_METADATA;
+exports.OPTIONAL_PROPERTY_DEPS_METADATA = OPTIONAL_PROPERTY_DEPS_METADATA;
+exports.Optional = Optional;
+exports.PARAMTYPES_METADATA = PARAMTYPES_METADATA;
+exports.PROPERTY_DEPS_METADATA = PROPERTY_DEPS_METADATA;
+exports.SCOPE_OPTIONS_METADATA = SCOPE_OPTIONS_METADATA;
+exports.SELF_DECLARED_DEPS_METADATA = SELF_DECLARED_DEPS_METADATA;
+exports.Scope = Scope;
+exports.forwardRef = forwardRef;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map