0
# URI Construction and Parsing
1

2
Core functionality for creating, parsing, and building URI instances with full component access and validation.
3

4
## Capabilities
5

6
### URI Constructor
7

8
Creates a new URI instance for manipulation, with optional base URI resolution.
9

10
```javascript { .api }
11
/**
12
 * URI constructor - can be called with or without 'new'
13
 * @param url - URI string to parse (defaults to current location in browser)
14
 * @param base - Base URI for resolving relative URLs
15
 * @returns URI instance for chaining operations
16
 */
17
function URI(url?: string, base?: string): URI;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
// Basic construction
24
const uri = new URI('http://example.com/path');
25
const uri2 = URI('http://example.com/path'); // 'new' is optional
26

27
// With base resolution
28
const relative = new URI('../other/path.html', 'http://example.com/current/page.html');
29
console.log(relative.toString()); // 'http://example.com/other/path.html'
30

31
// Current location (browser only)
32
const current = new URI(); // Uses window.location.href
33
```
34

35
### Static Parsing Methods
36

37
Low-level parsing functions that break URI strings into component objects.
38

39
```javascript { .api }
40
/**
41
 * Parse URI string into components object
42
 * @param string - URI string to parse
43
 * @param parts - Optional existing parts object to populate
44
 * @returns Object with URI components (protocol, hostname, port, etc.)
45
 */
46
URI.parse(string: string, parts?: object): ParsedURI;
47

48
/**
49
 * Parse hostname portion of URI
50
 * @param string - Hostname string potentially containing port
51
 * @param parts - Parts object to populate
52
 * @returns Parts object with hostname and port
53
 */
54
URI.parseHost(string: string, parts: object): object;
55

56
/**
57
 * Parse authority portion (userinfo + host)
58
 * @param string - Authority string
59
 * @param parts - Parts object to populate
60
 * @returns Parts object with userinfo and host components
61
 */
62
URI.parseAuthority(string: string, parts: object): object;
63

64
/**
65
 * Parse userinfo portion (username:password)
66
 * @param string - Userinfo string
67
 * @param parts - Parts object to populate
68
 * @returns Parts object with username and password
69
 */
70
URI.parseUserinfo(string: string, parts: object): object;
71

72
/**
73
 * Parse query string into object representation
74
 * @param string - Query string (without leading ?)
75
 * @param escapeQuerySpace - Whether to treat + as space
76
 * @returns Object representing query parameters
77
 */
78
URI.parseQuery(string: string, escapeQuerySpace?: boolean): object;
79

80
interface ParsedURI {
81
  protocol?: string;
82
  username?: string;
83
  password?: string;
84
  hostname?: string;
85
  port?: string;
86
  pathname?: string;
87
  query?: string;
88
  fragment?: string;
89
}
90
```
91

92
**Usage Examples:**
93

94
```javascript
95
// Parse complete URI
96
const parts = URI.parse('http://user:pass@example.com:8080/path?query=value#fragment');
97
console.log(parts);
98
// {
99
//   protocol: 'http',
100
//   username: 'user',
101
//   password: 'pass',
102
//   hostname: 'example.com',
103
//   port: '8080',
104
//   pathname: '/path',
105
//   query: 'query=value',
106
//   fragment: 'fragment'
107
// }
108

109
// Parse query string
110
const queryObj = URI.parseQuery('name=John&age=30&tags=js&tags=web');
111
console.log(queryObj);
112
// { name: 'John', age: '30', tags: ['js', 'web'] }
113
```
114

115
### Static Building Methods
116

117
Functions to construct URI strings from component objects.
118

119
```javascript { .api }
120
/**
121
 * Build URI string from parts object
122
 * @param parts - Parts object with URI components
123
 * @returns Complete URI string
124
 */
125
URI.build(parts: object): string;
126

127
/**
128
 * Build host string from parts (hostname + port)
129
 * @param parts - Parts object with hostname and port
130
 * @returns Host string
131
 */
132
URI.buildHost(parts: object): string;
133

134
/**
135
 * Build authority string from parts (userinfo + host)
136
 * @param parts - Parts object with userinfo and host components
137
 * @returns Authority string
138
 */
139
URI.buildAuthority(parts: object): string;
140

141
/**
142
 * Build userinfo string from parts (username:password)
143
 * @param parts - Parts object with username and password
144
 * @returns Userinfo string
145
 */
146
URI.buildUserinfo(parts: object): string;
147

148
/**
149
 * Build query string from data object
150
 * @param data - Object or string to convert to query string
151
 * @param duplicateQueryParameters - Allow duplicate parameter names
152
 * @param escapeQuerySpace - Escape spaces as + instead of %20
153
 * @returns Query string (without leading ?)
154
 */
155
URI.buildQuery(data: object | string, duplicateQueryParameters?: boolean, escapeQuerySpace?: boolean): string;
156
```
157

