0
# Module Resolution
1

2
ESM-compliant module resolution with support for custom conditions, extensions, and multiple search paths. Handles Node.js built-ins, file system paths, and various URL protocols following the ECMAScript Resolver algorithm.
3

4
## Capabilities
5

6
### Resolve Function
7

8
Asynchronously resolves a module path based on the given options.
9

10
```typescript { .api }
11
/**
12
 * Asynchronously resolves a module path based on the given options
13
 * @param id - The identifier or path of the module to resolve
14
 * @param options - Options for resolving the module
15
 * @returns A promise to resolve the URL as a string
16
 */
17
function resolve(id: string, options?: ResolveOptions): Promise<string>;
18
```
19

20
**Usage Examples:**
21

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

25
// Resolve relative module
26
const url = await resolve("./utils.mjs", { url: import.meta.url });
27
// Result: "file:///path/to/project/utils.mjs"
28

29
// Resolve npm package  
30
const lodashUrl = await resolve("lodash", { url: import.meta.url });
31

32
// Resolve with custom conditions
33
const devUrl = await resolve("my-package", { 
34
  conditions: ["development", "import", "node"] 
35
});
36
```
37

38
### Resolve Sync Function
39

40
Synchronously resolves a module path based on the options provided.
41

42
```typescript { .api }
43
/**
44
 * Synchronously resolves a module path based on the options provided
45
 * @param id - The identifier or path of the module to resolve
46
 * @param options - Options to resolve the module
47
 * @returns The resolved URL as a string
48
 */
49
function resolveSync(id: string, options?: ResolveOptions): string;
50
```
51

52
### Resolve Path Function
53

54
Asynchronously resolves a module path to a local file path based on the options provided.
55

56
```typescript { .api }
57
/**
58
 * Asynchronously resolves a module path to a local file path based on the options provided
59
 * @param id - The identifier or path of the module to resolve
60
 * @param options - Options for resolving the module
61
 * @returns A promise to resolve to the file path
62
 */
63
function resolvePath(id: string, options?: ResolveOptions): Promise<string>;
64
```
65

66
### Resolve Path Sync Function
67

68
Synchronously resolves a module path to a local file path based on the given options.
69

70
```typescript { .api }
71
/**
72
 * Synchronously resolves a module path to a local file path based on the given options
73
 * @param id - The identifier or path of the module to resolve
74
 * @param options - Options to resolve the module
75
 * @returns The resolved file path
76
 */
77
function resolvePathSync(id: string, options?: ResolveOptions): string;
78
```
79

80
### Create Resolve Function
81

82
Creates a resolver function with default options that can be used to resolve module identifiers.
83

84
```typescript { .api }
85
/**
86
 * Creates a resolver function with default options that can be used to resolve module identifiers
87
 * @param defaults - Default options to use for all resolutions
88
 * @returns A resolver function that takes an identifier and an optional URL, and resolves the identifier using the default options and the given URL
89
 */
90
function createResolve(defaults?: ResolveOptions): (id: string, url?: ResolveOptions["url"]) => Promise<string>;
91
```
92

93
**Usage Example:**
94

95
```typescript
96
import { createResolve } from "mlly";
97

98
// Create resolver with defaults
99
const resolver = createResolve({ url: import.meta.url });
100

101
// Use resolver
102
const moduleUrl = await resolver("./config.mjs");
103
```
104

105
### Parse Node Module Path Function
106

107
Parses a node module path to extract the directory, name, and subpath.
108

109
```typescript { .api }
110
/**
111
 * Parses a node module path to extract the directory, name, and subpath
112
 * @param path - The path to parse
113
 * @returns An object containing the directory, module name, and subpath of the node module
114
 */
115
function parseNodeModulePath(path: string): {
116
  dir?: string;
117
  name?: string;
118
  subpath?: string;
119
};
120
```
121

122
**Usage Example:**
123

124
```typescript
125
import { parseNodeModulePath } from "mlly";
126

127
const result = parseNodeModulePath("/project/node_modules/lodash/dist/lodash.js");
128
// Result: { dir: "/project/node_modules/", name: "lodash", subpath: "./dist/lodash.js" }
129
```
130

131
### Lookup Node Module Subpath Function
132

133
Attempts to reverse engineer a subpath export within a node module.
134

135
```typescript { .api }
136
/**
137
 * Attempts to reverse engineer a subpath export within a node module
138
 * @param path - The path within the node module
139
 * @returns A promise that resolves to the detected subpath or undefined if not found
140
 */
141
function lookupNodeModuleSubpath(path: string): Promise<string | undefined>;
142
```
143

144
## Types
145

146
```typescript { .api }
147
interface ResolveOptions {
148
  /** A URL, path or array of URLs/paths to resolve against */
149
  url?: string | URL | (string | URL)[];
150
  /** File extensions to consider when resolving modules */
151
  extensions?: string[];
152
  /** Conditions to consider when resolving package exports */
153
  conditions?: string[];
154
}
155
```