0
# URL Class
1

2
The URL class provides a web-compatible interface for parsing, manipulating, and serializing URLs according to the WHATWG URL Standard.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new URL instance from a URL string with optional base URL.
9

10
```javascript { .api }
11
/**
12
 * Creates a new URL instance
13
 * @param {string} url - The URL string to parse
14
 * @param {string} [base] - Optional base URL for relative URLs
15
 * @throws {TypeError} If url is invalid or base is provided but invalid
16
 */
17
constructor(url, base)
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const { URL } = require("whatwg-url");
24

25
// Absolute URL
26
const url1 = new URL("https://example.com/path");
27

28
// Relative URL with base
29
const url2 = new URL("/api/users", "https://example.com");
30
console.log(url2.href); // "https://example.com/api/users"
31

32
// Relative URL with another URL as base
33
const base = new URL("https://example.com/api/");
34
const url3 = new URL("users", base);
35
console.log(url3.href); // "https://example.com/api/users"
36
```
37

38
### Static Methods
39

40
#### parse
41

42
Parses a URL string and returns a URL instance or null if invalid.
43

44
```javascript { .api }
45
/**
46
 * Parse a URL string without throwing on invalid input
47
 * @param {string} url - The URL string to parse
48
 * @param {string} [base] - Optional base URL for relative URLs
49
 * @returns {URL|null} URL instance or null if parsing fails
50
 */
51
static parse(url, base)
52
```
53

54
#### canParse
55

56
Tests whether a URL string can be successfully parsed.
57

58
```javascript { .api }
59
/**
60
 * Test if a URL can be parsed successfully
61
 * @param {string} url - The URL string to test
62
 * @param {string} [base] - Optional base URL for relative URLs
63
 * @returns {boolean} True if URL can be parsed, false otherwise
64
 */
65
static canParse(url, base)
66
```
67

68
**Usage Examples:**
69

70
```javascript
71
// Safe parsing without exceptions
72
const url = URL.parse("https://example.com/path");
73
if (url) {
74
  console.log(url.hostname); // "example.com"
75
}
76

77
// Quick validation
78
if (URL.canParse("https://example.com")) {
79
  console.log("Valid URL");
80
}
81

82
// With base URL
83
const relativeUrl = URL.parse("/api", "https://example.com");
84
console.log(relativeUrl?.href); // "https://example.com/api"
85
```
86

87
### Properties
88

89
#### href
90

91
The complete URL string. Setting this property re-parses the entire URL.
92

93
```javascript { .api }
94
/**
95
 * Complete URL string (getter/setter)
96
 * @type {string}
97
 * @throws {TypeError} When setting to an invalid URL
98
 */
99
href
100
```
101

102
#### origin
103

104
The origin of the URL (protocol + host + port). Read-only.
105

106
```javascript { .api }
107
/**
108
 * URL origin (readonly)
109
 * @type {string}
110
 */
111
origin
112
```
113

114
#### protocol
115

116
The protocol scheme including the trailing colon (e.g., "https:").
117

118
```javascript { .api }
119
/**
120
 * Protocol scheme with colon (getter/setter)
121
 * @type {string}
122
 */
123
protocol
124
```
125

126
#### username
127

128
The username portion of the URL.
129

130
```javascript { .api }
131
/**
132
 * Username portion (getter/setter)
133
 * @type {string}
134
 */
135
username
136
```
137

138
#### password
139

140
The password portion of the URL.
141

142
```javascript { .api }
143
/**
144
 * Password portion (getter/setter)
145
 * @type {string}
146
 */
147
password
148
```
149

150
#### host
151

152
The host including port if non-default (e.g., "example.com:8080").
153

154
```javascript { .api }
155
/**
156
 * Host with port (getter/setter)
157
 * @type {string}
158
 */
159
host
160
```
161

162
#### hostname
163

164
The hostname without port (e.g., "example.com").
165

166
```javascript { .api }
167
/**
168
 * Hostname without port (getter/setter)
169
 * @type {string}
170
 */
171
hostname
172
```
173

174
#### port
175

176
The port number as a string. Empty string for default ports.
177

178
```javascript { .api }
179
/**
180
 * Port number as string (getter/setter)
181
 * @type {string}
182
 */
183
port
184
```
185

186
#### pathname
187

188
The path portion of the URL including leading slash.
189

190
```javascript { .api }
191
/**
192
 * Path portion with leading slash (getter/setter)
193
 * @type {string}
194
 */
195
pathname
196
```
197

198
#### search
199

200
The query string including leading "?" or empty string if no query.
201

202
```javascript { .api }
203
/**
204
 * Query string with "?" (getter/setter)
205
 * @type {string}
206
 */
207
search
208
```
209

210
#### searchParams
211

212
URLSearchParams object for the query string. Read-only reference.
213

214
```javascript { .api }
215
/**
216
 * Query parameters object (readonly)
217
 * @type {URLSearchParams}
218
 */
219
searchParams
220
```
221

222
#### hash
223

224
The fragment including leading "#" or empty string if no fragment.
225

226
```javascript { .api }
227
/**
228
 * Fragment with "#" (getter/setter)
229
 * @type {string}
230
 */
231
hash
232
```
233

234
**Usage Examples:**
235

236
```javascript
237
const url = new URL("https://user:pass@example.com:8080/path?query=value#section");
238

239
console.log(url.href);       // "https://user:pass@example.com:8080/path?query=value#section"
240
console.log(url.origin);     // "https://example.com:8080"
241
console.log(url.protocol);   // "https:"
242
console.log(url.username);   // "user"
243
console.log(url.password);   // "pass"
244
console.log(url.host);       // "example.com:8080"
245
console.log(url.hostname);   // "example.com"
246
console.log(url.port);       // "8080"
247
console.log(url.pathname);   // "/path"
248
console.log(url.search);     // "?query=value"
249
console.log(url.hash);       // "#section"
250

251
// Modify components
252
url.pathname = "/new-path";
253
url.searchParams.set("newParam", "newValue");
254
console.log(url.href); // "https://user:pass@example.com:8080/new-path?query=value&newParam=newValue#section"
255
```
256

257
### Methods
258

259
#### toJSON
260

261
Returns the href string representation for JSON serialization.
262

263
```javascript { .api }
264
/**
265
 * Returns href string for JSON serialization
266
 * @returns {string} The href string
267
 */
268
toJSON()
269
```
270

271
**Usage Example:**
272

273
```javascript
274
const url = new URL("https://example.com/path");
275
console.log(JSON.stringify({ url })); // {"url":"https://example.com/path"}
276
console.log(url.toJSON()); // "https://example.com/path"
277
```