@husky-di/module 1.0.0 → 1.1.0

package/dist/enums/module-error-code.enum.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @overview Module error code enum.
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+export declare enum ModuleErrorCodeEnum {
+    /**
+     * Module contains multiple declarations with the same ServiceIdentifier.
+     * @see SPECIFICATION.md Section 4.1 D1
+     */
+    E_DUPLICATE_DECLARATION = "E_DUPLICATE_DECLARATION",
+    /**
+     * Declaration lacks valid registration strategy (useClass, useFactory, useValue, or useAlias).
+     * @see SPECIFICATION.md Section 4.1 D2
+     */
+    E_INVALID_REGISTRATION = "E_INVALID_REGISTRATION",
+    /**
+     * Same module instance imported multiple times in a single import list.
+     * @see SPECIFICATION.md Section 4.2 I1
+     */
+    E_DUPLICATE_IMPORT_MODULE = "E_DUPLICATE_IMPORT_MODULE",
+    /**
+     * Circular dependency detected in module import graph.
+     * @see SPECIFICATION.md Section 4.2 I2
+     */
+    E_CIRCULAR_DEPENDENCY = "E_CIRCULAR_DEPENDENCY",
+    /**
+     * Multiple imported modules export the same ServiceIdentifier without alias resolution.
+     * @see SPECIFICATION.md Section 4.2 I3
+     */
+    E_IMPORT_COLLISION = "E_IMPORT_COLLISION",
+    /**
+     * Imported ServiceIdentifier conflicts with a local declaration in the importing module.
+     * @see SPECIFICATION.md Section 4.2 I4
+     */
+    E_IMPORT_CONFLICT_LOCAL = "E_IMPORT_CONFLICT_LOCAL",
+    /**
+     * Alias source ServiceIdentifier is not exported by the source module.
+     * @see SPECIFICATION.md Section 5.1 Resolution Logic
+     */
+    E_ALIAS_SOURCE_NOT_EXPORTED = "E_ALIAS_SOURCE_NOT_EXPORTED",
+    /**
+     * Same source ServiceIdentifier mapped multiple times within a single alias list.
+     * @see SPECIFICATION.md Section 5.1 Resolution Logic
+     */
+    E_DUPLICATE_ALIAS_MAP = "E_DUPLICATE_ALIAS_MAP",
+    /**
+     * Export references a ServiceIdentifier that is neither declared locally nor imported.
+     * @see SPECIFICATION.md Section 4.3 E1
+     */
+    E_EXPORT_NOT_FOUND = "E_EXPORT_NOT_FOUND",
+    /**
+     * Same ServiceIdentifier exported multiple times from a single module.
+     * @see SPECIFICATION.md Section 4.3 E2
+     */
+    E_DUPLICATE_EXPORT = "E_DUPLICATE_EXPORT"
+}

package/dist/exceptions/module.exception.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @overview Module package exception.
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+import { CodedException } from "@husky-di/core";
+import type { ModuleErrorCode } from "../types/module-error-code.type";
+export declare class ModuleException extends CodedException<ModuleErrorCode> {
+    /** Internal marker to identify ModuleException instances across frames. */
+    private __isModuleException__;
+    static isModuleException(error: unknown): error is ModuleException;
+}

package/dist/factories/exported-guard-middleware.factory.d.ts

@@ -1,7 +1,38 @@
 /**
+ * Factory for creating export guard middleware.
+ *
  * @overview
+ * This middleware enforces export restrictions for module containers. It ensures
+ * that only explicitly exported service identifiers can be accessed from outside
+ * the container. Internal access (within the same container) is always allowed.
+ *
+ * @remarks
+ * The middleware distinguishes between internal and external access by checking
+ * the resolution path. If the previous resolution step occurred in the same
+ * container, it's considered internal access. Otherwise, it's external access
+ * and must be in the exports list.
+ *
  * @author AEPKILL
  * @created 2025-08-18 22:01:34
  */
 import { type ResolveMiddleware, type ServiceIdentifier } from "@husky-di/core";
-export declare function createExportedGuardMiddlewareFactory(exports: ServiceIdentifier<unknown>[]): ResolveMiddleware<any, any>;
+/**
+ * Creates a middleware factory that guards against accessing non-exported services.
+ *
+ * @param exports - Array of service identifiers that are allowed to be accessed from outside the container
+ * @returns A resolve middleware that enforces export restrictions
+ *
+ * @remarks
+ * The middleware works by:
+ * 1. Checking if the current resolution is from within the same container (internal access)
+ * 2. If external access is detected, verifying that the service identifier is in the exports list
+ * 3. Throwing a ResolveException if a non-exported service is accessed externally
+ *
+ * Note: Services not registered in the container are not considered external access,
+ * as they will be resolved from parent containers or fail with a different error.
+ *
+ * @important Do not remove this middleware from the container once registered.
+ * Removing this middleware will disable export protection and allow external access
+ * to non-exported services.
+ */
+export declare function createExportedGuardMiddleware(exports: ReadonlyArray<ServiceIdentifier<unknown>>): ResolveMiddleware<any, any>;

package/dist/factories/import-scope.factory.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Import scope factory.
+ *
+ * @overview
+ * Creates the normalized import visibility model for module imports.
+ *
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+import type { IModule, ModuleWithAliases } from "../interfaces/module.interface";
+import type { ImportScope } from "../types/import-scope.type";
+export declare function createImportScope(imports?: ReadonlyArray<IModule | ModuleWithAliases>): ImportScope;

package/dist/impls/{module.d.ts → ModuleImpl.d.ts}

@@ -1,11 +1,11 @@
 /**
- * @overview
+ * @overview Module implementation.
  * @author AEPKILL
  * @created 2025-08-09 14:51:09
  */
-import type { IContainer, IsRegisteredOptions, ResolveInstance, ResolveMiddleware, ResolveOptions, ServiceIdentifier } from "@husky-di/core";
+import { type Cleanup, type IContainer, type IsRegisteredOptions, type ResolveInstance, type ResolveMiddleware, type ResolveOptions, type ServiceIdentifier } from "@husky-di/core";
 import type { Alias, CreateModuleOptions, Declaration, IModule, ModuleWithAliases } from "../interfaces/module.interface";
