@esmx/import 3.0.0-rc.30 → 3.0.0-rc.32

package/dist/error.d.ts

@@ -0,0 +1,14 @@
+export declare const formatCircularDependency: (moduleIds: string[], targetModule: string) => string;
+export declare const formatModuleChain: (moduleIds: string[], targetModule: string, originalError?: Error) => string;
+export declare class ModuleLoadingError extends Error {
+    moduleIds: string[];
+    targetModule: string;
+    originalError?: Error | undefined;
+    constructor(message: string, moduleIds: string[], targetModule: string, originalError?: Error | undefined);
+}
+export declare class CircularDependencyError extends ModuleLoadingError {
+    constructor(message: string, moduleIds: string[], targetModule: string);
+}
+export declare class FileReadError extends ModuleLoadingError {
+    constructor(message: string, moduleIds: string[], targetModule: string, originalError?: Error);
+}

package/dist/error.mjs

@@ -0,0 +1,104 @@
+import path from "node:path";
+const Colors = {
+  RED: "\x1B[31m",
+  YELLOW: "\x1B[33m",
+  CYAN: "\x1B[36m",
+  GRAY: "\x1B[90m",
+  RESET: "\x1B[0m",
+  BOLD: "\x1B[1m"
+};
+const supportsColor = () => {
+  return !!(process.stdout?.isTTY && process.env.TERM !== "dumb") || process.env.FORCE_COLOR === "1" || process.env.FORCE_COLOR === "true";
+};
+const useColors = supportsColor() && process.env.NO_COLOR !== "1";
+const colorize = (text, color) => {
+  return useColors ? `${color}${text}${Colors.RESET}` : text;
+};
+const getRelativeFromCwd = (filePath) => {
+  return path.relative(process.cwd(), filePath);
+};
+export const formatCircularDependency = (moduleIds, targetModule) => {
+  const fullChain = [...moduleIds, targetModule];
+  return `${colorize(colorize("Module dependency chain (circular reference found):", Colors.BOLD), Colors.RED)}
+${fullChain.map((module, index) => {
+    const isLastModule = index === fullChain.length - 1;
+    const prefix = index === 0 ? "\u250C\u2500 " : index === fullChain.length - 1 ? "\u2514\u2500 " : "\u251C\u2500 ";
+    const displayPath = getRelativeFromCwd(module);
+    const isCircularModule = fullChain.filter((m) => m === module).length > 1;
+    const coloredFile = isCircularModule ? colorize(colorize(displayPath, Colors.BOLD), Colors.RED) : colorize(displayPath, Colors.CYAN);
+    const suffix = isLastModule ? ` ${colorize("\u{1F504} Creates circular reference", Colors.YELLOW)}` : "";
+    return `${colorize(prefix, Colors.GRAY)}${coloredFile}${suffix}`;
+  }).join("\n")}`;
+};
+export const formatModuleChain = (moduleIds, targetModule, originalError) => {
+  let result = "";
+  if (moduleIds.length === 0) {
+    const displayPath = getRelativeFromCwd(targetModule);
+    result = `${colorize("Failed to load:", Colors.CYAN)} ${colorize(displayPath, Colors.RED)}`;
+  } else {
+    const chain = [...moduleIds, targetModule];
+    result = `${colorize(colorize("Module loading path:", Colors.BOLD), Colors.CYAN)}
+${chain.map((module, index) => {
+      const indent = "  ".repeat(index);
+      const connector = index === 0 ? "" : "\u2514\u2500 ";
+      const displayPath = getRelativeFromCwd(module);
+      const isFailedFile = index === chain.length - 1;
+      const coloredFile = isFailedFile ? colorize(colorize(displayPath, Colors.BOLD), Colors.RED) : colorize(displayPath, Colors.CYAN);
+      const status = isFailedFile ? ` ${colorize(colorize("\u274C Loading failed", Colors.BOLD), Colors.RED)}` : "";
+      return `${colorize(indent + connector, Colors.GRAY)}${coloredFile}${status}`;
+    }).join("\n")}`;
+  }
+  if (originalError) {
+    result += `
+
+${colorize("Error details:", Colors.YELLOW)} ${originalError.message}`;
+  }
+  return result;
+};
+export class ModuleLoadingError extends Error {
+  constructor(message, moduleIds, targetModule, originalError) {
+    super(message);
+    this.moduleIds = moduleIds;
+    this.targetModule = targetModule;
+    this.originalError = originalError;
+    this.name = "ModuleLoadingError";
+    Object.defineProperty(this, "moduleIds", {
+      value: moduleIds,
+      writable: false,
+      enumerable: false,
+      configurable: true
+    });
+    Object.defineProperty(this, "targetModule", {
+      value: targetModule,
+      writable: false,
+      enumerable: false,
+      configurable: true
+    });
+    if (originalError) {
+      Object.defineProperty(this, "originalError", {
+        value: originalError,
+        writable: false,
+        enumerable: false,
+        configurable: true
+      });
+    }
+  }
+}
+export class CircularDependencyError extends ModuleLoadingError {
+  constructor(message, moduleIds, targetModule) {
+    super(message, moduleIds, targetModule);
+    this.name = "CircularDependencyError";
+    this.stack = `${this.name}: ${message}
+
+${formatCircularDependency(moduleIds, targetModule)}`;
+  }
+}
+export class FileReadError extends ModuleLoadingError {
+  constructor(message, moduleIds, targetModule, originalError) {
+    super(message, moduleIds, targetModule, originalError);
+    this.name = "FileReadError";
+    this.stack = `${this.name}: ${message}
+
+${formatModuleChain(moduleIds, targetModule, originalError)}`;
+  }
+}

