0
# Utility Functions
1

2
Core utilities for path/URL conversion, protocol handling, URI sanitization, and Node.js built-in detection. Provides cross-platform file system path normalization and safe URL handling.
3

4
## Capabilities
5

6
### File URL to Path
7

8
Converts a file URL to a local file system path with normalized slashes.
9

10
```typescript { .api }
11
/**
12
 * Converts a file URL to a local file system path with normalized slashes
13
 * @param id - The file URL or local path to convert
14
 * @returns A normalized file system path
15
 */
16
function fileURLToPath(id: string | URL): string;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { fileURLToPath } from "mlly";
23

24
// Convert file URL to path
25
console.log(fileURLToPath("file:///foo/bar.js")); // "/foo/bar.js"
26

27
// Handles Windows paths
28
console.log(fileURLToPath("file:///C:/path/")); // "C:/path"
29

30
// Pass through regular paths
31
console.log(fileURLToPath("/already/a/path")); // "/already/a/path"
32
```
33

34
### Path to File URL
35

36
Converts a local file system path to a file URL.
37

38
```typescript { .api }
39
/**
40
 * Converts a local file system path to a file URL
41
 * @param id - The file system path to convert
42
 * @returns The resulting file URL as a string
43
 */
44
function pathToFileURL(id: string | URL): string;
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { pathToFileURL } from "mlly";
51

52
// Convert path to file URL
53
console.log(pathToFileURL("/foo/bar.js")); // "file:///foo/bar.js"
54

55
// Handles Windows paths
56
console.log(pathToFileURL("C:\\path\\file.js")); // "file:///C:/path/file.js"
57
```
58

59
### Sanitize URI Component
60

61
Sanitises a component of a URI by replacing invalid characters.
62

63
```typescript { .api }
64
/**
65
 * Sanitises a component of a URI by replacing invalid characters
66
 * @param name - The URI component to sanitise
67
 * @param replacement - The string to replace invalid characters with
68
 * @returns The sanitised URI component
69
 */
70
function sanitizeURIComponent(name?: string, replacement?: string): string;
71
```
72

73
**Usage Example:**
74

75
```typescript
76
import { sanitizeURIComponent } from "mlly";
77

78
// Replace invalid URI characters
79
console.log(sanitizeURIComponent("foo:bar")); // "foo_bar"
80
console.log(sanitizeURIComponent("hello world", "-")); // "hello-world"
81
```
82

83
### Sanitize File Path
84

85
Cleans a file path string by sanitising each component of the path.
86

87
```typescript { .api }
88
/**
89
 * Cleans a file path string by sanitising each component of the path
90
 * @param filePath - The file path to sanitise
91
 * @returns The sanitised file path
92
 */
93
function sanitizeFilePath(filePath?: string): string;
94
```
95

96
**Usage Example:**
97

98
```typescript
99
import { sanitizeFilePath } from "mlly";
100

101
// Sanitize problematic file path
102
console.log(sanitizeFilePath("C:\\te#st\\[...slug].jsx"));
103
// Result: "C:/te_st/_...slug_.jsx"
104
```
105

106
### Normalize ID
107

108
Normalises a module identifier to ensure it has a protocol if missing, handling built-in modules and file paths.
109

110
```typescript { .api }
111
/**
112
 * Normalises a module identifier to ensure it has a protocol if missing, handling built-in modules and file paths
113
 * @param id - The identifier to normalise
114
 * @returns The normalised identifier with the appropriate protocol
115
 */
116
function normalizeid(id: string): string;
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
import { normalizeid } from "mlly";
123

124
// Add file protocol to paths
125
console.log(normalizeid("/foo/bar.js")); // "file:///foo/bar.js"
126

127
// Handle built-in modules
128
console.log(normalizeid("fs")); // "node:fs"
129

130
// Pass through existing protocols
131
console.log(normalizeid("https://example.com")); // "https://example.com"
132
```
133

134
### Load URL
135

136
Loads the contents of a file from a URL into a string.
137

138
```typescript { .api }
139
/**
140
 * Loads the contents of a file from a URL into a string
141
 * @param url - The URL of the file to load
142
 * @returns A promise that resolves to the content of the file
143
 */
144
function loadURL(url: string): Promise<string>;
145
```
146

147
**Usage Example:**
148

149
```typescript
150
import { loadURL, resolve } from "mlly";
151

152
// Load file contents
153
const url = await resolve("./config.json", { url: import.meta.url });
154
const content = await loadURL(url);
155
console.log(JSON.parse(content));
156
```
157

158
### To Data URL
159

160
Converts a string of code into a data URL that can be used for dynamic imports.
161

162
```typescript { .api }
163
/**
164
 * Converts a string of code into a data URL that can be used for dynamic imports
165
 * @param code - The string of code to convert
166
 * @returns The data URL containing the encoded code
167
 */
168
function toDataURL(code: string): string;
169
```
170

171
**Usage Example:**
172

173
```typescript
174
import { toDataURL } from "mlly";
175

176
// Convert code to data URL
177
const code = `export const greeting = "Hello World!";`;
178
const dataUrl = toDataURL(code);
179

180
// Use with dynamic import
181
const module = await import(dataUrl);
182
console.log(module.greeting); // "Hello World!"
183
```
184

185
### Is Node Builtin
186

187
Checks if a module identifier matches a Node.js built-in module.
188

189
```typescript { .api }
190
/**
191
 * Checks if a module identifier matches a Node.js built-in module
192
 * @param id - The identifier to check
193
 * @returns `true` if the identifier is a built-in module, otherwise `false`
194
 */
195
function isNodeBuiltin(id?: string): boolean;
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
import { isNodeBuiltin } from "mlly";
202

203
console.log(isNodeBuiltin("fs")); // true
204
console.log(isNodeBuiltin("node:path")); // true
205
console.log(isNodeBuiltin("fs/promises")); // true
206
console.log(isNodeBuiltin("lodash")); // false
207
```
208

209
### Get Protocol
210

211
Extracts the protocol portion of a given identifier string.
212

213
```typescript { .api }
214
/**
215
 * Extracts the protocol portion of a given identifier string
216
 * @param id - The identifier from which to extract the protocol
217
 * @returns The protocol part of the identifier, or undefined if no protocol is present
218
 */
219
function getProtocol(id: string): string | undefined;
220
```
221

222
**Usage Examples:**
223

224
```typescript
225
import { getProtocol } from "mlly";
226

227
console.log(getProtocol("https://example.com")); // "https"
228
console.log(getProtocol("file:///path/to/file")); // "file"
229
console.log(getProtocol("node:fs")); // "node"
230
console.log(getProtocol("relative/path")); // undefined
231
```
232

233
## Key Features
234

235
### Cross-Platform Path Handling
236

237
All path utilities handle cross-platform differences:
238

239
- Normalizes Windows backslashes to forward slashes
240
- Properly handles Windows drive letters
241
- Ensures consistent path separators across platforms
242

243
### URI Safety
244

245
URI utilities follow RFC standards:
246

247
- `sanitizeURIComponent` follows RFC 2396 for valid URI characters
248
- Removes query strings and normalizes path components
249
- Handles special characters safely
250

251
### Protocol Detection
252

253
Smart protocol handling:
254

255
- Detects existing protocols and preserves them
256
- Adds appropriate protocols when missing
257
- Handles Node.js built-in module detection
258
- Supports data:, file:, http:, https:, and node: protocols
259

260
### Data URL Support
261

262
Data URL utilities enable dynamic module evaluation:
263

264
- Base64 encoding for JavaScript code
265
- Compatible with dynamic import() statements
266
- Proper MIME type handling for JavaScript modules