-export declare class Module implements IModule {
+export declare class ModuleImpl implements IModule {
     get id(): string;
     get name(): string;
     get declarations(): Declaration<unknown>[] | undefined;
@@ -13,16 +13,23 @@ export declare class Module implements IModule {
     get imports(): (IModule | ModuleWithAliases)[] | undefined;
     get displayName(): string;
     readonly container: IContainer;
-    private _id;
-    private _name;
-    private _declarations?;
-    private _imports?;
-    private _exports?;
+    private readonly _id;
+    private readonly _name;
+    private readonly _declarations?;
+    private readonly _imports?;
+    private readonly _exports?;
+    private readonly _importScope;
     constructor(options: CreateModuleOptions);
     resolve<T, O extends ResolveOptions<T>>(serviceIdentifier: ServiceIdentifier<T>, options?: O): ResolveInstance<T, O>;
     isRegistered<T>(serviceIdentifier: ServiceIdentifier<T>, options?: IsRegisteredOptions): boolean;
     getServiceIdentifiers(): ServiceIdentifier<unknown>[];
-    use(middleware: ResolveMiddleware<any, any>): void;
-    unused(middleware: ResolveMiddleware<any, any>): void;
+    use(...middleware: ResolveMiddleware<any, any>[]): Cleanup;
+    unused(...middleware: ResolveMiddleware<any, any>[]): void;
     withAliases(aliases: Alias[]): ModuleWithAliases;
+    private buildContainer;
+    private validateConfiguration;
+    private validateImports;
+    private registerDeclarations;
+    private registerImports;
+    private validateExports;
 }

package/dist/index.cjs

@@ -13,7 +13,7 @@ var __webpack_require__ = {};
 })();
 (()=>{
     __webpack_require__.r = (exports1)=>{
-        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
             value: 'Module'
         });
         Object.defineProperty(exports1, '__esModule', {
@@ -24,10 +24,31 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    ModuleErrorCodeEnum: ()=>module_error_code_enum_ModuleErrorCodeEnum,
+    ModuleException: ()=>ModuleException,
     createModule: ()=>createModule
 });
+var module_error_code_enum_ModuleErrorCodeEnum = /*#__PURE__*/ function(ModuleErrorCodeEnum) {
+    ModuleErrorCodeEnum["E_DUPLICATE_DECLARATION"] = "E_DUPLICATE_DECLARATION";
+    ModuleErrorCodeEnum["E_INVALID_REGISTRATION"] = "E_INVALID_REGISTRATION";
+    ModuleErrorCodeEnum["E_DUPLICATE_IMPORT_MODULE"] = "E_DUPLICATE_IMPORT_MODULE";
+    ModuleErrorCodeEnum["E_CIRCULAR_DEPENDENCY"] = "E_CIRCULAR_DEPENDENCY";
+    ModuleErrorCodeEnum["E_IMPORT_COLLISION"] = "E_IMPORT_COLLISION";
+    ModuleErrorCodeEnum["E_IMPORT_CONFLICT_LOCAL"] = "E_IMPORT_CONFLICT_LOCAL";
+    ModuleErrorCodeEnum["E_ALIAS_SOURCE_NOT_EXPORTED"] = "E_ALIAS_SOURCE_NOT_EXPORTED";
+    ModuleErrorCodeEnum["E_DUPLICATE_ALIAS_MAP"] = "E_DUPLICATE_ALIAS_MAP";
+    ModuleErrorCodeEnum["E_EXPORT_NOT_FOUND"] = "E_EXPORT_NOT_FOUND";
+    ModuleErrorCodeEnum["E_DUPLICATE_EXPORT"] = "E_DUPLICATE_EXPORT";
+    return ModuleErrorCodeEnum;
+}({});
 const core_namespaceObject = require("@husky-di/core");
-function createExportedGuardMiddlewareFactory(exports1) {
+class ModuleException extends core_namespaceObject.CodedException {
+    __isModuleException__ = true;
+    static isModuleException(error) {
+        return error?.__isModuleException__ === true;
+    }
+}
+function createExportedGuardMiddleware(exports1) {
     const exportedSet = new Set(exports1);
     return {
         name: "ExportGuard",
@@ -38,7 +59,7 @@ function createExportedGuardMiddlewareFactory(exports1) {
             if (!exportedSet.has(serviceIdentifier)) {
                 if (container.isRegistered(serviceIdentifier, {
                     recursive: true
-                })) throw new core_namespaceObject.ResolveException(`Service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" is not exported from ${container.displayName}.`, resolveRecord);
+                })) throw new core_namespaceObject.ResolveException(module_error_code_enum_ModuleErrorCodeEnum.E_EXPORT_NOT_FOUND, `Service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" is not exported from ${container.displayName}.`, resolveRecord);
             }
             return next(params);
         }
@@ -51,170 +72,131 @@ function findPreviousContainer(paths) {
         lastContainer = path.value.container;
     }
 }
