0
# WHATWG URL
1
2
WHATWG URL is a comprehensive implementation of the WHATWG URL Standard, providing both high-level URL and URLSearchParams classes for standard web compatibility, and low-level URL parsing and manipulation APIs for advanced use cases like browser engine development.
3
4
## Package Information
5
6
- **Package Name**: whatwg-url
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install whatwg-url`
10
11
## Core Imports
12
13
```javascript
14
const { URL, URLSearchParams } = require("whatwg-url");
15
```
16
17
For advanced URL parsing:
18
19
```javascript
20
const {
21
parseURL,
22
basicURLParse,
23
serializeURL,
24
percentDecodeString
25
} = require("whatwg-url");
26
```
27
28
For WebIDL wrapper interfaces:
29
30
```javascript
31
const { URL, URLSearchParams } = require("whatwg-url/webidl2js-wrapper");
32
```
33
34
## Basic Usage
35
36
```javascript
37
const { URL, URLSearchParams } = require("whatwg-url");
38
39
// Create and manipulate URLs
40
const url = new URL("https://example.com/path?query=value#fragment");
41
console.log(url.hostname); // "example.com"
42
console.log(url.pathname); // "/path"
43
44
// Modify URL components
45
url.pathname = "/new-path";
46
url.searchParams.set("newParam", "newValue");
47
console.log(url.href); // "https://example.com/new-path?query=value&newParam=newValue#fragment"
48
49
// Work with query parameters
50
const params = new URLSearchParams("?name=John&age=30");
51
params.append("city", "New York");
52
console.log(params.toString()); // "name=John&age=30&city=New+York"
53
54
// Low-level URL parsing
55
const parsed = parseURL("https://example.com/path", { baseURL: null });
56
if (parsed) {
57
console.log(parsed.scheme); // "https"
58
console.log(parsed.host); // "example.com"
59
}
60
```
61
62
## Architecture
63
64
WHATWG URL is built around several key components:
65
66
- **Standards Compliance**: Full implementation of the WHATWG URL Standard for maximum web compatibility
67
- **High-Level API**: `URL` and `URLSearchParams` classes matching browser APIs exactly
68
- **Low-Level API**: Internal URL parsing functions and utilities for building URL-aware applications
69
- **WebIDL Integration**: Generated interfaces using webidl2js for precise specification compliance
70
- **Error Handling**: Proper error handling with TypeError exceptions for invalid inputs
71
72
## Capabilities
73
74
### URL Class
75
76
Standard web-compatible URL class for parsing, manipulating, and serializing URLs with full property access and modification support.
77
78
```javascript { .api }
79
class URL {
80
constructor(url, base);
81
static parse(url, base);
82
static canParse(url, base);
83
84
href; // string getter/setter
85
origin; // string readonly
86
protocol; // string getter/setter
87
username; // string getter/setter
88
password; // string getter/setter
89
host; // string getter/setter
90
hostname; // string getter/setter
91
port; // string getter/setter
92
pathname; // string getter/setter
93
search; // string getter/setter
94
searchParams; // URLSearchParams readonly
95
hash; // string getter/setter
96
97
toJSON();
98
}
99
```
100
101
[URL Class](./url-class.md)
102
103
### URLSearchParams Class
104
105
Query string parameter manipulation with full iteration support and standard web API compatibility.
106
107
```javascript { .api }
108
class URLSearchParams {
109
constructor(init);
110
111
size; // number readonly
112
113
append(name, value);
114
delete(name, value);
115
get(name);
116
getAll(name);
117
has(name, value);
118
set(name, value);
119
sort();
120
toString();
121
[Symbol.iterator]();
122
}
123
```
124
125
[URLSearchParams Class](./url-search-params.md)
126
127
### URL Parsing
128
129
Low-level URL parsing functions following the WHATWG specification for building URL-aware applications and browser engines.
130
131
```javascript { .api }
132
function parseURL(input, options);
133
function basicURLParse(input, options);
134
function serializeURL(urlRecord, excludeFragment);
135
function serializePath(urlRecord);
136
function serializeHost(hostFromURLRecord);
137
function serializeURLOrigin(urlRecord);
138
function serializeInteger(integer);
139
```
140
141
[URL Parsing](./url-parsing.md)
142
143
### URL Manipulation
144
145
Low-level URL manipulation utilities for modifying URL record objects and handling URL components.
146
147
```javascript { .api }
148
function setTheUsername(urlRecord, usernameString);
149
function setThePassword(urlRecord, passwordString);
150
function cannotHaveAUsernamePasswordPort(urlRecord);
151
function hasAnOpaquePath(urlRecord);
152
```
153
154
[URL Manipulation](./url-manipulation.md)
155
156
### Percent Encoding
157
158
Percent encoding and decoding utilities for handling URL-encoded strings and byte sequences.
159
160
```javascript { .api }
161
function percentDecodeString(string);
162
function percentDecodeBytes(uint8Array);
163
```
164
165
[Percent Encoding](./percent-encoding.md)
166
167
## Types
168
169
```javascript { .api }
170
/**
171
* URL record object returned by parsing functions
172
*/
173
interface URLRecord {
174
scheme: string;
175
username: string;
176
password: string;
177
host: string | null;
178
port: number | null;
179
path: string[] | string; // array for normal URLs, string for opaque paths
180
query: string | null;
181
fragment: string | null;
182
}
183
184
/**
185
* Options for URL parsing functions
186
*/
187
interface ParseOptions {
188
baseURL?: URLRecord | null;
189
url?: URLRecord; // for basicURLParse only
190
stateOverride?: string; // for basicURLParse only
191
}
192
193
/**
194
* State override values for basicURLParse
195
*/
196
type StateOverride =
197
| "scheme start" | "scheme" | "no scheme"
198
| "special relative or authority" | "path or authority" | "relative"
199
| "relative slash" | "special authority slashes" | "special authority ignore slashes"
200
| "authority" | "host" | "hostname" | "port"
201
| "file" | "file slash" | "file host"
202
| "path start" | "path" | "opaque path"
203
| "query" | "fragment";
204
```