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
```