-function isModuleWithAliases(moduleImport) {
-    return moduleImport.module instanceof Module;
+function isModuleWithAliases(item) {
+    return "module" in item;
 }
-function getModuleByImport(moduleImport) {
-    return isModuleWithAliases(moduleImport) ? moduleImport.module : moduleImport;
+function createImportScope(imports) {
+    const bindings = (imports ?? []).flatMap((item)=>{
+        const sourceModule = isModuleWithAliases(item) ? item.module : item;
+        const aliases = isModuleWithAliases(item) ? item.aliases ?? [] : [];
+        const aliasMap = createAliasMap(aliases);
+        return (sourceModule.exports ?? []).map((sourceServiceIdentifier)=>{
+            const localServiceIdentifier = aliasMap.get(sourceServiceIdentifier) ?? sourceServiceIdentifier;
+            return {
+                sourceModule,
+                sourceServiceIdentifier,
+                localServiceIdentifier,
+                isAliased: aliasMap.has(sourceServiceIdentifier)
+            };
+        });
+    });
+    return {
+        bindings,
+        visibleServiceIdentifiers: new Set(bindings.map((binding)=>binding.localServiceIdentifier))
+    };
 }
-function build(module) {
-    const builder = new ModuleBuilder(module);
-    return builder.build();
+function createAliasMap(aliases) {
+    return new Map(aliases.map((alias)=>[
+            alias.serviceIdentifier,
+            alias.as
+        ]));
 }
-class ModuleBuilder {
-    module;
-    serviceIdentifierMap = new Map();
-    availableServiceIdentifiers = new Set();
-    importAliasesCache = new Map();
-    constructor(module){
-        this.module = module;
-    }
-    build() {
-        this.validateAndCollectInfo();
-        if (this.module.container) return this.module.container;
-        const container = (0, core_namespaceObject.createContainer)(this.module.name);
-        if (this.module.exports?.length) container.use(createExportedGuardMiddlewareFactory(this.module.exports));
-        this.registerDeclarations(container);
-        this.registerImports(container);
-        return container;
-    }
-    validateAndCollectInfo() {
-        this.validateImportUniqueness();
-        this.validateExportUniqueness();
-        this.validateCircularDependencies();
-        this.collectServiceInfoAndValidateConflicts();
-        this.validateExportValidity();
-    }
-    validateImportUniqueness() {
-        const { imports } = this.module;
-        if (!imports?.length) return;
-        const importModules = new Set();
-        for (const importModule of imports)try {
-            const importedModule = getModuleByImport(importModule);
-            if (importModules.has(importedModule)) throw new Error(`Duplicate import module: "${importedModule.displayName}" in "${this.module.displayName}".`);
-            importModules.add(importedModule);
-        } catch (error) {
-            throw new Error(`Invalid module import in "${this.module.displayName}": ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
+function validateDeclarations(moduleName, declarations) {
+    if (!declarations || 0 === declarations.length) return;
+    const seen = new Set();
+    for (const decl of declarations){
+        const { serviceIdentifier } = decl;
+        if (seen.has(serviceIdentifier)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_DECLARATION, `Duplicate declaration of service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" in module "${moduleName}".`);
+        seen.add(serviceIdentifier);
+        const hasValidOption = "useClass" in decl || "useFactory" in decl || "useValue" in decl || "useAlias" in decl;
+        if (!hasValidOption) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_INVALID_REGISTRATION, `Invalid registration options for service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" in module "${moduleName}": must specify useClass, useFactory, useValue, or useAlias.`);
     }
-    validateExportUniqueness() {
-        const { exports: exports1 } = this.module;
-        if (!exports1?.length) return;
-        const existingExportServiceIdentifiers = new Set();
-        for (const exported of exports1){
-            if (existingExportServiceIdentifiers.has(exported)) throw new Error(`Duplicate export service identifier: "${(0, core_namespaceObject.getServiceIdentifierName)(exported)}" in "${this.module.displayName}".`);
-            existingExportServiceIdentifiers.add(exported);
-        }
-    }
-    validateCircularDependencies() {
-        const visited = new Set();
-        const visiting = new Set();
-        const dependencyPath = [];
-        this.detectCircularDependency(this.module, visited, visiting, dependencyPath);
-    }
-    detectCircularDependency(currentModule, visited, visiting, dependencyPath) {
-        if (visited.has(currentModule)) return;
-        if (visiting.has(currentModule)) {
-            const cycleStartIndex = dependencyPath.findIndex((module)=>module === currentModule);
-            const cyclePath = dependencyPath.slice(cycleStartIndex).concat(currentModule).map((module)=>module.displayName).join(" -> ");
-            throw new Error(`Circular dependency detected: ${cyclePath}. Modules cannot have circular import relationships.`);
-        }
-        visiting.add(currentModule);
-        dependencyPath.push(currentModule);
-        const imports = currentModule.imports ?? [];
-        for (const importModule of imports)try {
-            const importedModule = getModuleByImport(importModule);
-            this.detectCircularDependency(importedModule, visited, visiting, dependencyPath);
-        } catch (error) {
-            if (error instanceof Error && error.message.includes("Circular dependency detected")) throw error;
-            throw new Error(`Failed to validate circular dependencies for "${currentModule.displayName}": ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
-        visiting.delete(currentModule);
-        dependencyPath.pop();
-        visited.add(currentModule);
-    }
-    collectServiceInfoAndValidateConflicts() {
-        const { imports, declarations } = this.module;
-        if (declarations?.length) for (const declaration of declarations){
-            this.serviceIdentifierMap.set(declaration.serviceIdentifier, {
-                type: "declaration",
-                source: "declarations"
-            });
-            this.availableServiceIdentifiers.add(declaration.serviceIdentifier);
-        }
-        if (imports?.length) for (const importModule of imports)try {
-            const importedModule = getModuleByImport(importModule);
-            const exportedServices = importedModule.exports ?? [];
-            const aliasesMap = this.buildAndCacheAliasesMap(importModule, importedModule);
-            for (const exported of exportedServices){
-                const existing = this.serviceIdentifierMap.get(exported);
-                if (existing) {
-                    const conflictInfo = {
-                        serviceName: (0, core_namespaceObject.getServiceIdentifierName)(exported),
-                        currentModule: importedModule.displayName,
-                        existing,
-                        targetModule: this.module.displayName
-                    };
-                    throw new Error(this.buildConflictMessage(conflictInfo));
-                }
-                this.serviceIdentifierMap.set(exported, {
-                    type: "import",
-                    source: importedModule.displayName
-                });
-                this.availableServiceIdentifiers.add(exported);
-                const alias = aliasesMap.get(exported);
-                if (alias) this.availableServiceIdentifiers.add(alias);
-            }
-        } catch (error) {
-            throw new Error(`Failed to validate imports in "${this.module.displayName}": ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
+}
+function validateImportUniqueness(moduleName, imports) {
+    const seenModules = new Set();
+    for (const item of imports){
+        const importedModule = isModuleWithAliases(item) ? item.module : item;
+        const moduleId = importedModule.id;
+        if (seenModules.has(moduleId)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_IMPORT_MODULE, `Duplicate import module: "${importedModule.displayName}" in "${moduleName}".`);
+        seenModules.add(moduleId);
     }
-    validateExportValidity() {
-        const { exports: exports1 } = this.module;
-        if (!exports1?.length) return;
-        for (const exported of exports1)if (!this.availableServiceIdentifiers.has(exported)) throw new Error(`Cannot export service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(exported)}" from "${this.module.displayName}": it is not declared in this module or imported from any imported module.`);
+}
+function validateImportAliases(imports) {
+    for (const item of imports)if (isModuleWithAliases(item)) validateAliases(item.module.displayName, item.aliases ?? [], item.module.exports);
+}
+function detectCircularDependencies(module, visitedModules = new Set(), visitStack = []) {
+    if (visitStack.includes(module)) {
+        const cycle = [
+            ...visitStack.slice(visitStack.indexOf(module)),
+            module
+        ];
+        const cyclePath = cycle.map((m)=>m.displayName).join(" → ");
+        throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_CIRCULAR_DEPENDENCY, `Circular dependency detected: ${cyclePath}`);
     }
-    buildAndCacheAliasesMap(importModule, importedModule) {
-        const cached = this.importAliasesCache.get(importedModule);
-        if (cached) return cached;
-        const aliasesMap = new Map();
-        const moduleWithAliases = importModule;
-        const aliases = moduleWithAliases.aliases ?? [];
-        for (const alias of aliases)aliasesMap.set(alias.serviceIdentifier, alias.as);
-        this.importAliasesCache.set(importedModule, aliasesMap);
-        return aliasesMap;
+    if (visitedModules.has(module.id)) return;
+    visitStack.push(module);
+    const imports = module.imports ?? [];
+    for (const item of imports){
+        const importedModule = isModuleWithAliases(item) ? item.module : item;
+        detectCircularDependencies(importedModule, visitedModules, visitStack);
     }
-    registerDeclarations(container) {
-        const { declarations } = this.module;
-        if (!declarations?.length) return;
-        for (const declaration of declarations){
-            const { serviceIdentifier, ...rest } = declaration;
-            container.register(serviceIdentifier, rest);
-        }
+    visitedModules.add(module.id);
+    visitStack.pop();
+}
+function validateAliases(moduleName, aliases, exports1) {
+    if (!aliases || 0 === aliases.length) return;
+    const exportedSet = new Set(exports1 ?? []);
+    const mappedServices = new Set();
+    for (const alias of aliases){
+        const { serviceIdentifier } = alias;
+        if (!exportedSet.has(serviceIdentifier)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_ALIAS_SOURCE_NOT_EXPORTED, `Cannot alias service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" from module "${moduleName}": it is not exported from that module.`);
+        if (mappedServices.has(serviceIdentifier)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_ALIAS_MAP, `Duplicate alias mapping for service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" in module "${moduleName}".`);
+        mappedServices.add(serviceIdentifier);
     }
-    registerImports(container) {
-        const { imports } = this.module;
-        if (!imports?.length) return;
-        for (const importModule of imports){
-            const importedModule = getModuleByImport(importModule);
-            const aliasesMap = this.importAliasesCache.get(importedModule) ?? new Map();
-            for (const exported of importedModule.exports ?? [])container.register(aliasesMap.get(exported) ?? exported, {
-                useAlias: exported,
-                getContainer () {
-                    return importedModule.container;
-                }
-            });
-        }
+}
+function validateImportConflictsWithDeclarations(moduleName, importScope, declarations) {
+    if (!declarations) return;
+    const localDeclarations = new Set((declarations ?? []).map((decl)=>decl.serviceIdentifier));
+    const conflictingImport = importScope.bindings.find((binding)=>localDeclarations.has(binding.localServiceIdentifier));
+    if (conflictingImport) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_IMPORT_CONFLICT_LOCAL, `Imported service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(conflictingImport.localServiceIdentifier)}" conflicts with local declaration in module "${moduleName}". Use an alias to resolve the conflict.`);
+}
+function validateImportNamingConflicts(_moduleName, importScope) {
+    if (0 === importScope.bindings.length) return;
+    const serviceToModules = importScope.bindings.reduce((acc, binding)=>{
+        const modules = acc.get(binding.localServiceIdentifier) ?? [];
+        modules.push(binding.sourceModule);
+        acc.set(binding.localServiceIdentifier, modules);
+        return acc;
+    }, new Map());
+    const conflicts = Array.from(serviceToModules.entries()).filter(([, modules])=>modules.length > 1);
+    if (conflicts.length > 0) {
+        const [serviceId, modules] = conflicts[0];
+        const moduleNames = modules.map((m)=>`"${m.displayName}"`).join(", ");
+        throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_IMPORT_COLLISION, `Service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceId)}" is exported by multiple imported modules: ${moduleNames}. Consider using aliases to resolve the conflict.`);
     }
-    buildConflictMessage(conflictInfo) {
-        const { serviceName, currentModule, existing, targetModule } = conflictInfo;
-        const conflictType = "declaration" === existing.type ? "declared in" : "exported by";
-        const conflictSource = existing.source;
-        return `Service identifier conflict: "${serviceName}" is exported by "${currentModule}" and ${conflictType} "${conflictSource}" in "${targetModule}".`;
+}
+function validateExportUniqueness(moduleName, exports1) {
+    if (!exports1 || 0 === exports1.length) return;
+    const seen = new Set();
+    for (const exportId of exports1){
+        if (seen.has(exportId)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_EXPORT, `Duplicate export of service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(exportId)}" in module "${moduleName}".`);
+        seen.add(exportId);
     }
 }
+function collectAvailableServices(declarations, importScope) {
+    const localServices = (declarations ?? []).map((decl)=>decl.serviceIdentifier);
+    return new Set([
+        ...localServices,
+        ...importScope?.visibleServiceIdentifiers ?? []
+    ]);
+}
+function validateExportAvailability(moduleName, exports1, declarations, importScope) {
+    if (!exports1 || 0 === exports1.length) return;
+    const availableServices = collectAvailableServices(declarations, importScope);
+    for (const exportId of exports1)if (!availableServices.has(exportId)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_EXPORT_NOT_FOUND, `Cannot export service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(exportId)}" from "${moduleName}": it is not declared in this module or imported from any imported module.`);
+}
 const createModuleId = (0, core_namespaceObject.incrementalIdFactory)("MODULE");
-class Module {
+class ModuleImpl {
     get id() {
         return this._id;
     }
@@ -231,7 +213,7 @@ class Module {
         return this._imports;
     }
     get displayName() {
-        return `${String(this._name)}#${this._id}`;
+        return `${String(this._name)}/${this._id}`;
     }
     container;
     _id;
@@ -239,13 +221,17 @@ class Module {
     _declarations;
     _imports;
     _exports;
+    _importScope;
     constructor(options){
         this._id = createModuleId();
         this._name = options.name;
         this._declarations = options.declarations;
         this._imports = options.imports;
         this._exports = options.exports;
-        this.container = build(this);
+        this._importScope = createImportScope(this._imports);
+        this.validateConfiguration();
+        this.container = this.buildContainer();
+        this.container.use(createExportedGuardMiddleware(this.exports ?? []));
     }
     resolve(serviceIdentifier, options) {
         return this.container.resolve(serviceIdentifier, options);
@@ -256,26 +242,69 @@ class Module {
     getServiceIdentifiers() {
         return this.container.getServiceIdentifiers();
     }
-    use(middleware) {
-        this.container.use(middleware);
+    use(...middleware) {
+        return this.container.use(...middleware);
     }
-    unused(middleware) {
-        this.container.unused(middleware);
+    unused(...middleware) {
+        this.container.unused(...middleware);
     }
     withAliases(aliases) {
+        validateAliases(this.displayName, aliases, this._exports);
         return {
             module: this,
             aliases
         };
     }
+    buildContainer() {
+        const container = (0, core_namespaceObject.createContainer)(this._name);
+        this.registerDeclarations(container);
+        this.registerImports(container);
+        return container;
+    }
+    validateConfiguration() {
+        validateDeclarations(this.displayName, this._declarations);
+        this.validateImports();
+        this.validateExports();
+    }
+    validateImports() {
+        if (!this._imports || 0 === this._imports.length) return;
+        validateImportUniqueness(this.displayName, this._imports);
+        validateImportAliases(this._imports);
+        detectCircularDependencies(this);
+        validateImportConflictsWithDeclarations(this.displayName, this._importScope, this._declarations);
+        validateImportNamingConflicts(this.displayName, this._importScope);
+    }
+    registerDeclarations(container) {
+        if (!this._declarations || 0 === this._declarations.length) return;
+        for (const decl of this._declarations){
+            const { serviceIdentifier, ...options } = decl;
+            container.register(serviceIdentifier, options);
+        }
+    }
+    registerImports(container) {
+        if (0 === this._importScope.bindings.length) return;
+        for (const binding of this._importScope.bindings)container.register(binding.localServiceIdentifier, {
+            useAlias: binding.sourceServiceIdentifier,
+            getContainer: ()=>binding.sourceModule.container
+        });
+    }
+    validateExports() {
+        if (!this._exports || 0 === this._exports.length) return;
+        validateExportUniqueness(this.displayName, this._exports);
+        validateExportAvailability(this.displayName, this._exports, this._declarations, this._importScope);
+    }
 }
 function createModule(options) {
-    return new Module(options);
+    return new ModuleImpl(options);
 }
+exports.ModuleErrorCodeEnum = __webpack_exports__.ModuleErrorCodeEnum;
+exports.ModuleException = __webpack_exports__.ModuleException;
 exports.createModule = __webpack_exports__.createModule;
-for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "ModuleErrorCodeEnum",
+    "ModuleException",
     "createModule"
-].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true
 });

package/dist/index.d.ts

@@ -3,5 +3,8 @@
  * @author AEPKILL
  * @created 2025-08-12 22:53:27
  */
+export { ModuleErrorCodeEnum } from "./enums/module-error-code.enum";
+export { ModuleException } from "./exceptions/module.exception";
 export { createModule } from "./factories/module.factory";
 export type { CreateModuleOptions, IModule, } from "./interfaces/module.interface";
+export type { ModuleErrorCode } from "./types/module-error-code.type";

package/dist/index.js

@@ -1,5 +1,24 @@
-import { ResolveException, createContainer, getServiceIdentifierName, incrementalIdFactory, isResolveServiceIdentifierRecord } from "@husky-di/core";
-function createExportedGuardMiddlewareFactory(exports) {
+import { CodedException, ResolveException, createContainer, getServiceIdentifierName, incrementalIdFactory, isResolveServiceIdentifierRecord } from "@husky-di/core";
+var module_error_code_enum_ModuleErrorCodeEnum = /*#__PURE__*/ function(ModuleErrorCodeEnum) {
+    ModuleErrorCodeEnum["E_DUPLICATE_DECLARATION"] = "E_DUPLICATE_DECLARATION";
+    ModuleErrorCodeEnum["E_INVALID_REGISTRATION"] = "E_INVALID_REGISTRATION";
+    ModuleErrorCodeEnum["E_DUPLICATE_IMPORT_MODULE"] = "E_DUPLICATE_IMPORT_MODULE";
+    ModuleErrorCodeEnum["E_CIRCULAR_DEPENDENCY"] = "E_CIRCULAR_DEPENDENCY";
+    ModuleErrorCodeEnum["E_IMPORT_COLLISION"] = "E_IMPORT_COLLISION";
+    ModuleErrorCodeEnum["E_IMPORT_CONFLICT_LOCAL"] = "E_IMPORT_CONFLICT_LOCAL";
+    ModuleErrorCodeEnum["E_ALIAS_SOURCE_NOT_EXPORTED"] = "E_ALIAS_SOURCE_NOT_EXPORTED";
+    ModuleErrorCodeEnum["E_DUPLICATE_ALIAS_MAP"] = "E_DUPLICATE_ALIAS_MAP";
+    ModuleErrorCodeEnum["E_EXPORT_NOT_FOUND"] = "E_EXPORT_NOT_FOUND";
+    ModuleErrorCodeEnum["E_DUPLICATE_EXPORT"] = "E_DUPLICATE_EXPORT";
+    return ModuleErrorCodeEnum;
+}({});
+class ModuleException extends CodedException {
+    __isModuleException__ = true;
+    static isModuleException(error) {
+        return error?.__isModuleException__ === true;
+    }
+}
+function createExportedGuardMiddleware(exports) {
     const exportedSet = new Set(exports);
     return {
         name: "ExportGuard",
@@ -10,7 +29,7 @@ function createExportedGuardMiddlewareFactory(exports) {
             if (!exportedSet.has(serviceIdentifier)) {
                 if (container.isRegistered(serviceIdentifier, {
                     recursive: true
-                })) throw new ResolveException(`Service identifier "${getServiceIdentifierName(serviceIdentifier)}" is not exported from ${container.displayName}.`, resolveRecord);
+                })) throw new ResolveException(module_error_code_enum_ModuleErrorCodeEnum.E_EXPORT_NOT_FOUND, `Service identifier "${getServiceIdentifierName(serviceIdentifier)}" is not exported from ${container.displayName}.`, resolveRecord);
             }
             return next(params);
         }
@@ -23,170 +42,131 @@ function findPreviousContainer(paths) {
         lastContainer = path.value.container;
     }
 }
-function isModuleWithAliases(moduleImport) {
-    return moduleImport.module instanceof Module;
+function isModuleWithAliases(item) {
+    return "module" in item;
 }
-function getModuleByImport(moduleImport) {
-    return isModuleWithAliases(moduleImport) ? moduleImport.module : moduleImport;
+function createImportScope(imports) {
+    const bindings = (imports ?? []).flatMap((item)=>{
+        const sourceModule = isModuleWithAliases(item) ? item.module : item;
+        const aliases = isModuleWithAliases(item) ? item.aliases ?? [] : [];
+        const aliasMap = createAliasMap(aliases);
+        return (sourceModule.exports ?? []).map((sourceServiceIdentifier)=>{
+            const localServiceIdentifier = aliasMap.get(sourceServiceIdentifier) ?? sourceServiceIdentifier;
+            return {
+                sourceModule,
+                sourceServiceIdentifier,
+                localServiceIdentifier,
+                isAliased: aliasMap.has(sourceServiceIdentifier)
+            };
+        });
+    });
+    return {
+        bindings,
+        visibleServiceIdentifiers: new Set(bindings.map((binding)=>binding.localServiceIdentifier))
+    };
 }
-function build(module) {
-    const builder = new ModuleBuilder(module);
-    return builder.build();
+function createAliasMap(aliases) {
+    return new Map(aliases.map((alias)=>[
+            alias.serviceIdentifier,
+            alias.as
+        ]));
 }
-class ModuleBuilder {
-    module;
-    serviceIdentifierMap = new Map();
-    availableServiceIdentifiers = new Set();
-    importAliasesCache = new Map();
-    constructor(module){
-        this.module = module;
+function validateDeclarations(moduleName, declarations) {
+    if (!declarations || 0 === declarations.length) return;
+    const seen = new Set();
+    for (const decl of declarations){
+        const { serviceIdentifier } = decl;
+        if (seen.has(serviceIdentifier)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_DECLARATION, `Duplicate declaration of service identifier "${getServiceIdentifierName(serviceIdentifier)}" in module "${moduleName}".`);
+        seen.add(serviceIdentifier);
+        const hasValidOption = "useClass" in decl || "useFactory" in decl || "useValue" in decl || "useAlias" in decl;
+        if (!hasValidOption) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_INVALID_REGISTRATION, `Invalid registration options for service identifier "${getServiceIdentifierName(serviceIdentifier)}" in module "${moduleName}": must specify useClass, useFactory, useValue, or useAlias.`);
     }
-    build() {
-        this.validateAndCollectInfo();
-        if (this.module.container) return this.module.container;
-        const container = createContainer(this.module.name);
-        if (this.module.exports?.length) container.use(createExportedGuardMiddlewareFactory(this.module.exports));
-        this.registerDeclarations(container);
-        this.registerImports(container);
-        return container;
-    }
-    validateAndCollectInfo() {
-        this.validateImportUniqueness();
-        this.validateExportUniqueness();
-        this.validateCircularDependencies();
-        this.collectServiceInfoAndValidateConflicts();
-        this.validateExportValidity();
-    }
-    validateImportUniqueness() {
-        const { imports } = this.module;
-        if (!imports?.length) return;
-        const importModules = new Set();
-        for (const importModule of imports)try {
-            const importedModule = getModuleByImport(importModule);
-            if (importModules.has(importedModule)) throw new Error(`Duplicate import module: "${importedModule.displayName}" in "${this.module.displayName}".`);
-            importModules.add(importedModule);
-        } catch (error) {
-            throw new Error(`Invalid module import in "${this.module.displayName}": ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
-    }
-    validateExportUniqueness() {
-        const { exports } = this.module;
-        if (!exports?.length) return;
-        const existingExportServiceIdentifiers = new Set();
-        for (const exported of exports){
-            if (existingExportServiceIdentifiers.has(exported)) throw new Error(`Duplicate export service identifier: "${getServiceIdentifierName(exported)}" in "${this.module.displayName}".`);
-            existingExportServiceIdentifiers.add(exported);
-        }
+}
+function validateImportUniqueness(moduleName, imports) {
+    const seenModules = new Set();
+    for (const item of imports){
+        const importedModule = isModuleWithAliases(item) ? item.module : item;
+        const moduleId = importedModule.id;
+        if (seenModules.has(moduleId)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_IMPORT_MODULE, `Duplicate import module: "${importedModule.displayName}" in "${moduleName}".`);
+        seenModules.add(moduleId);
     }
-    validateCircularDependencies() {
-        const visited = new Set();
-        const visiting = new Set();
-        const dependencyPath = [];
-        this.detectCircularDependency(this.module, visited, visiting, dependencyPath);
-    }
-    detectCircularDependency(currentModule, visited, visiting, dependencyPath) {
-        if (visited.has(currentModule)) return;
-        if (visiting.has(currentModule)) {
-            const cycleStartIndex = dependencyPath.findIndex((module)=>module === currentModule);
-            const cyclePath = dependencyPath.slice(cycleStartIndex).concat(currentModule).map((module)=>module.displayName).join(" -> ");
-            throw new Error(`Circular dependency detected: ${cyclePath}. Modules cannot have circular import relationships.`);
-        }
-        visiting.add(currentModule);
-        dependencyPath.push(currentModule);
-        const imports = currentModule.imports ?? [];
-        for (const importModule of imports)try {
-            const importedModule = getModuleByImport(importModule);
-            this.detectCircularDependency(importedModule, visited, visiting, dependencyPath);
-        } catch (error) {
-            if (error instanceof Error && error.message.includes("Circular dependency detected")) throw error;
-            throw new Error(`Failed to validate circular dependencies for "${currentModule.displayName}": ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
-        visiting.delete(currentModule);
-        dependencyPath.pop();
-        visited.add(currentModule);
-    }
-    collectServiceInfoAndValidateConflicts() {
-        const { imports, declarations } = this.module;
-        if (declarations?.length) for (const declaration of declarations){
-            this.serviceIdentifierMap.set(declaration.serviceIdentifier, {
-                type: "declaration",
-                source: "declarations"
-            });
-            this.availableServiceIdentifiers.add(declaration.serviceIdentifier);
-        }
-        if (imports?.length) for (const importModule of imports)try {
-            const importedModule = getModuleByImport(importModule);
-            const exportedServices = importedModule.exports ?? [];
-            const aliasesMap = this.buildAndCacheAliasesMap(importModule, importedModule);
-            for (const exported of exportedServices){
-                const existing = this.serviceIdentifierMap.get(exported);
-                if (existing) {
-                    const conflictInfo = {
-                        serviceName: getServiceIdentifierName(exported),
-                        currentModule: importedModule.displayName,
-                        existing,
-                        targetModule: this.module.displayName
-                    };
-                    throw new Error(this.buildConflictMessage(conflictInfo));
-                }
-                this.serviceIdentifierMap.set(exported, {
-                    type: "import",
-                    source: importedModule.displayName
-                });
-                this.availableServiceIdentifiers.add(exported);
-                const alias = aliasesMap.get(exported);
-                if (alias) this.availableServiceIdentifiers.add(alias);
-            }
-        } catch (error) {
-            throw new Error(`Failed to validate imports in "${this.module.displayName}": ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
+}
+function validateImportAliases(imports) {
+    for (const item of imports)if (isModuleWithAliases(item)) validateAliases(item.module.displayName, item.aliases ?? [], item.module.exports);
+}
+function detectCircularDependencies(module, visitedModules = new Set(), visitStack = []) {
+    if (visitStack.includes(module)) {
+        const cycle = [
+            ...visitStack.slice(visitStack.indexOf(module)),
+            module
+        ];
+        const cyclePath = cycle.map((m)=>m.displayName).join(" → ");
+        throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_CIRCULAR_DEPENDENCY, `Circular dependency detected: ${cyclePath}`);
     }
-    validateExportValidity() {
-        const { exports } = this.module;
-        if (!exports?.length) return;
-        for (const exported of exports)if (!this.availableServiceIdentifiers.has(exported)) throw new Error(`Cannot export service identifier "${getServiceIdentifierName(exported)}" from "${this.module.displayName}": it is not declared in this module or imported from any imported module.`);
-    }
-    buildAndCacheAliasesMap(importModule, importedModule) {
-        const cached = this.importAliasesCache.get(importedModule);
-        if (cached) return cached;
-        const aliasesMap = new Map();
-        const moduleWithAliases = importModule;
-        const aliases = moduleWithAliases.aliases ?? [];
-        for (const alias of aliases)aliasesMap.set(alias.serviceIdentifier, alias.as);
-        this.importAliasesCache.set(importedModule, aliasesMap);
-        return aliasesMap;
+    if (visitedModules.has(module.id)) return;
+    visitStack.push(module);
+    const imports = module.imports ?? [];
+    for (const item of imports){
+        const importedModule = isModuleWithAliases(item) ? item.module : item;
+        detectCircularDependencies(importedModule, visitedModules, visitStack);
     }
-    registerDeclarations(container) {
-        const { declarations } = this.module;
-        if (!declarations?.length) return;
-        for (const declaration of declarations){
-            const { serviceIdentifier, ...rest } = declaration;
-            container.register(serviceIdentifier, rest);
-        }
+    visitedModules.add(module.id);
+    visitStack.pop();
+}
+function validateAliases(moduleName, aliases, exports) {
+    if (!aliases || 0 === aliases.length) return;
+    const exportedSet = new Set(exports ?? []);
+    const mappedServices = new Set();
+    for (const alias of aliases){
+        const { serviceIdentifier } = alias;
+        if (!exportedSet.has(serviceIdentifier)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_ALIAS_SOURCE_NOT_EXPORTED, `Cannot alias service identifier "${getServiceIdentifierName(serviceIdentifier)}" from module "${moduleName}": it is not exported from that module.`);
+        if (mappedServices.has(serviceIdentifier)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_ALIAS_MAP, `Duplicate alias mapping for service identifier "${getServiceIdentifierName(serviceIdentifier)}" in module "${moduleName}".`);
+        mappedServices.add(serviceIdentifier);
     }
-    registerImports(container) {
-        const { imports } = this.module;
-        if (!imports?.length) return;
-        for (const importModule of imports){
-            const importedModule = getModuleByImport(importModule);
-            const aliasesMap = this.importAliasesCache.get(importedModule) ?? new Map();
-            for (const exported of importedModule.exports ?? [])container.register(aliasesMap.get(exported) ?? exported, {
-                useAlias: exported,
-                getContainer () {
-                    return importedModule.container;
-                }
-            });
-        }
+}
+function validateImportConflictsWithDeclarations(moduleName, importScope, declarations) {
+    if (!declarations) return;
+    const localDeclarations = new Set((declarations ?? []).map((decl)=>decl.serviceIdentifier));
+    const conflictingImport = importScope.bindings.find((binding)=>localDeclarations.has(binding.localServiceIdentifier));
+    if (conflictingImport) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_IMPORT_CONFLICT_LOCAL, `Imported service identifier "${getServiceIdentifierName(conflictingImport.localServiceIdentifier)}" conflicts with local declaration in module "${moduleName}". Use an alias to resolve the conflict.`);
+}
+function validateImportNamingConflicts(_moduleName, importScope) {
+    if (0 === importScope.bindings.length) return;
+    const serviceToModules = importScope.bindings.reduce((acc, binding)=>{
+        const modules = acc.get(binding.localServiceIdentifier) ?? [];
+        modules.push(binding.sourceModule);
+        acc.set(binding.localServiceIdentifier, modules);
+        return acc;
+    }, new Map());
+    const conflicts = Array.from(serviceToModules.entries()).filter(([, modules])=>modules.length > 1);
+    if (conflicts.length > 0) {
+        const [serviceId, modules] = conflicts[0];
+        const moduleNames = modules.map((m)=>`"${m.displayName}"`).join(", ");
+        throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_IMPORT_COLLISION, `Service identifier "${getServiceIdentifierName(serviceId)}" is exported by multiple imported modules: ${moduleNames}. Consider using aliases to resolve the conflict.`);
     }
-    buildConflictMessage(conflictInfo) {
-        const { serviceName, currentModule, existing, targetModule } = conflictInfo;
-        const conflictType = "declaration" === existing.type ? "declared in" : "exported by";
-        const conflictSource = existing.source;
-        return `Service identifier conflict: "${serviceName}" is exported by "${currentModule}" and ${conflictType} "${conflictSource}" in "${targetModule}".`;
+}
+function validateExportUniqueness(moduleName, exports) {
+    if (!exports || 0 === exports.length) return;
+    const seen = new Set();
+    for (const exportId of exports){
+        if (seen.has(exportId)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_DUPLICATE_EXPORT, `Duplicate export of service identifier "${getServiceIdentifierName(exportId)}" in module "${moduleName}".`);
+        seen.add(exportId);
     }
 }
+function collectAvailableServices(declarations, importScope) {
+    const localServices = (declarations ?? []).map((decl)=>decl.serviceIdentifier);
+    return new Set([
+        ...localServices,
+        ...importScope?.visibleServiceIdentifiers ?? []
+    ]);
+}
+function validateExportAvailability(moduleName, exports, declarations, importScope) {
+    if (!exports || 0 === exports.length) return;
+    const availableServices = collectAvailableServices(declarations, importScope);
+    for (const exportId of exports)if (!availableServices.has(exportId)) throw new ModuleException(module_error_code_enum_ModuleErrorCodeEnum.E_EXPORT_NOT_FOUND, `Cannot export service identifier "${getServiceIdentifierName(exportId)}" from "${moduleName}": it is not declared in this module or imported from any imported module.`);
+}
 const createModuleId = incrementalIdFactory("MODULE");
-class Module {
+class ModuleImpl {
     get id() {
         return this._id;
     }
@@ -203,7 +183,7 @@ class Module {
         return this._imports;
     }
     get displayName() {
-        return `${String(this._name)}#${this._id}`;
+        return `${String(this._name)}/${this._id}`;
     }
     container;
     _id;
@@ -211,13 +191,17 @@ class Module {
     _declarations;
     _imports;
     _exports;
+    _importScope;
     constructor(options){
         this._id = createModuleId();
         this._name = options.name;
         this._declarations = options.declarations;
         this._imports = options.imports;
         this._exports = options.exports;
-        this.container = build(this);
+        this._importScope = createImportScope(this._imports);
+        this.validateConfiguration();
+        this.container = this.buildContainer();
+        this.container.use(createExportedGuardMiddleware(this.exports ?? []));
     }
     resolve(serviceIdentifier, options) {
         return this.container.resolve(serviceIdentifier, options);
@@ -228,20 +212,59 @@ class Module {
     getServiceIdentifiers() {
         return this.container.getServiceIdentifiers();
     }
-    use(middleware) {
-        this.container.use(middleware);
+    use(...middleware) {
+        return this.container.use(...middleware);
     }
-    unused(middleware) {
-        this.container.unused(middleware);
+    unused(...middleware) {
+        this.container.unused(...middleware);
     }
     withAliases(aliases) {
+        validateAliases(this.displayName, aliases, this._exports);
         return {
             module: this,
             aliases
         };
     }
+    buildContainer() {
+        const container = createContainer(this._name);
+        this.registerDeclarations(container);
+        this.registerImports(container);
+        return container;
+    }
+    validateConfiguration() {
+        validateDeclarations(this.displayName, this._declarations);
+        this.validateImports();
+        this.validateExports();
+    }
+    validateImports() {
+        if (!this._imports || 0 === this._imports.length) return;
+        validateImportUniqueness(this.displayName, this._imports);
+        validateImportAliases(this._imports);
+        detectCircularDependencies(this);
+        validateImportConflictsWithDeclarations(this.displayName, this._importScope, this._declarations);
+        validateImportNamingConflicts(this.displayName, this._importScope);
+    }
+    registerDeclarations(container) {
+        if (!this._declarations || 0 === this._declarations.length) return;
+        for (const decl of this._declarations){
+            const { serviceIdentifier, ...options } = decl;
+            container.register(serviceIdentifier, options);
+        }
+    }
+    registerImports(container) {
+        if (0 === this._importScope.bindings.length) return;
+        for (const binding of this._importScope.bindings)container.register(binding.localServiceIdentifier, {
+            useAlias: binding.sourceServiceIdentifier,
+            getContainer: ()=>binding.sourceModule.container
+        });
+    }
+    validateExports() {
+        if (!this._exports || 0 === this._exports.length) return;
+        validateExportUniqueness(this.displayName, this._exports);
+        validateExportAvailability(this.displayName, this._exports, this._declarations, this._importScope);
+    }
 }
 function createModule(options) {
-    return new Module(options);
+    return new ModuleImpl(options);
 }
-export { createModule };
+export { ModuleException, createModule, module_error_code_enum_ModuleErrorCodeEnum as ModuleErrorCodeEnum };

package/dist/interfaces/module.interface.d.ts

@@ -5,11 +5,11 @@
  */
 import type { CreateRegistrationOptions, IContainer, IDisplayName, IUnique, ServiceIdentifier } from "@husky-di/core";
 export type Declaration<T> = CreateRegistrationOptions<T> & {
-    serviceIdentifier: ServiceIdentifier<T> | string;
+    readonly serviceIdentifier: ServiceIdentifier<T>;
 };
 export type Alias = {
-    serviceIdentifier: ServiceIdentifier<unknown>;
-    as: ServiceIdentifier<unknown>;
+    readonly serviceIdentifier: ServiceIdentifier<unknown>;
+    readonly as: ServiceIdentifier<unknown>;
 };
 export type CreateModuleOptions = {
     readonly name: string;
@@ -18,14 +18,14 @@ export type CreateModuleOptions = {
     readonly exports?: ServiceIdentifier<unknown>[];
 };
 export type ModuleWithAliases = {
-    module: IModule;
-    aliases?: Alias[];
+    readonly module: IModule;
+    readonly aliases?: Alias[];
 };
 export interface IModule extends IUnique, IDisplayName, Pick<IContainer, "resolve" | "isRegistered" | "getServiceIdentifiers" | "use" | "unused"> {
     readonly name: string;
-    readonly declarations?: Declaration<unknown>[];
-    readonly imports?: Array<IModule | ModuleWithAliases>;
-    readonly exports?: ServiceIdentifier<unknown>[];
+    readonly declarations?: ReadonlyArray<Declaration<unknown>>;
+    readonly imports?: ReadonlyArray<IModule | ModuleWithAliases>;
+    readonly exports?: ReadonlyArray<ServiceIdentifier<unknown>>;
     readonly container: IContainer;
     withAliases(aliases: Alias[]): ModuleWithAliases;
 }

package/dist/types/import-scope.type.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Import scope type definitions.
+ *
+ * @overview
+ * Defines the normalized import visibility model used by module validation and
+ * container assembly.
+ *
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+import type { ServiceIdentifier } from "@husky-di/core";
+import type { IModule } from "../interfaces/module.interface";
+export type ImportBinding = {
+    readonly sourceModule: IModule;
+    readonly sourceServiceIdentifier: ServiceIdentifier<unknown>;
+    readonly localServiceIdentifier: ServiceIdentifier<unknown>;
+    readonly isAliased: boolean;
+};
+export type ImportScope = {
+    readonly bindings: ReadonlyArray<ImportBinding>;
+    readonly visibleServiceIdentifiers: ReadonlySet<ServiceIdentifier<unknown>>;
+};

package/dist/types/module-error-code.type.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @overview Module error code type.
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+import type { ModuleErrorCodeEnum } from "../enums/module-error-code.enum";
+export type ModuleErrorCode = ModuleErrorCodeEnum;

package/dist/utils/module-import.utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Module import utilities.
+ *
+ * @overview
+ * Provides helpers for working with module import descriptors.
+ *
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+import type { IModule, ModuleWithAliases } from "../interfaces/module.interface";
+export declare function isModuleWithAliases(item: IModule | ModuleWithAliases): item is ModuleWithAliases;

package/dist/utils/module-validator.utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @overview Module validation utilities.
+ * @author AEPKILL
+ * @created 2025-03-30
+ */
+import { type ServiceIdentifier } from "@husky-di/core";
+import type { Alias, Declaration, IModule, ModuleWithAliases } from "../interfaces/module.interface";
+import type { ImportScope } from "../types/import-scope.type";
+export declare function validateDeclarations(moduleName: string, declarations?: Declaration<unknown>[]): void;
+export declare function validateImportUniqueness(moduleName: string, imports: ReadonlyArray<IModule | ModuleWithAliases>): void;
+export declare function validateImportAliases(imports: ReadonlyArray<IModule | ModuleWithAliases>): void;
+export declare function detectCircularDependencies(module: IModule, visitedModules?: Set<string | symbol>, visitStack?: IModule[]): void;
+export declare function validateAliases(moduleName: string, aliases: ReadonlyArray<Alias>, exports?: ReadonlyArray<ServiceIdentifier<unknown>>): void;
+export declare function validateImportConflictsWithDeclarations(moduleName: string, importScope: ImportScope, declarations?: Declaration<unknown>[]): void;
+export declare function validateImportNamingConflicts(_moduleName: string, importScope: ImportScope): void;
+export declare function validateExportUniqueness(moduleName: string, exports?: ServiceIdentifier<unknown>[]): void;
+export declare function collectAvailableServices(declarations?: Declaration<unknown>[], importScope?: ImportScope): Set<ServiceIdentifier<unknown>>;
+export declare function validateExportAvailability(moduleName: string, exports?: ServiceIdentifier<unknown>[], declarations?: Declaration<unknown>[], importScope?: ImportScope): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@husky-di/module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -15,13 +15,16 @@
     "dist"
   ],
   "dependencies": {
-    "@husky-di/core": "1.0.0"
+    "@husky-di/core": "1.1.0"
   },
   "devDependencies": {
-    "@rslib/core": "^0.11.2",
-    "@types/node": "^22.17.0",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "@rslib/core": "^0.20.1",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "build": "rslib build",

package/dist/utils/module.utils.d.ts

@@ -1,126 +0,0 @@
-/**
- * @overview 模块工具函数，包含模块构建和验证逻辑
- * @author AEPKILL
- * @created 2025-08-12 19:57:50
- */
-import { type IContainer } from "@husky-di/core";
-import type { CreateModuleOptions, IModule, ModuleWithAliases } from "../interfaces/module.interface";
-/**
- * 类型守卫：检查模块导入是否包含别名映射
- *
- * @param moduleImport 模块导入对象
- * @returns 如果包含别名映射则返回 true，否则返回 false
- */
-export declare function isModuleWithAliases(moduleImport: NonNullable<CreateModuleOptions["imports"]>[number]): moduleImport is ModuleWithAliases;
-/**
- * 从模块导入中获取实际的模块对象
- *
- * @param moduleImport 模块导入（可能包含别名）
- * @returns 实际的模块对象
- */
-export declare function getModuleByImport(moduleImport: NonNullable<CreateModuleOptions["imports"]>[number]): IModule;
-/**
- * 构建模块容器的公共函数
- *
- * @param module 要构建的模块
- * @returns 构建好的容器
- */
-export declare function build(module: IModule): IContainer;
-/**
- * 模块构建器类，整合模块验证和构建逻辑
- *
- * 在验证过程中收集服务标识符信息，并在构建过程中复用这些信息
- */
-export declare class ModuleBuilder {
-    /** 要构建的模块 */
-    private readonly module;
-    /** 服务标识符映射表（验证时构建，构建时复用） */
-    private readonly serviceIdentifierMap;
-    /** 可用服务标识符集合（验证时构建，构建时复用） */
-    private readonly availableServiceIdentifiers;
-    /** 导入模块的别名映射缓存 */
-    private readonly importAliasesCache;
-    constructor(module: IModule);
-    /**
-     * 构建模块容器
-     *
-     * @returns 构建好的容器
-     * @throws {Error} 当模块配置无效时抛出错误
-     */
-    build(): IContainer;
-    /**
-     * 验证模块并收集信息
-     *
-     * @throws {Error} 当模块配置无效时抛出错误
-     */
-    validateAndCollectInfo(): void;
-    /**
-     * 验证导入模块的唯一性
-     *
-     * @throws {Error} 当存在重复导入时抛出错误
-     */
-    private validateImportUniqueness;
-    /**
-     * 验证导出服务标识符的唯一性
-     *
-     * @throws {Error} 当存在重复导出时抛出错误
-     */
-    private validateExportUniqueness;
-    /**
-     * 验证循环依赖
-     *
-     * 使用深度优先搜索（DFS）算法检测模块之间的循环依赖
-     *
-     * @throws {Error} 当检测到循环依赖时抛出错误
-     */
-    private validateCircularDependencies;
-    /**
-     * 递归检测循环依赖的核心方法
-     *
-     * @param currentModule 当前检查的模块
-     * @param visited 已完全访问过的模块集合（白色节点）
-     * @param visiting 正在访问中的模块集合（灰色节点）
-     * @param dependencyPath 当前依赖路径，用于构建错误信息
-     * @throws {Error} 当检测到循环依赖时抛出错误
-     */
-    private detectCircularDependency;
-    /**
-     * 收集服务标识符信息并验证冲突
-     *
-     * @throws {Error} 当存在服务标识符冲突时抛出错误
-     */
-    private collectServiceInfoAndValidateConflicts;
-    /**
-     * 验证导出服务标识符的有效性
-     *
-     * @throws {Error} 当导出的服务标识符不可用时抛出错误
-     */
-    private validateExportValidity;
-    /**
-     * 构建并缓存别名映射
-     *
-     * @param importModule 导入模块配置
-     * @param importedModule 实际导入的模块
-     * @returns 别名映射
-     */
-    private buildAndCacheAliasesMap;
-    /**
-     * 注册声明的服务
-     *
-     * @param container 目标容器
-     */
-    private registerDeclarations;
-    /**
-     * 注册导入的服务
-     *
-     * @param container 目标容器
-     */
-    private registerImports;
-    /**
-     * 构建服务标识符冲突的详细错误消息
-     *
-     * @param conflictInfo 包含冲突详细信息的对象
-     * @returns 格式化的错误消息字符串
-     */
-    private buildConflictMessage;
-}