package/dist/error.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/error.test.mjs

@@ -0,0 +1,167 @@
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  CircularDependencyError,
+  FileReadError,
+  ModuleLoadingError,
+  formatCircularDependency,
+  formatModuleChain
+} from "./error.mjs";
+describe("Module Loading Errors", () => {
+  let originalEnv;
+  beforeEach(() => {
+    originalEnv = process.env.NO_COLOR;
+    process.env.NO_COLOR = "1";
+  });
+  afterEach(() => {
+    if (originalEnv !== void 0) {
+      process.env.NO_COLOR = originalEnv;
+    } else {
+      process.env.NO_COLOR = void 0;
+    }
+  });
+  describe("CircularDependencyError", () => {
+    it("should create circular dependency error with correct properties", () => {
+      const moduleIds = ["/src/A.js", "/src/B.js"];
+      const targetModule = "/src/A.js";
+      const error = new CircularDependencyError(
+        "Test circular dependency",
+        moduleIds,
+        targetModule
+      );
+      expect(error.name).toBe("CircularDependencyError");
+      expect(error.message).toBe("Test circular dependency");
+      expect(error.stack).toContain("Test circular dependency");
+      expect(error.stack).toContain(
+        "Module dependency chain (circular reference found):"
+      );
+      expect(error.stack).toContain("\u250C\u2500");
+      expect(error.stack).toContain("\u2514\u2500");
+      expect(error.stack).toContain("\u{1F504} Creates circular reference");
+      expect(error.moduleIds).toEqual(moduleIds);
+      expect(error.targetModule).toBe(targetModule);
+      expect(error instanceof ModuleLoadingError).toBe(true);
+    });
+    it("should format circular dependency in toString", () => {
+      const moduleIds = ["/src/A.js", "/src/B.js"];
+      const targetModule = "/src/A.js";
+      const error = new CircularDependencyError(
+        "Circular dependency detected",
+        moduleIds,
+        targetModule
+      );
+      const formatted = error.toString();
+      expect(formatted).toContain("CircularDependencyError");
+      expect(formatted).toContain("Circular dependency detected");
+    });
+  });
+  describe("FileReadError", () => {
+    it("should create file read error with correct properties", () => {
+      const moduleIds = ["/src/main.js", "/src/components/App.js"];
+      const targetModule = "/src/missing.js";
+      const originalError = new Error(
+        "ENOENT: no such file or directory"
+      );
+      const error = new FileReadError(
+        "Failed to read module",
+        moduleIds,
+        targetModule,
+        originalError
+      );
+      expect(error.name).toBe("FileReadError");
+      expect(error.message).toBe("Failed to read module");
+      expect(error.stack).toContain("Failed to read module");
+      expect(error.stack).toContain("Module loading path:");
+      expect(error.stack).toContain("main.js");
+      expect(error.stack).toContain("App.js");
+      expect(error.stack).toContain("missing.js");
+      expect(error.stack).toContain("\u274C Loading failed");
+      expect(error.stack).toContain("Error details:");
+      expect(error.stack).toContain("ENOENT");
+      expect(error.moduleIds).toEqual(moduleIds);
+      expect(error.targetModule).toBe(targetModule);
+      expect(error.originalError).toBe(originalError);
+      expect(error instanceof ModuleLoadingError).toBe(true);
+    });
+    it("should format module chain in toString", () => {
+      const moduleIds = ["/src/main.js", "/src/components/App.js"];
+      const targetModule = "/src/missing.js";
+      const originalError = new Error(
+        "ENOENT: no such file or directory"
+      );
+      const error = new FileReadError(
+        "Failed to read module",
+        moduleIds,
+        targetModule,
+        originalError
+      );
+      const formatted = error.toString();
+      expect(formatted).toContain("FileReadError");
+      expect(formatted).toContain("Failed to read module");
+    });
+  });
+  describe("Formatting Functions", () => {
+    it("should format circular dependency correctly", () => {
+      const moduleIds = ["/src/A.js", "/src/B.js", "/src/C.js"];
+      const targetModule = "/src/A.js";
+      const formatted = formatCircularDependency(moduleIds, targetModule);
+      const relativeA = path.relative(process.cwd(), "/src/A.js");
+      const relativeB = path.relative(process.cwd(), "/src/B.js");
+      const relativeC = path.relative(process.cwd(), "/src/C.js");
+      expect(formatted).toContain(
+        "Module dependency chain (circular reference found):"
+      );
+      expect(formatted).toContain(`\u250C\u2500 ${relativeA}`);
+      expect(formatted).toContain(`\u251C\u2500 ${relativeB}`);
+      expect(formatted).toContain(`\u251C\u2500 ${relativeC}`);
+      expect(formatted).toContain(`\u2514\u2500 ${relativeA}`);
+      expect(formatted).toContain("\u{1F504} Creates circular reference");
+    });
+    it("should format module chain correctly", () => {
+      const moduleIds = ["/src/main.js", "/src/app.js"];
+      const targetModule = "/src/missing.js";
+      const originalError = new Error("File not found");
+      const formatted = formatModuleChain(
+        moduleIds,
+        targetModule,
+        originalError
+      );
+      expect(formatted).toContain("Module loading path:");
+      expect(formatted).toContain("main.js");
+      expect(formatted).toContain("app.js");
+      expect(formatted).toContain("missing.js");
+      expect(formatted).toContain("\u274C Loading failed");
+      expect(formatted).toContain("Error details:");
+      expect(formatted).toContain("File not found");
+    });
+    it("should handle empty moduleIds in formatModuleChain", () => {
+      const moduleIds = [];
+      const targetModule = "/src/standalone.js";
+      const formatted = formatModuleChain(moduleIds, targetModule);
+      expect(formatted).toContain("Failed to load:");
+      expect(formatted).toContain("standalone.js");
+    });
+    it("should handle deep module chains", () => {
+      const moduleIds = [
+        "/src/a.js",
+        "/src/b.js",
+        "/src/c.js",
+        "/src/d.js"
+      ];
+      const targetModule = "/src/e.js";
+      const formatted = formatModuleChain(moduleIds, targetModule);
+      const relativeA = path.relative(process.cwd(), "/src/a.js");
+      const relativeB = path.relative(process.cwd(), "/src/b.js");
+      const relativeC = path.relative(process.cwd(), "/src/c.js");
+      const relativeD = path.relative(process.cwd(), "/src/d.js");
+      const relativeE = path.relative(process.cwd(), "/src/e.js");
+      expect(formatted).toContain(relativeA);
+      expect(formatted).toContain(`  \u2514\u2500 ${relativeB}`);
+      expect(formatted).toContain(`    \u2514\u2500 ${relativeC}`);
+      expect(formatted).toContain(`      \u2514\u2500 ${relativeD}`);
+      expect(formatted).toContain(
+        `        \u2514\u2500 ${relativeE} \u274C Loading failed`
+      );
+    });
+  });
+});

