0
# Module Evaluation
1

2
Safe module evaluation using data: URLs with automatic import resolution and stack trace preservation. Includes transformation utilities for JSON modules and import.meta.url rewriting.
3

4
## Capabilities
5

6
### Load Module
7

8
Loads a module by resolving its identifier to a URL, fetching the module's code and evaluating it.
9

10
```typescript { .api }
11
/**
12
 * Loads a module by resolving its identifier to a URL, fetching the module's code and evaluating it
13
 * @param id - The identifier of the module to load
14
 * @param options - Optional parameters to resolve and load the module
15
 * @returns A promise to resolve to the evaluated module
16
 */
17
function loadModule(id: string, options?: EvaluateOptions): Promise<any>;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { loadModule } from "mlly";
24

25
// Load a module by path
26
const utils = await loadModule("./utils.mjs", { url: import.meta.url });
27

28
// Load with custom resolution options
29
const config = await loadModule("./config.json", {
30
  url: import.meta.url,
31
  extensions: [".json", ".mjs"]
32
});
33
```
34

35
### Eval Module
36

37
Evaluates JavaScript code as a module using a dynamic import from a data URL.
38

39
```typescript { .api }
40
/**
41
 * Evaluates JavaScript code as a module using a dynamic import from a data URL
42
 * @param code - The code of the module to evaluate
43
 * @param options - Includes the original URL of the module for better error mapping
44
 * @returns A promise that resolves to the evaluated module or throws an error if the evaluation fails
45
 */
46
function evalModule(code: string, options?: EvaluateOptions): Promise<any>;
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { evalModule } from "mlly";
53

54
// Evaluate simple module code
55
const result = await evalModule(`
56
  export const greeting = "Hello World!";
57
  export default function() { return 42; }
58
`);
59

60
console.log(result.greeting); // "Hello World!"
61
console.log(result.default()); // 42
62

63
// Evaluate with import resolution
64
const moduleWithImports = await evalModule(`
65
  import { join } from 'path';
66
  export const fullPath = join('/home', 'user', 'file.txt');
67
`, { url: import.meta.url });
68
```
69

70
### Transform Module
71

72
Transform module code to handle specific scenarios, such as converting JSON to a module or rewriting import.meta.url.
73

74
```typescript { .api }
75
/**
76
 * Transform module code to handle specific scenarios, such as converting JSON to a module or rewriting import.meta.url
77
 * @param code - The code of the module to transform
78
 * @param options - Options to control how the code is transformed
79
 * @returns A promise that resolves to the transformed code
80
 */
81
function transformModule(code: string, options?: EvaluateOptions): Promise<string>;
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
import { transformModule } from "mlly";
88

89
// Transform JSON to module
90
const jsonModule = await transformModule('{"name": "test"}', {
91
  url: "file:///project/data.json"
92
});
93
console.log(jsonModule); // "export default {"name": "test"}"
94

95
// Transform import.meta.url references
96
const transformed = await transformModule(
97
  `console.log(import.meta.url)`,
98
  { url: "file:///project/module.mjs" }
99
);
100
console.log(transformed); // `console.log('file:///project/module.mjs')`
101
```
102

103
### Resolve Imports
104

105
Resolves all import URLs found within the provided code to their absolute URLs, based on the given options.
106

107
```typescript { .api }
108
/**
109
 * Resolves all import URLs found within the provided code to their absolute URLs, based on the given options
110
 * @param code - The code containing the import directives to resolve
111
 * @param options - Options to use for resolving imports
112
 * @returns A promise that resolves to the code, replacing import URLs with resolved URLs
113
 */
114
function resolveImports(code: string, options?: EvaluateOptions): Promise<string>;
115
```
116

117
**Usage Example:**
118

119
```typescript
120
import { resolveImports } from "mlly";
121

122
const code = `
123
import foo from './utils.mjs';
124
import { bar } from '../config.json';
125
export const baz = await import('./dynamic.mjs');
126
`;
127

128
const resolved = await resolveImports(code, { url: import.meta.url });
129
// All relative imports are resolved to absolute file:// URLs
130
```
131

132
## Types
133

134
```typescript { .api }
135
interface EvaluateOptions extends ResolveOptions {
136
  /** The URL of the module, which can be specified to override the URL resolved from the module identifier */
137
  url?: string;
138
}
139
```
140

141
## Key Features
142

143
### Automatic Import Resolution
144

145
The module evaluation system automatically resolves relative imports to absolute URLs before evaluation:
146

147
- Relative imports like `./module.mjs` are resolved based on the `url` option
148
- JSON files are automatically transformed to export default modules
149
- Import resolution respects the same options as the resolve functions
150

151
### Stack Trace Preservation
152

153
When modules are evaluated using data URLs, stack traces are rewritten to show the original module URL instead of the data URL, making debugging easier.
154

155
### JSON Module Support
156

157
JSON files are automatically detected by extension and transformed into ES modules that export the JSON data as the default export:
158

159
```typescript
160
// Original JSON file content: {"name": "test", "version": "1.0.0"}
161
// Transformed to: export default {"name": "test", "version": "1.0.0"}
162
```
163

164
### Import.meta.url Rewriting
165

166
The `import.meta.url` references in the code are automatically replaced with the actual module URL provided in options, ensuring proper context for module evaluation.