@husky-di/module 1.0.1 → 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

@@ -30,5 +30,9 @@ import { type ResolveMiddleware, type ServiceIdentifier } from "@husky-di/core";
  *
  * 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 createExportedGuardMiddlewareFactory(exports: ReadonlyArray<ServiceIdentifier<unknown>>): ResolveMiddleware<any, any>;
+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/ModuleImpl.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @overview Module implementation.
+ * @author AEPKILL
+ * @created 2025-08-09 14:51:09
+ */
+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 ModuleImpl implements IModule {
+    get id(): string;
+    get name(): string;
+    get declarations(): Declaration<unknown>[] | undefined;
+    get exports(): ServiceIdentifier<unknown>[] | undefined;
+    get imports(): (IModule | ModuleWithAliases)[] | undefined;
+    get displayName(): string;
+    readonly container: IContainer;
+    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>[]): 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,8 +72,131 @@ function findPreviousContainer(paths) {
         lastContainer = path.value.container;
     }
 }
+function isModuleWithAliases(item) {
+    return "module" in item;
+}
+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 createAliasMap(aliases) {
+    return new Map(aliases.map((alias)=>[
+            alias.serviceIdentifier,
+            alias.as
+        ]));
+}
+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.`);
+    }
+}
+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);
+    }
+}
+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}`);
+    }
+    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);
+    }
+    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);
+    }
+}
+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.`);
+    }
+}
+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;
     }
@@ -69,7 +213,7 @@ class Module {
         return this._imports;
     }
     get displayName() {
-        return `${String(this._name)}#${this._id}`;
+        return `${String(this._name)}/${this._id}`;
     }
     container;
     _id;