package/dist/import-vm.mjs

@@ -3,6 +3,7 @@ import { isBuiltin } from "node:module";
 import path from "node:path";
 import vm from "node:vm";
 import IM from "@import-maps/resolve";
+import { CircularDependencyError, FileReadError } from "./error.mjs";
 async function importBuiltinModule(specifier, context) {
   const nodeModule = await import(specifier);
   const keys = Object.keys(nodeModule);
@@ -47,29 +48,35 @@ export function createVmImport(baseURL, importMap = {}) {
     }
     const parsed = parse(specifier, parent);
     if (moduleIds.includes(parsed.pathname)) {
-      throw new RangeError(
-        `Module circular reference: 
- ${JSON.stringify([...moduleIds, parsed.pathname], null, 4)}`
+      throw new CircularDependencyError(
+        "Circular dependency detected",
+        moduleIds,
+        parsed.pathname
       );
     }
     const module = cache.get(parsed.pathname);
     if (module) {
       return module;
     }
-    const pe = new Promise((resolve) => {
+    const modulePromise = new Promise((resolve) => {
       process.nextTick(() => {
         moduleBuild().then(resolve);
       });
     });
     const dirname = path.dirname(parsed.filename);
-    cache.set(parsed.pathname, pe);
-    return pe;
+    cache.set(parsed.pathname, modulePromise);
+    return modulePromise;
     async function moduleBuild() {
       let text;
       try {
         text = fs.readFileSync(parsed.pathname, "utf-8");
-      } catch {
-        throw new Error(`Failed to read module: ${parsed.pathname}`);
+      } catch (error) {
+        throw new FileReadError(
+          `Failed to read module: ${parsed.pathname}`,
+          moduleIds,
+          parsed.pathname,
+          error
+        );
       }
       const module2 = new vm.SourceTextModule(text, {
         initializeImportMeta: (meta) => {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { createVmImport } from './import-vm';
 export { createLoaderImport } from './import-loader';
 export type { ImportMap, SpecifierMap, ScopesMap } from './types';
+export { ModuleLoadingError, CircularDependencyError, FileReadError, formatCircularDependency, formatModuleChain } from './error';

package/dist/index.mjs

@@ -1,2 +1,9 @@
 export { createVmImport } from "./import-vm.mjs";
 export { createLoaderImport } from "./import-loader.mjs";
+export {
+  ModuleLoadingError,
+  CircularDependencyError,
+  FileReadError,
+  formatCircularDependency,
+  formatModuleChain
+} from "./error.mjs";

package/package.json

@@ -33,7 +33,7 @@
     },
     "devDependencies": {
         "@biomejs/biome": "1.9.4",
-        "@esmx/lint": "3.0.0-rc.30",
+        "@esmx/lint": "3.0.0-rc.32",
         "@types/node": "^24.0.0",
         "@vitest/coverage-v8": "3.2.4",
         "stylelint": "16.21.0",
@@ -41,7 +41,7 @@
         "unbuild": "3.5.0",
         "vitest": "3.2.4"
     },
-    "version": "3.0.0-rc.30",
+    "version": "3.0.0-rc.32",
     "type": "module",
     "private": false,
     "exports": {
@@ -60,5 +60,5 @@
         "template",
         "public"
     ],
-    "gitHead": "0bc6815e4a805e552e67a245201a4a75599f58f5"
+    "gitHead": "8f7c52dde97c2cf74a783e578328cc72bde78c3b"
 }

package/src/error.test.ts

@@ -0,0 +1,206 @@
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+    CircularDependencyError,
+    FileReadError,
+    ModuleLoadingError,
+    formatCircularDependency,
+    formatModuleChain
+} from './error';
+
+describe('Module Loading Errors', () => {
+    let originalEnv: string | undefined;
+
+    beforeEach(() => {
+        originalEnv = process.env.NO_COLOR;
+        process.env.NO_COLOR = '1'; // Disable colors for testing
+    });
+
+    afterEach(() => {
+        if (originalEnv !== undefined) {
+            process.env.NO_COLOR = originalEnv;
+        } else {
+            process.env.NO_COLOR = undefined;
+        }
+    });
+
+    describe('CircularDependencyError', () => {
+        it('should create circular dependency error with correct properties', () => {
+            const moduleIds = ['/src/A.js', '/src/B.js'];
+            const targetModule = '/src/A.js';
+
+            const error = new CircularDependencyError(
+                'Test circular dependency',
+                moduleIds,
+                targetModule
+            );
+
+            expect(error.name).toBe('CircularDependencyError');
+            // Message is now clean and simple
+            expect(error.message).toBe('Test circular dependency');
+            // Formatted content is in stack property
+            expect(error.stack).toContain('Test circular dependency');
+            expect(error.stack).toContain(
+                'Module dependency chain (circular reference found):'
+            );
+            expect(error.stack).toContain('┌─');
+            expect(error.stack).toContain('└─');
+            expect(error.stack).toContain('🔄 Creates circular reference');
+            expect(error.moduleIds).toEqual(moduleIds);
+            expect(error.targetModule).toBe(targetModule);
+            expect(error instanceof ModuleLoadingError).toBe(true);
+        });
+
+        it('should format circular dependency in toString', () => {
+            const moduleIds = ['/src/A.js', '/src/B.js'];
+            const targetModule = '/src/A.js';
+
+            const error = new CircularDependencyError(
+                'Circular dependency detected',
+                moduleIds,
+                targetModule
+            );
+
+            const formatted = error.toString();
+
+            expect(formatted).toContain('CircularDependencyError');
+            expect(formatted).toContain('Circular dependency detected');
+            // toString() now uses default Error behavior, so it only shows name and message
+        });
+    });
+
+    describe('FileReadError', () => {
+        it('should create file read error with correct properties', () => {
+            const moduleIds = ['/src/main.js', '/src/components/App.js'];
+            const targetModule = '/src/missing.js';
+            const originalError = new Error(
+                'ENOENT: no such file or directory'
+            );
+
+            const error = new FileReadError(
+                'Failed to read module',
+                moduleIds,
+                targetModule,
+                originalError
+            );
+
+            expect(error.name).toBe('FileReadError');
+            // Message is now clean and simple
+            expect(error.message).toBe('Failed to read module');
+            // Formatted content is in stack property
+            expect(error.stack).toContain('Failed to read module');
+            expect(error.stack).toContain('Module loading path:');
+            expect(error.stack).toContain('main.js');
+            expect(error.stack).toContain('App.js');
+            expect(error.stack).toContain('missing.js');
+            expect(error.stack).toContain('❌ Loading failed');
+            expect(error.stack).toContain('Error details:');
+            expect(error.stack).toContain('ENOENT');
+            expect(error.moduleIds).toEqual(moduleIds);
+            expect(error.targetModule).toBe(targetModule);
+            expect(error.originalError).toBe(originalError);
+            expect(error instanceof ModuleLoadingError).toBe(true);
+        });
+
+        it('should format module chain in toString', () => {
+            const moduleIds = ['/src/main.js', '/src/components/App.js'];
+            const targetModule = '/src/missing.js';
+            const originalError = new Error(
+                'ENOENT: no such file or directory'
+            );
+
+            const error = new FileReadError(
+                'Failed to read module',
+                moduleIds,
+                targetModule,
+                originalError
+            );
+
+            const formatted = error.toString();
+
+            expect(formatted).toContain('FileReadError');
+            expect(formatted).toContain('Failed to read module');
+            // toString() now uses default Error behavior, so it only shows name and message
+        });
+    });
+
+    describe('Formatting Functions', () => {
+        it('should format circular dependency correctly', () => {
+            const moduleIds = ['/src/A.js', '/src/B.js', '/src/C.js'];
+            const targetModule = '/src/A.js';
+
+            const formatted = formatCircularDependency(moduleIds, targetModule);
+
+            // Calculate expected relative paths
+            const relativeA = path.relative(process.cwd(), '/src/A.js');
+            const relativeB = path.relative(process.cwd(), '/src/B.js');
+            const relativeC = path.relative(process.cwd(), '/src/C.js');
+
+            expect(formatted).toContain(
+                'Module dependency chain (circular reference found):'
+            );
+            expect(formatted).toContain(`┌─ ${relativeA}`);
+            expect(formatted).toContain(`├─ ${relativeB}`);
+            expect(formatted).toContain(`├─ ${relativeC}`);
+            expect(formatted).toContain(`└─ ${relativeA}`);
+            expect(formatted).toContain('🔄 Creates circular reference');
+        });
+
+        it('should format module chain correctly', () => {
+            const moduleIds = ['/src/main.js', '/src/app.js'];
+            const targetModule = '/src/missing.js';
+            const originalError = new Error('File not found');
+
+            const formatted = formatModuleChain(
+                moduleIds,
+                targetModule,
+                originalError
+            );
+
+            expect(formatted).toContain('Module loading path:');
+            expect(formatted).toContain('main.js');
+            expect(formatted).toContain('app.js');
+            expect(formatted).toContain('missing.js');
+            expect(formatted).toContain('❌ Loading failed');
+            expect(formatted).toContain('Error details:');
+            expect(formatted).toContain('File not found');
+        });
+
+        it('should handle empty moduleIds in formatModuleChain', () => {
+            const moduleIds: string[] = [];
+            const targetModule = '/src/standalone.js';
+
+            const formatted = formatModuleChain(moduleIds, targetModule);
+
+            expect(formatted).toContain('Failed to load:');
+            expect(formatted).toContain('standalone.js');
+        });
+
+        it('should handle deep module chains', () => {
+            const moduleIds = [
+                '/src/a.js',
+                '/src/b.js',
+                '/src/c.js',
+                '/src/d.js'
+            ];
+            const targetModule = '/src/e.js';
+
+            const formatted = formatModuleChain(moduleIds, targetModule);
+
+            // Calculate expected relative paths
+            const relativeA = path.relative(process.cwd(), '/src/a.js');
+            const relativeB = path.relative(process.cwd(), '/src/b.js');
+            const relativeC = path.relative(process.cwd(), '/src/c.js');
+            const relativeD = path.relative(process.cwd(), '/src/d.js');
+            const relativeE = path.relative(process.cwd(), '/src/e.js');
+
+            expect(formatted).toContain(relativeA);
+            expect(formatted).toContain(`  └─ ${relativeB}`);
+            expect(formatted).toContain(`    └─ ${relativeC}`);
+            expect(formatted).toContain(`      └─ ${relativeD}`);
+            expect(formatted).toContain(
+                `        └─ ${relativeE} ❌ Loading failed`
+            );
+        });
+    });
+});

package/src/error.ts

@@ -0,0 +1,172 @@
+import path from 'node:path';
+
+// Color constants for terminal output
+const Colors = {
+    RED: '\x1b[31m',
+    YELLOW: '\x1b[33m',
+    CYAN: '\x1b[36m',
+    GRAY: '\x1b[90m',
+    RESET: '\x1b[0m',
+    BOLD: '\x1b[1m'
+};
+
+// Check if terminal supports colors
+const supportsColor = (): boolean => {
+    return (
+        !!(process.stdout?.isTTY && process.env.TERM !== 'dumb') ||
+        process.env.FORCE_COLOR === '1' ||
+        process.env.FORCE_COLOR === 'true'
+    );
+};
+
+// Color formatter utility
+const useColors = supportsColor() && process.env.NO_COLOR !== '1';
+
+const colorize = (text: string, color: string): string => {
+    return useColors ? `${color}${text}${Colors.RESET}` : text;
+};
+
+// Get relative path from current working directory
+const getRelativeFromCwd = (filePath: string): string => {
+    return path.relative(process.cwd(), filePath);
+};
+
+// Formatting functions
+export const formatCircularDependency = (
+    moduleIds: string[],
+    targetModule: string
+): string => {
+    const fullChain = [...moduleIds, targetModule];
+
+    return `${colorize(colorize('Module dependency chain (circular reference found):', Colors.BOLD), Colors.RED)}\n${fullChain
+        .map((module, index) => {
+            const isLastModule = index === fullChain.length - 1;
+            const prefix =
+                index === 0
+                    ? '┌─ '
+                    : index === fullChain.length - 1
+                      ? '└─ '
+                      : '├─ ';
+
+            const displayPath = getRelativeFromCwd(module);
+
+            // Check if this module appears elsewhere in the chain (circular dependency)
+            const isCircularModule =
+                fullChain.filter((m) => m === module).length > 1;
+
+            const coloredFile = isCircularModule
+                ? colorize(colorize(displayPath, Colors.BOLD), Colors.RED)
+                : colorize(displayPath, Colors.CYAN);
+
+            const suffix = isLastModule
+                ? ` ${colorize('🔄 Creates circular reference', Colors.YELLOW)}`
+                : '';
+
+            return `${colorize(prefix, Colors.GRAY)}${coloredFile}${suffix}`;
+        })
+        .join('\n')}`;
+};
+
+export const formatModuleChain = (
+    moduleIds: string[],
+    targetModule: string,
+    originalError?: Error
+): string => {
+    let result = '';
+
+    if (moduleIds.length === 0) {
+        const displayPath = getRelativeFromCwd(targetModule);
+
+        result = `${colorize('Failed to load:', Colors.CYAN)} ${colorize(displayPath, Colors.RED)}`;
+    } else {
+        const chain = [...moduleIds, targetModule];
+        result = `${colorize(colorize('Module loading path:', Colors.BOLD), Colors.CYAN)}\n${chain
+            .map((module, index) => {
+                const indent = '  '.repeat(index);
+                const connector = index === 0 ? '' : '└─ ';
+                const displayPath = getRelativeFromCwd(module);
+
+                const isFailedFile = index === chain.length - 1;
+                const coloredFile = isFailedFile
+                    ? colorize(colorize(displayPath, Colors.BOLD), Colors.RED)
+                    : colorize(displayPath, Colors.CYAN);
+
+                const status = isFailedFile
+                    ? ` ${colorize(colorize('❌ Loading failed', Colors.BOLD), Colors.RED)}`
+                    : '';
+
+                return `${colorize(indent + connector, Colors.GRAY)}${coloredFile}${status}`;
+            })
+            .join('\n')}`;
+    }
+
+    if (originalError) {
+        result += `\n\n${colorize('Error details:', Colors.YELLOW)} ${originalError.message}`;
+    }
+
+    return result;
+};
+
+// Base module loading error class
+export class ModuleLoadingError extends Error {
+    constructor(
+        message: string,
+        public moduleIds: string[],
+        public targetModule: string,
+        public originalError?: Error
+    ) {
+        super(message);
+        this.name = 'ModuleLoadingError';
+
+        // Hide auxiliary properties from enumeration to avoid cluttering error display
+        Object.defineProperty(this, 'moduleIds', {
+            value: moduleIds,
+            writable: false,
+            enumerable: false,
+            configurable: true
+        });
+
+        Object.defineProperty(this, 'targetModule', {
+            value: targetModule,
+            writable: false,
+            enumerable: false,
+            configurable: true
+        });
+
+        if (originalError) {
+            Object.defineProperty(this, 'originalError', {
+                value: originalError,
+                writable: false,
+                enumerable: false,
+                configurable: true
+            });
+        }
+    }
+}
+
+// Circular dependency error class
+export class CircularDependencyError extends ModuleLoadingError {
+    constructor(message: string, moduleIds: string[], targetModule: string) {
+        super(message, moduleIds, targetModule);
+        this.name = 'CircularDependencyError';
+
+        // Custom stack for clean error display
+        this.stack = `${this.name}: ${message}\n\n${formatCircularDependency(moduleIds, targetModule)}`;
+    }
+}
+
+// File read error class
+export class FileReadError extends ModuleLoadingError {
+    constructor(
+        message: string,
+        moduleIds: string[],
+        targetModule: string,
+        originalError?: Error
+    ) {
+        super(message, moduleIds, targetModule, originalError);
+        this.name = 'FileReadError';
+
+        // Custom stack for clean error display
+        this.stack = `${this.name}: ${message}\n\n${formatModuleChain(moduleIds, targetModule, originalError)}`;
+    }
+}

package/src/import-vm.ts

@@ -3,6 +3,7 @@ import { isBuiltin } from 'node:module';
 import path from 'node:path';
 import vm from 'node:vm';
 import IM from '@import-maps/resolve';
+import { CircularDependencyError, FileReadError } from './error';
 import type { ImportMap } from './types';
 
 async function importBuiltinModule(specifier: string, context: vm.Context) {
@@ -58,8 +59,10 @@ export function createVmImport(baseURL: URL, importMap: ImportMap = {}) {
         const parsed = parse(specifier, parent);
 
         if (moduleIds.includes(parsed.pathname)) {
-            throw new RangeError(
-                `Module circular reference: \n ${JSON.stringify([...moduleIds, parsed.pathname], null, 4)}`
+            throw new CircularDependencyError(
+                'Circular dependency detected',
+                moduleIds,
+                parsed.pathname
             );
         }
 
@@ -67,22 +70,27 @@ export function createVmImport(baseURL: URL, importMap: ImportMap = {}) {
         if (module) {
             return module;
         }
-        const pe = new Promise<vm.SourceTextModule>((resolve) => {
+        const modulePromise = new Promise<vm.SourceTextModule>((resolve) => {
             process.nextTick(() => {
                 moduleBuild().then(resolve);
             });
         });
 
         const dirname = path.dirname(parsed.filename);
-        cache.set(parsed.pathname, pe);
-        return pe;
+        cache.set(parsed.pathname, modulePromise);
+        return modulePromise;
 
         async function moduleBuild(): Promise<vm.SourceTextModule> {
             let text: string;
             try {
                 text = fs.readFileSync(parsed.pathname, 'utf-8');
-            } catch {
-                throw new Error(`Failed to read module: ${parsed.pathname}`);
+            } catch (error) {
+                throw new FileReadError(
+                    `Failed to read module: ${parsed.pathname}`,
+                    moduleIds,
+                    parsed.pathname,
+                    error as Error
+                );
             }
             const module = new vm.SourceTextModule(text, {
                 initializeImportMeta: (meta) => {

package/src/index.ts

@@ -1,3 +1,10 @@
 export { createVmImport } from './import-vm';
 export { createLoaderImport } from './import-loader';
 export type { ImportMap, SpecifierMap, ScopesMap } from './types';
+export {
+    ModuleLoadingError,
+    CircularDependencyError,
+    FileReadError,
+    formatCircularDependency,
+    formatModuleChain
+} from './error';