158
**Usage Examples:**
159

160
```javascript
161
// Build from parts
162
const uriString = URI.build({
163
  protocol: 'https',
164
  hostname: 'api.example.com',
165
  port: '443',
166
  pathname: '/v1/users',
167
  query: 'limit=10&offset=0'
168
});
169
console.log(uriString); // 'https://api.example.com:443/v1/users?limit=10&offset=0'
170

171
// Build query string
172
const queryString = URI.buildQuery({
173
  search: 'javascript',
174
  category: 'programming',
175
  tags: ['web', 'frontend']
176
});
177
console.log(queryString); // 'search=javascript&category=programming&tags=web&tags=frontend'
178
```
179

180
### Instance Methods
181

182
Core instance methods for URI manipulation and output.
183

184
```javascript { .api }
185
/**
186
 * Get or set the complete URI
187
 * @param href - New URI string to set
188
 * @param build - Whether to rebuild URI immediately
189
 * @returns Current href string or URI instance for chaining
190
 */
191
href(href?: string, build?: boolean): string | URI;
192

193
/**
194
 * Build URI string from current parts
195
 * @param deferBuild - Don't trigger automatic rebuilding
196
 * @returns Complete URI string
197
 */
198
build(deferBuild?: boolean): string;
199

200
/**
201
 * Create a copy of this URI instance
202
 * @returns New URI instance with same components
203
 */
204
clone(): URI;
205

206
/**
207
 * Convert URI to string representation
208
 * @returns Complete URI string
209
 */
210
toString(): string;
211

212
/**
213
 * Get primitive value (same as toString)
214
 * @returns Complete URI string
215
 */
216
valueOf(): string;
217
```
218

219
**Usage Examples:**
220

221
```javascript
222
const uri = new URI('http://example.com/path');
223

224
// Get complete URI
225
console.log(uri.href()); // 'http://example.com/path'
226

227
// Set new URI
228
uri.href('https://newsite.com/newpath');
229
console.log(uri.toString()); // 'https://newsite.com/newpath'
230

231
// Clone URI
232
const copy = uri.clone();
233
copy.hostname('different.com');
234
console.log(uri.hostname()); // 'newsite.com' (original unchanged)
235
console.log(copy.hostname()); // 'different.com'
236
```
237

238
### URI Validation and Identification
239

240
Methods to check URI properties and validate components.
241

242
```javascript { .api }
243
/**
244
 * Check various URI properties
245
 * @param what - Property to check: 'relative', 'absolute', 'domain', 'sld', 'ip', 'ip4', 'ip6', 'idn', 'url', 'urn', 'punycode'
246
 * @returns Boolean indicating if URI has the specified property
247
 */
248
is(what: string): boolean;
249
```
250

251
**Usage Examples:**
252

253
```javascript
254
const uri1 = new URI('http://example.com/path');
255
const uri2 = new URI('../relative/path');
256
const uri3 = new URI('http://192.168.1.1/');
257

258
console.log(uri1.is('absolute')); // true
259
console.log(uri2.is('relative')); // true
260
console.log(uri3.is('ip')); // true
261
console.log(uri3.is('ip4')); // true
262

263
const domainUri = new URI('http://example.co.uk/');
264
console.log(domainUri.is('sld')); // true (has second-level domain)
265
```
266

267
### Static Configuration Properties
268

269
Global configuration properties that affect parsing and building behavior.
270

271
```javascript { .api }
272
// Version information
273
URI.version: string; // '1.19.11'
274

275
// Behavior configuration
276
URI.preventInvalidHostname: boolean; // Default: false
277
URI.duplicateQueryParameters: boolean; // Default: false  
278
URI.escapeQuerySpace: boolean; // Default: true
279

280
// Regular expressions for validation
281
URI.protocol_expression: RegExp;
282
URI.idn_expression: RegExp;
283
URI.punycode_expression: RegExp;
284
URI.ip4_expression: RegExp;
285
URI.ip6_expression: RegExp;
286
URI.find_uri_expression: RegExp;
287

288
// Default port mappings
289
URI.defaultPorts: {
290
  http: '80',
291
  https: '443',
292
  ftp: '21',
293
  gopher: '70',
294
  ws: '80',
295
  wss: '443'
296
};
297
```