@@ -77,19 +221,17 @@ class Module {
     _declarations;
     _imports;
     _exports;
-    _visitedModules = new Set();
-    _visitStack = [];
+    _importScope;
     constructor(options){
         this._id = createModuleId();
         this._name = options.name;
         this._declarations = options.declarations;
         this._imports = options.imports;
         this._exports = options.exports;
-        this.validateDeclarations();
-        this.validateImports();
-        this.validateExports();
+        this._importScope = createImportScope(this._imports);
+        this.validateConfiguration();
         this.container = this.buildContainer();
-        this.container.use(createExportedGuardMiddlewareFactory(this.exports ?? []));
+        this.container.use(createExportedGuardMiddleware(this.exports ?? []));
     }
     resolve(serviceIdentifier, options) {
         return this.container.resolve(serviceIdentifier, options);
@@ -100,14 +242,14 @@ 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) {
-        this.validateAliases(aliases);
+        validateAliases(this.displayName, aliases, this._exports);
         return {
             module: this,
             aliases
@@ -119,45 +261,18 @@ class Module {
         this.registerImports(container);
         return container;
     }
+    validateConfiguration() {
+        validateDeclarations(this.displayName, this._declarations);
+        this.validateImports();
+        this.validateExports();
+    }
     validateImports() {
         if (!this._imports || 0 === this._imports.length) return;
-        this.validateImportUniqueness(this._imports);
-        this.detectCircularDependencies();
-        this.validateAliasConflictsWithDeclarations();
-        this.validateImportNamingConflicts();
-    }
-    validateImportUniqueness(imports) {
-        const seenModules = new Set();
-        for (const item of imports){
-            const importedModule = this.isModuleWithAliases(item) ? item.module : item;
-            const moduleId = importedModule.id;
-            if (seenModules.has(moduleId)) throw new Error(`Duplicate import module: "${importedModule.displayName}" in "${this.displayName}".`);
-            seenModules.add(moduleId);
-        }
-    }
-    detectCircularDependencies() {
-        this._visitedModules.clear();
-        this._visitStack.length = 0;
-        this.visitModule(this);
-    }
-    visitModule(module) {
-        if (this._visitStack.includes(module)) {
-            const cycle = [
-                ...this._visitStack.slice(this._visitStack.indexOf(module)),
-                module
-            ];
-            const cyclePath = cycle.map((m)=>m.displayName).join(" \u2192 ");
-            throw new Error(`Circular dependency detected: ${cyclePath}`);
-        }
-        if (this._visitedModules.has(module.id)) return;
-        this._visitStack.push(module);
-        const imports = module.imports ?? [];
-        for (const item of imports){
-            const importedModule = this.isModuleWithAliases(item) ? item.module : item;
-            this.visitModule(importedModule);
-        }
-        this._visitedModules.add(module.id);
-        this._visitStack.pop();
+        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;
@@ -167,118 +282,29 @@ class Module {
         }
     }
     registerImports(container) {
-        if (!this._imports || 0 === this._imports.length) return;
-        const normalizedImports = this.normalizeImports(this._imports);
-        for (const { module: sourceModule, serviceIdentifier, as } of normalizedImports)if (serviceIdentifier !== as) container.register(as, {
-            useAlias: serviceIdentifier,
-            getContainer: ()=>sourceModule.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
         });
-        else container.register(serviceIdentifier, {
-            useAlias: serviceIdentifier,
-            getContainer: ()=>sourceModule.container
-        });
-    }
-    normalizeImports(imports) {
-        return imports.flatMap((item)=>{
-            const module = this.isModuleWithAliases(item) ? item.module : item;
-            const aliases = this.isModuleWithAliases(item) ? item.aliases : void 0;
-            const aliasMap = this.buildAliasMap(aliases);
-            return (module.exports ?? []).map((serviceIdentifier)=>({
-                    module,
-                    serviceIdentifier,
-                    as: aliasMap.get(serviceIdentifier) ?? serviceIdentifier
-                }));
-        });
-    }
-    buildAliasMap(aliases) {
-        return new Map((aliases ?? []).map((alias)=>[
-                alias.serviceIdentifier,
-                alias.as
-            ]));
-    }
-    validateDeclarations() {
-        if (!this._declarations || 0 === this._declarations.length) return;
-        const seen = new Set();
-        for (const decl of this._declarations){
-            const { serviceIdentifier } = decl;
-            if (seen.has(serviceIdentifier)) throw new Error(`Duplicate declaration of service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" in module "${this.displayName}".`);
-            seen.add(serviceIdentifier);
-            const hasValidOption = "useClass" in decl || "useFactory" in decl || "useValue" in decl || "useAlias" in decl;
-            if (!hasValidOption) throw new Error(`Invalid registration options for service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" in module "${this.displayName}": must specify useClass, useFactory, useValue, or useAlias.`);
-        }
     }
     validateExports() {
         if (!this._exports || 0 === this._exports.length) return;
-        const seen = new Set();
-        for (const exportId of this._exports){
-            if (seen.has(exportId)) throw new Error(`Duplicate export of service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(exportId)}" in module "${this.displayName}".`);
-            seen.add(exportId);
-        }
-        const availableServices = this.collectAvailableServices();
-        for (const exportId of this._exports)if (!availableServices.has(exportId)) throw new Error(`Cannot export service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(exportId)}" from "${this.displayName}": it is not declared in this module or imported from any imported module.`);
-    }
-    collectAvailableServices() {
-        const localServices = (this._declarations ?? []).map((decl)=>decl.serviceIdentifier);
-        const importedServices = (this._imports ?? []).flatMap((item)=>{
-            const module = this.isModuleWithAliases(item) ? item.module : item;
-            const aliases = this.isModuleWithAliases(item) ? item.aliases : void 0;
-            const aliasMap = this.buildAliasMap(aliases);
-            return (module.exports ?? []).map((serviceId)=>aliasMap.get(serviceId) ?? serviceId);
-        });
-        return new Set([
-            ...localServices,
-            ...importedServices
-        ]);
-    }
-    validateAliases(aliases) {
-        if (!aliases || 0 === aliases.length) return;
-        const exportedSet = new Set(this._exports ?? []);
-        const mappedServices = new Set();
-        for (const alias of aliases){
-            const { serviceIdentifier } = alias;
-            if (!exportedSet.has(serviceIdentifier)) throw new Error(`Cannot alias service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" from module "${this.displayName}": it is not exported from that module.`);
-            if (mappedServices.has(serviceIdentifier)) throw new Error(`Duplicate alias mapping for service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceIdentifier)}" in module "${this.displayName}".`);
-            mappedServices.add(serviceIdentifier);
-        }
-    }
-    validateAliasConflictsWithDeclarations() {
-        if (!this._imports || !this._declarations) return;
-        const localDeclarations = new Set((this._declarations ?? []).map((decl)=>decl.serviceIdentifier));
-        const conflictingAlias = (this._imports ?? []).filter((item)=>this.isModuleWithAliases(item)).flatMap((item)=>item.aliases ?? []).find((alias)=>localDeclarations.has(alias.as));
-        if (conflictingAlias) throw new Error(`Alias "${(0, core_namespaceObject.getServiceIdentifierName)(conflictingAlias.as)}" conflicts with local declaration in module "${this.displayName}".`);
-    }
-    validateImportNamingConflicts() {
-        if (!this._imports || 0 === this._imports.length) return;
-        const serviceToModules = (this._imports ?? []).reduce((acc, item)=>{
-            const module = this.isModuleWithAliases(item) ? item.module : item;
-            const aliases = this.isModuleWithAliases(item) ? item.aliases : void 0;
-            const aliasMap = this.buildAliasMap(aliases);
-            for (const serviceId of module.exports ?? []){
-                const effectiveName = aliasMap.get(serviceId) ?? serviceId;
-                const modules = acc.get(effectiveName) ?? [];
-                modules.push(module);
-                acc.set(effectiveName, 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 Error(`Service identifier "${(0, core_namespaceObject.getServiceIdentifierName)(serviceId)}" is exported by multiple imported modules: ${moduleNames}. Consider using aliases to resolve the conflict.`);
-        }
-    }
-    isModuleWithAliases(item) {
-        return "module" in item;
+        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,8 +42,131 @@ function findPreviousContainer(paths) {
         lastContainer = path.value.container;
     }
 }
+function isModuleWithAliases(item) {
+    return "module" in item;
+}
+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 createAliasMap(aliases) {
+    return new Map(aliases.map((alias)=>[
+            alias.serviceIdentifier,
+            alias.as
+        ]));
+}
+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.`);
+    }
+}
+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);
+    }
+}
+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}`);
+    }
+    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);
+    }
+    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);
+    }
+}
+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.`);
+    }
+}
+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;
     }
@@ -41,7 +183,7 @@ class Module {
         return this._imports;
     }
     get displayName() {
-        return `${String(this._name)}#${this._id}`;
+        return `${String(this._name)}/${this._id}`;
     }
     container;
     _id;
