0
# URL Manipulation
1

2
Low-level URL manipulation utilities for modifying URL record objects and handling URL component validation. These functions operate directly on URL records and follow the WHATWG URL specification algorithms.
3

4
## Capabilities
5

6
### setTheUsername
7

8
Sets the username component of a URL record according to the WHATWG specification.
9

10
```javascript { .api }
11
/**
12
 * Set the username on a URL record
13
 * @param {URLRecord} urlRecord - URL record to modify
14
 * @param {string} usernameString - Username to set
15
 */
16
function setTheUsername(urlRecord, usernameString)
17
```
18

19
### setThePassword
20

21
Sets the password component of a URL record according to the WHATWG specification.
22

23
```javascript { .api }
24
/**
25
 * Set the password on a URL record
26
 * @param {URLRecord} urlRecord - URL record to modify
27
 * @param {string} passwordString - Password to set
28
 */
29
function setThePassword(urlRecord, passwordString)
30
```
31

32
**Usage Examples:**
33

34
```javascript
35
const { parseURL, setTheUsername, setThePassword, serializeURL } = require("whatwg-url");
36

37
// Parse a URL
38
const url = parseURL("https://example.com/path");
39

40
// Set username and password
41
setTheUsername(url, "user123");
42
setThePassword(url, "secret");
43

44
console.log(serializeURL(url)); 
45
// "https://user123:secret@example.com/path"
46

47
// Modify existing credentials
48
const urlWithAuth = parseURL("https://olduser:oldpass@example.com/");
49
setTheUsername(urlWithAuth, "newuser");
50
setThePassword(urlWithAuth, "newpass");
51

52
console.log(serializeURL(urlWithAuth)); 
53
// "https://newuser:newpass@example.com/"
54
```
55

56
### cannotHaveAUsernamePasswordPort
57

58
Determines whether a URL record can have username, password, or port components based on its scheme and host.
59

60
```javascript { .api }
61
/**
62
 * Check if URL cannot have username, password, or port
63
 * @param {URLRecord} urlRecord - URL record to check
64
 * @returns {boolean} True if URL cannot have username/password/port
65
 */
66
function cannotHaveAUsernamePasswordPort(urlRecord)
67
```
68

69
**Returns `true` for:**
70
- URLs with null host (like `file:` URLs)
71
- URLs with empty host
72
- Certain special schemes that don't support authentication
73

74
**Usage Examples:**
75

76
```javascript
77
const { parseURL, cannotHaveAUsernamePasswordPort } = require("whatwg-url");
78

79
// File URL cannot have credentials
80
const fileUrl = parseURL("file:///path/to/file.txt");
81
console.log(cannotHaveAUsernamePasswordPort(fileUrl)); // true
82

83
// HTTP URL can have credentials
84
const httpUrl = parseURL("https://example.com/");
85
console.log(cannotHaveAUsernamePasswordPort(httpUrl)); // false
86

87
// Data URL cannot have credentials  
88
const dataUrl = parseURL("data:text/plain,Hello");
89
console.log(cannotHaveAUsernamePasswordPort(dataUrl)); // true
90
```
91

92
### hasAnOpaquePath
93

94
Determines whether a URL record has an opaque path (string) rather than a structured path (array).
95

96
```javascript { .api }
97
/**
98
 * Check if URL has an opaque path
99
 * @param {URLRecord} urlRecord - URL record to check
100
 * @returns {boolean} True if URL has opaque path (string), false if structured path (array)
101
 */
102
function hasAnOpaquePath(urlRecord)
103
```
104

105
**Opaque paths are used for:**
106
- Non-special URLs (schemes not in the special schemes list)
107
- URLs like `data:`, `mailto:`, `javascript:`, etc.
108
- URLs where the path cannot be structured into segments
109

110
**Usage Examples:**
111

112
```javascript
113
const { parseURL, hasAnOpaquePath } = require("whatwg-url");
114

115
// HTTP URL has structured path (array)
116
const httpUrl = parseURL("https://example.com/api/users");
117
console.log(hasAnOpaquePath(httpUrl)); // false
118
console.log(httpUrl.path); // ["", "api", "users"]
119

120
// Data URL has opaque path (string)
121
const dataUrl = parseURL("data:text/plain;base64,SGVsbG8=");
122
console.log(hasAnOpaquePath(dataUrl)); // true
123
console.log(dataUrl.path); // "text/plain;base64,SGVsbG8="
124

125
// Mailto URL has opaque path (string)
126
const mailtoUrl = parseURL("mailto:user@example.com");
127
console.log(hasAnOpaquePath(mailtoUrl)); // true
128
console.log(mailtoUrl.path); // "user@example.com"
129

130
// Custom scheme URL has opaque path
131
const customUrl = parseURL("myscheme:some-opaque-data");
132
console.log(hasAnOpaquePath(customUrl)); // true
133
console.log(customUrl.path); // "some-opaque-data"
134
```
135

136
## Advanced Usage Patterns
137

138
### Safe URL Modification
139

140
Always check URL constraints before attempting modifications:
141

142
```javascript
143
const { 
144
  parseURL, 
145
  setTheUsername, 
146
  setThePassword, 
147
  cannotHaveAUsernamePasswordPort,
148
  serializeURL 
149
} = require("whatwg-url");
150

151
function safeSetCredentials(urlString, username, password) {
152
  const url = parseURL(urlString);
153
  if (!url) {
154
    throw new Error("Invalid URL");
155
  }
156
  
157
  if (cannotHaveAUsernamePasswordPort(url)) {
158
    throw new Error("URL cannot have username/password");
159
  }
160
  
161
  setTheUsername(url, username);
162
  setThePassword(url, password);
163
  
164
  return serializeURL(url);
165
}
166

167
// Safe usage
168
try {
169
  const result = safeSetCredentials("https://example.com/", "user", "pass");
170
  console.log(result); // "https://user:pass@example.com/"
171
} catch (error) {
172
  console.error(error.message);
173
}
174

175
// Will throw error
176
try {
177
  safeSetCredentials("file:///path/file.txt", "user", "pass");
178
} catch (error) {
179
  console.error(error.message); // "URL cannot have username/password"
180
}
181
```
182

183
### Path Type Detection
184

185
Handle different path types appropriately:
186

187
```javascript
188
const { parseURL, hasAnOpaquePath, serializePath } = require("whatwg-url");
189

190
function analyzePath(urlString) {
191
  const url = parseURL(urlString);
192
  if (!url) return null;
193
  
194
  if (hasAnOpaquePath(url)) {
195
    return {
196
      type: "opaque",
197
      path: url.path, // string
198
      segments: null
199
    };
200
  } else {
201
    return {
202
      type: "structured", 
203
      path: serializePath(url), // serialized string
204
      segments: url.path // array
205
    };
206
  }
207
}
208

209
console.log(analyzePath("https://example.com/api/users"));
210
// { type: "structured", path: "/api/users", segments: ["", "api", "users"] }
211

212
console.log(analyzePath("data:text/plain,Hello"));
213
// { type: "opaque", path: "text/plain,Hello", segments: null }
214
```