0
# URL Parse
1
2
URL Parse is a lightweight, high-performance URL parsing library that works seamlessly across Node.js and browser environments. It provides a pure string-based parsing algorithm with a minimal footprint, offering both Node.js-style `url.parse()` and modern `URL` constructor interfaces for maximum compatibility.
3
4
## Package Information
5
6
- **Package Name**: url-parse
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install url-parse`
10
11
## Core Imports
12
13
```javascript
14
var Url = require('url-parse');
15
```
16
17
ES6 modules (if supported by bundler):
18
```javascript
19
import Url from 'url-parse';
20
```
21
22
## Basic Usage
23
24
```javascript
25
var Url = require('url-parse');
26
27
// Parse a complete URL
28
var url = new Url('https://user:pass@github.com:443/foo/bar?hello=world#readme');
29
30
console.log(url.protocol); // 'https:'
31
console.log(url.hostname); // 'github.com'
32
console.log(url.pathname); // '/foo/bar'
33
console.log(url.query); // 'hello=world'
34
console.log(url.hash); // '#readme'
35
36
// Parse with query string parsing enabled
37
var urlWithQuery = new Url('https://example.com?name=john&age=30', null, true);
38
console.log(urlWithQuery.query); // { name: 'john', age: '30' }
39
40
// Parse relative URL with base URL
41
var relative = new Url('/api/users', 'https://example.com');
42
console.log(relative.href); // 'https://example.com/api/users'
43
44
// Node.js-style parsing
45
var parsed = Url('https://example.com/path?query=value', true);
46
```
47
48
## Architecture
49
50
URL Parse is built around several key components that enable efficient and accurate URL parsing:
51
52
- **Pure String Parsing**: Uses a custom string-based parsing algorithm instead of RegExp or DOM-based approaches for better performance and cross-environment compatibility
53
- **Rules-Based Processing**: Employs a parsing rules array that defines the order and method for extracting URL components (hash, query, pathname, auth, host, port, hostname)
54
- **Protocol Handling**: Special handling for different protocol schemes (file:, ftp:, http:, https:, ws:, wss:) with appropriate path and slash processing
55
- **Location Context**: Intelligent base URL resolution using browser location or custom location objects for relative URL parsing
56
- **Property Propagation**: The `set()` method ensures changes to one property automatically update related properties (e.g., changing hostname updates host)
57
- **Query Integration**: Seamless integration with querystringify for flexible query string parsing and stringification
58
59
The parsing process follows a systematic approach: protocol extraction, rules-based component parsing, authentication handling, hostname/port normalization, pathname resolution, and final href/origin computation.
60
61
## Capabilities
62
63
### URL Constructor
64
65
Creates a new URL instance by parsing the provided URL string.
66
67
```javascript { .api }
68
/**
69
* Parse URL and create URL instance
70
* @param address - URL string to parse (absolute or relative)
71
* @param location - Base URL for relative parsing or location defaults
72
* @param parser - Query string parser (boolean or function)
73
* @returns Url instance
74
*/
75
function Url(address, location, parser);
76
```
77
78
**Parameters:**
79
- `address` (String): URL string to parse (absolute or relative)
80
- `location` (Object|String, optional): Base URL for relative parsing. In browsers, defaults to `window.location`. Pass empty object `{}` for environment-independent parsing.
81
- `parser` (Boolean|Function, optional):
82
- `false` (default): Query string remains as string
83
- `true`: Parse query using built-in querystringify
84
- `Function`: Custom query string parser function
85
86
**Usage Examples:**
87
88
```javascript
89
// Basic parsing
90
var url = new Url('https://example.com/path');
91
92
// With query parsing
93
var url = new Url('https://example.com/path?a=1&b=2', null, true);
94
95
// Relative URL with base
96
var url = new Url('/api', 'https://example.com');
97
98
// Custom query parser
99
var url = new Url('https://example.com?data', null, customParser);
100
101
// Node.js style (without 'new')
102
var url = Url('https://example.com/path', true);
103
```
104
105
### URL Properties
106
107
All parsed URL components are available as instance properties:
108
109
```javascript { .api }
110
interface UrlInstance {
111
/** Protocol scheme including colon (e.g., 'http:') */
112
protocol: string;
113
/** Whether protocol is followed by '//' */
114
slashes: boolean;
115
/** Authentication info as 'username:password' */
116
auth: string;
117
/** Username portion of authentication */
118
username: string;
119
/** Password portion of authentication */
120
password: string;
121
/** Hostname with port number */
122
host: string;
123
/** Hostname without port number */
124
hostname: string;
125
/** Port number as string */
126
port: string;
127
/** URL path portion */
128
pathname: string;
129
/** Query string (string or parsed object based on parser) */
130
query: string | object;
131
/** Fragment portion including '#' */
132
hash: string;
133
/** Complete URL string */
134
href: string;
135
/** Origin (protocol + hostname + port) */
136
origin: string;
137
}
138
```
139
140
### Set Method
141
142
Modify URL properties with automatic propagation to related properties.
143
144
```javascript { .api }
145
/**
146
* Change URL properties with automatic updates to related properties
147
* @param part - Property name to set
148
* @param value - New value for the property
149
* @param fn - Additional options (parser for query, slash handling for protocol)
150
* @returns Url instance (for chaining)
151
*/
152
set(part, value, fn);
153
```
154
155
**Supported Properties:**
156
- `'protocol'`: Updates protocol, may affect slashes
157
- `'hostname'`: Updates hostname, propagates to host
158
- `'host'`: Updates both hostname and port
159
- `'port'`: Updates port, propagates to host, handles default ports
160
- `'pathname'`: Updates path portion
161
- `'query'`: Updates query string, can use custom parser
162
- `'hash'`: Updates fragment portion
163
- `'username'`: Updates username, propagates to auth
164
- `'password'`: Updates password, propagates to auth
165
- `'auth'`: Updates authentication, splits into username/password
166
167
**Usage Examples:**
168
169
```javascript
170
var url = new Url('http://example.com/path');
171
172
// Change hostname
173
url.set('hostname', 'newhost.com');
174
console.log(url.href); // 'http://newhost.com/path'
175
176
// Change port (automatically updates host)
177
url.set('port', '8080');
178
console.log(url.host); // 'newhost.com:8080'
179
180
// Change query with parsing
181
url.set('query', 'name=value&type=test', true);
182
console.log(url.query); // { name: 'value', type: 'test' }
183
184
// Method chaining
185
url.set('protocol', 'https:').set('pathname', '/api');
186
```
187
188
### ToString Method
189
190
Generate complete URL string from the instance properties.
191
192
```javascript { .api }
193
/**
194
* Generate complete URL string
195
* @param stringify - Custom query string stringify function
196
* @returns Complete URL as string
197
*/
198
toString(stringify);
199
```
200
201
**Usage Examples:**
202
203
```javascript
204
var url = new Url('https://example.com/path?name=value');
205
206
// Default stringification
207
var urlString = url.toString();
208
console.log(urlString); // 'https://example.com/path?name=value'
209
210
// Custom query stringifier
211
var customString = url.toString(customStringifyFunction);
212
213
// Also available as href property
214
console.log(url.href === url.toString()); // true
215
```
216
217
### Static Utility Methods
218
219
Additional utility methods available on the Url constructor:
220
221
```javascript { .api }
222
/**
223
* Extract protocol information from URL
224
* @param address - URL string to extract from
225
* @param location - Optional location defaults
226
* @returns Object with protocol, slashes, rest, and slashesCount properties
227
*/
228
Url.extractProtocol(address, location);
229
230
/**
231
* Generate location object for URL parsing
232
* @param loc - Default location object
233
* @returns Location object with URL properties
234
*/
235
Url.location(loc);
236
237
/**
238
* Remove control characters and whitespace from string beginning
239
* @param str - String to trim
240
* @returns Trimmed string
241
*/
242
Url.trimLeft(str);
243
244
/**
245
* Reference to querystringify module for query operations
246
*/
247
Url.qs;
248
```
249
250
**Usage Examples:**
251
252
```javascript
253
// Extract protocol info
254
var protocolInfo = Url.extractProtocol('https://example.com/path');
255
console.log(protocolInfo.protocol); // 'https:'
256
console.log(protocolInfo.slashes); // true
257
console.log(protocolInfo.rest); // 'example.com/path'
258
console.log(protocolInfo.slashesCount); // 2
259
260
// Trim whitespace
261
var clean = Url.trimLeft(' \t\n hello world');
262
console.log(clean); // 'hello world'
263
264
// Access query string utilities
265
var queryString = Url.qs.stringify({ name: 'value', type: 'test' });
266
var queryObject = Url.qs.parse('name=value&type=test');
267
```
268
269
## Error Handling
270
271
URL Parse handles malformed URLs gracefully by:
272
- Defaulting missing components to empty strings
273
- Preserving invalid hostnames and ports for inspection
274
- Handling special protocols (file:, ftp:, http:, https:, ws:, wss:) appropriately
275
- Supporting both absolute and relative URL parsing
276
277
For robust error handling, validate critical properties after parsing:
278
279
```javascript
280
var url = new Url(userInput);
281
282
// Validate hostname exists
283
if (!url.hostname) {
284
throw new Error('Invalid URL: missing hostname');
285
}
286
287
// Validate protocol is expected
288
if (!['http:', 'https:'].includes(url.protocol)) {
289
throw new Error('Invalid protocol: ' + url.protocol);
290
}
291
```
292
293
## Browser vs Node.js Differences
294
295
- **Browser**: Defaults to `window.location` as base URL for relative URLs
296
- **Node.js**: No default base URL, relative URLs parse with empty location
297
- **Environment-independent parsing**: Pass empty object `{}` as second parameter
298
299
```javascript
300
// Browser-dependent (uses window.location in browser)
301
var url = new Url('/api/users');
302
303
// Environment-independent
304
var url = new Url('/api/users', {});
305
```