@@ -49,19 +191,17 @@ class Module {
     _declarations;
     _imports;
     _exports;
-    _visitedModules = new Set();
-    _visitStack = [];
+    _importScope;
     constructor(options){
         this._id = createModuleId();
         this._name = options.name;
         this._declarations = options.declarations;
         this._imports = options.imports;
         this._exports = options.exports;
-        this.validateDeclarations();
-        this.validateImports();
-        this.validateExports();
+        this._importScope = createImportScope(this._imports);
+        this.validateConfiguration();
         this.container = this.buildContainer();
-        this.container.use(createExportedGuardMiddlewareFactory(this.exports ?? []));
+        this.container.use(createExportedGuardMiddleware(this.exports ?? []));
     }
     resolve(serviceIdentifier, options) {
         return this.container.resolve(serviceIdentifier, options);
@@ -72,14 +212,14 @@ 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) {
-        this.validateAliases(aliases);
+        validateAliases(this.displayName, aliases, this._exports);
         return {
             module: this,
             aliases
@@ -91,45 +231,18 @@ class Module {
         this.registerImports(container);
         return container;
     }
+    validateConfiguration() {
+        validateDeclarations(this.displayName, this._declarations);
+        this.validateImports();
+        this.validateExports();
+    }
     validateImports() {
         if (!this._imports || 0 === this._imports.length) return;
-        this.validateImportUniqueness(this._imports);
-        this.detectCircularDependencies();
-        this.validateAliasConflictsWithDeclarations();
-        this.validateImportNamingConflicts();
-    }
-    validateImportUniqueness(imports) {
-        const seenModules = new Set();
-        for (const item of imports){
-            const importedModule = this.isModuleWithAliases(item) ? item.module : item;
-            const moduleId = importedModule.id;
-            if (seenModules.has(moduleId)) throw new Error(`Duplicate import module: "${importedModule.displayName}" in "${this.displayName}".`);
-            seenModules.add(moduleId);
-        }
-    }
-    detectCircularDependencies() {
-        this._visitedModules.clear();
-        this._visitStack.length = 0;
-        this.visitModule(this);
-    }
-    visitModule(module) {
-        if (this._visitStack.includes(module)) {
-            const cycle = [
-                ...this._visitStack.slice(this._visitStack.indexOf(module)),
-                module
-            ];
-            const cyclePath = cycle.map((m)=>m.displayName).join(" \u2192 ");
-            throw new Error(`Circular dependency detected: ${cyclePath}`);
-        }
-        if (this._visitedModules.has(module.id)) return;
-        this._visitStack.push(module);
-        const imports = module.imports ?? [];
-        for (const item of imports){
-            const importedModule = this.isModuleWithAliases(item) ? item.module : item;
-            this.visitModule(importedModule);
-        }
-        this._visitedModules.add(module.id);
-        this._visitStack.pop();
+        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;
@@ -139,112 +252,19 @@ class Module {
         }
     }
     registerImports(container) {
-        if (!this._imports || 0 === this._imports.length) return;
-        const normalizedImports = this.normalizeImports(this._imports);
-        for (const { module: sourceModule, serviceIdentifier, as } of normalizedImports)if (serviceIdentifier !== as) container.register(as, {
-            useAlias: serviceIdentifier,
-            getContainer: ()=>sourceModule.container
-        });
-        else container.register(serviceIdentifier, {
-            useAlias: serviceIdentifier,
-            getContainer: ()=>sourceModule.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
         });
     }
-    normalizeImports(imports) {
-        return imports.flatMap((item)=>{
-            const module = this.isModuleWithAliases(item) ? item.module : item;
-            const aliases = this.isModuleWithAliases(item) ? item.aliases : void 0;
-            const aliasMap = this.buildAliasMap(aliases);
-            return (module.exports ?? []).map((serviceIdentifier)=>({
-                    module,
-                    serviceIdentifier,
-                    as: aliasMap.get(serviceIdentifier) ?? serviceIdentifier
-                }));
-        });
-    }
-    buildAliasMap(aliases) {
-        return new Map((aliases ?? []).map((alias)=>[
-                alias.serviceIdentifier,
-                alias.as
-            ]));
-    }
-    validateDeclarations() {
-        if (!this._declarations || 0 === this._declarations.length) return;
-        const seen = new Set();
-        for (const decl of this._declarations){
-            const { serviceIdentifier } = decl;
-            if (seen.has(serviceIdentifier)) throw new Error(`Duplicate declaration of service identifier "${getServiceIdentifierName(serviceIdentifier)}" in module "${this.displayName}".`);
-            seen.add(serviceIdentifier);
-            const hasValidOption = "useClass" in decl || "useFactory" in decl || "useValue" in decl || "useAlias" in decl;
-            if (!hasValidOption) throw new Error(`Invalid registration options for service identifier "${getServiceIdentifierName(serviceIdentifier)}" in module "${this.displayName}": must specify useClass, useFactory, useValue, or useAlias.`);
-        }
-    }
     validateExports() {
         if (!this._exports || 0 === this._exports.length) return;
-        const seen = new Set();
-        for (const exportId of this._exports){
-            if (seen.has(exportId)) throw new Error(`Duplicate export of service identifier "${getServiceIdentifierName(exportId)}" in module "${this.displayName}".`);
-            seen.add(exportId);
-        }
-        const availableServices = this.collectAvailableServices();
-        for (const exportId of this._exports)if (!availableServices.has(exportId)) throw new Error(`Cannot export service identifier "${getServiceIdentifierName(exportId)}" from "${this.displayName}": it is not declared in this module or imported from any imported module.`);
-    }
-    collectAvailableServices() {
-        const localServices = (this._declarations ?? []).map((decl)=>decl.serviceIdentifier);
-        const importedServices = (this._imports ?? []).flatMap((item)=>{
-            const module = this.isModuleWithAliases(item) ? item.module : item;
-            const aliases = this.isModuleWithAliases(item) ? item.aliases : void 0;
-            const aliasMap = this.buildAliasMap(aliases);
-            return (module.exports ?? []).map((serviceId)=>aliasMap.get(serviceId) ?? serviceId);
-        });
-        return new Set([
-            ...localServices,
-            ...importedServices
-        ]);
-    }
-    validateAliases(aliases) {
-        if (!aliases || 0 === aliases.length) return;
-        const exportedSet = new Set(this._exports ?? []);
-        const mappedServices = new Set();
-        for (const alias of aliases){
-            const { serviceIdentifier } = alias;
-            if (!exportedSet.has(serviceIdentifier)) throw new Error(`Cannot alias service identifier "${getServiceIdentifierName(serviceIdentifier)}" from module "${this.displayName}": it is not exported from that module.`);
-            if (mappedServices.has(serviceIdentifier)) throw new Error(`Duplicate alias mapping for service identifier "${getServiceIdentifierName(serviceIdentifier)}" in module "${this.displayName}".`);
-            mappedServices.add(serviceIdentifier);
-        }
-    }
-    validateAliasConflictsWithDeclarations() {
-        if (!this._imports || !this._declarations) return;
-        const localDeclarations = new Set((this._declarations ?? []).map((decl)=>decl.serviceIdentifier));
-        const conflictingAlias = (this._imports ?? []).filter((item)=>this.isModuleWithAliases(item)).flatMap((item)=>item.aliases ?? []).find((alias)=>localDeclarations.has(alias.as));
-        if (conflictingAlias) throw new Error(`Alias "${getServiceIdentifierName(conflictingAlias.as)}" conflicts with local declaration in module "${this.displayName}".`);
-    }
-    validateImportNamingConflicts() {
-        if (!this._imports || 0 === this._imports.length) return;
-        const serviceToModules = (this._imports ?? []).reduce((acc, item)=>{
-            const module = this.isModuleWithAliases(item) ? item.module : item;
-            const aliases = this.isModuleWithAliases(item) ? item.aliases : void 0;
-            const aliasMap = this.buildAliasMap(aliases);
-            for (const serviceId of module.exports ?? []){
-                const effectiveName = aliasMap.get(serviceId) ?? serviceId;
-                const modules = acc.get(effectiveName) ?? [];
-                modules.push(module);
-                acc.set(effectiveName, 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 Error(`Service identifier "${getServiceIdentifierName(serviceId)}" is exported by multiple imported modules: ${moduleNames}. Consider using aliases to resolve the conflict.`);
-        }
-    }
-    isModuleWithAliases(item) {
-        return "module" in item;
+        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/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.1",
+  "version": "1.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -15,13 +15,13 @@
     "dist"
   ],
   "dependencies": {
-    "@husky-di/core": "1.0.1"
+    "@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"

package/dist/impls/module.d.ts

@@ -1,194 +0,0 @@
-/**
- * @overview
- * @author AEPKILL
- * @created 2025-08-09 14:51:09
- */
-import { 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 {
-    get id(): string;
-    get name(): string;
-    get declarations(): Declaration<unknown>[] | undefined;
-    get exports(): ServiceIdentifier<unknown>[] | undefined;
-    get imports(): (IModule | ModuleWithAliases)[] | undefined;
-    get displayName(): string;
-    readonly container: IContainer;
-    private _id;
-    private _name;
-    private _declarations?;
-    private _imports?;
-    private _exports?;
-    private readonly _visitedModules;
-    private readonly _visitStack;
-    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;
-    withAliases(aliases: Alias[]): ModuleWithAliases;
-    /**
-     * Builds the container for this module.
-     *
-     * @returns The built container
-     *
-     * @remarks
-     * This method is called after all validations have been performed.
-     * It creates the container and registers all declarations and imports.
-     */
-    private buildContainer;
-    /**
-     * Validates the module's imports.
-     *
-     * @throws Error if validation fails
-     *
-     * @remarks
-     * Validates the following rules:
-     * - Rule I1: Module uniqueness - no module imported multiple times
-     * - Rule I2: Circular dependencies - no circular import chains
-     * - Rule I3: Alias validation - aliases reference exported services and don't conflict
-     * - Rule I4: Import naming conflicts - no service name conflicts across imports
-     */
-    private validateImports;
-    /**
-     * Validates that no module is imported multiple times (Rule I1).
-     *
-     * @param imports - Array of imports to validate
-     * @throws Error if a module is imported more than once
-     *
-     * @remarks
-     * This prevents accidentally importing the same module multiple times,
-     * which would be redundant and potentially confusing.
-     */
-    private validateImportUniqueness;
-    /**
-     * Detects circular dependencies in the module import graph.
-     *
-     * @throws Error if a circular dependency is detected
-     */
-    private detectCircularDependencies;
-    /**
-     * Recursively visits a module to detect circular dependencies (Rule I2).
-     *
-     * @param module - The module to visit
-     * @throws Error if a circular dependency is detected
-     *
-     * @remarks
-     * Uses depth-first search with a visit stack to detect cycles.
-     * The visit stack tracks the current path being explored, while
-     * visitedModules tracks fully processed modules to avoid redundant work.
-     */
-    private visitModule;
-    /**
-     * Registers the module's local declarations in the container.
-     *
-     * @param container - The container to register declarations in
-     */
-    private registerDeclarations;
-    /**
-     * Registers the module's imports in the container.
-     *
-     * @param container - The container to register imports in
-     */
-    private registerImports;
-    /**
-     * Normalizes imports into a flat list of service identifiers with their aliases.
-     *
-     * @param imports - Array of imports to normalize
-     * @returns Normalized array of imports with alias mappings
-     *
-     * @remarks
-     * This method transforms the import declarations into a format suitable
-     * for container registration, applying any alias mappings in the process.
-     */
-    private normalizeImports;
-    /**
-     * Builds a map of service identifier aliases from an alias array.
-     *
-     * @param aliases - Array of alias mappings
-     * @returns Map from source service identifier to target service identifier
-     *
-     * @remarks
-     * This method is used throughout the validation and registration process
-     * to consistently apply alias transformations.
-     */
-    private buildAliasMap;
-    /**
-     * Validates declarations for this module.
-     *
-     * @throws Error if validation fails
-     *
-     * @remarks
-     * Validates that:
-     * 1. No serviceIdentifier is declared multiple times (Rule D1)
-     * 2. Each declaration has valid registration options (Rule D2)
-     */
-    private validateDeclarations;
-    /**
-     * Validates exports for this module.
-     *
-     * @throws Error if validation fails
-     *
-     * @remarks
-     * Validates that:
-     * 1. No serviceIdentifier is exported multiple times
-     * 2. Each exported serviceIdentifier is either declared locally or imported
-     * 3. Aliased imports must be exported using their alias name, not original name
-     */
-    private validateExports;
-    /**
-     * Collects all service identifiers that are available in this module.
-     *
-     * @returns Set of available service identifiers
-     *
-     * @remarks
-     * Available services include:
-     * 1. Locally declared services
-     * 2. Imported services (considering aliases)
-     *
-     * This is used by validateExports to ensure only available services are exported.
-     */
-    private collectAvailableServices;
-    /**
-     * Validates aliases for this module (called from withAliases).
-     *
-     * @param aliases - Array of alias mappings to validate
-     * @throws Error if validation fails
-     *
-     * @remarks
-     * Validates that:
-     * 1. Each aliased serviceIdentifier is exported by this module (Rule I3.1)
-     * 2. No serviceIdentifier is mapped multiple times (Rule I3.2)
-     *
-     * Note: Rule I3.3 (alias conflicts with declarations) is validated during
-     * module construction in validateAliasConflictsWithDeclarations()
-     */
-    private validateAliases;
-    /**
-     * Validates that aliases don't conflict with local declarations (Rule I3.3).
-     *
-     * @throws Error if an alias name conflicts with a local declaration
-     *
-     * @remarks
-     * This ensures that aliased imports don't shadow or conflict with
-     * services declared in the current module.
-     */
-    private validateAliasConflictsWithDeclarations;
-    /**
-     * Validates that imported services don't have naming conflicts (Rule I4).
-     *
-     * @throws Error if the same service identifier is exported by multiple modules
-     *
-     * @remarks
-     * This prevents ambiguity when multiple imported modules export services
-     * with the same name. Users should use aliases to resolve such conflicts.
-     */
-    private validateImportNamingConflicts;
-    /**
-     * Helper method to check if an import item is a ModuleWithAliases.
-     *
-     * @param item - The import item to check
-     * @returns True if the item is a ModuleWithAliases, false otherwise
-     */
-    private isModuleWithAliases;
-}