0
# URI.js
1

2
URI.js is a comprehensive JavaScript library for working with URIs and URLs. It provides a chainable fluent API for parsing, manipulating, and building URIs with RFC 3986 compliance, supporting complex URI operations that would otherwise require verbose and error-prone string manipulation.
3

4
## Package Information
5

6
- **Package Name**: urijs
7
- **Package Type**: npm
8
- **Language**: JavaScript (UMD compatible)
9
- **Installation**: `npm install urijs`
10

11
## Core Imports
12

13
```javascript
14
// Node.js/CommonJS
15
const URI = require('urijs');
16

17
// ES6 Modules
18
import URI from 'urijs';
19

20
// Browser global
21
// <script src="URI.js"></script>
22
// URI is available as window.URI
23
```
24

25
## Basic Usage
26

27
```javascript
28
import URI from 'urijs';
29

30
// Create and manipulate URIs
31
const uri = new URI('http://user:pass@example.com:8080/path/to/file.html?query=value#fragment');
32

33
// Get/set components
34
console.log(uri.hostname()); // 'example.com'
35
console.log(uri.port()); // 8080
36
console.log(uri.pathname()); // '/path/to/file.html'
37

38
// Chain operations
39
const newUri = uri
40
  .hostname('newhost.com')
41
  .port(9000)
42
  .addQuery('param', 'value')
43
  .fragment('section');
44

45
console.log(newUri.toString()); // 'http://user:pass@newhost.com:9000/path/to/file.html?query=value&param=value#section'
46

47
// Parse and build URIs
48
const parsed = URI.parse('https://example.com/api/users?page=1');
49
console.log(parsed.hostname); // 'example.com'
50
console.log(parsed.query); // 'page=1'
51
```
52

53
## Architecture
54

55
URI.js is built around several key components:
56

57
- **Core URI Class**: Main constructor providing chainable instance methods for all URI components
58
- **Static Parser/Builder**: Low-level functions for parsing URI strings into parts and building them back
59
- **Encoding System**: Configurable encoding/decoding with support for different character sets
60
- **Extension Modules**: Optional modules for IPv6, Second Level Domains, URI Templates, and Punycode
61
- **Plugin Extensions**: Fragment query/URI extensions and jQuery integration
62
- **UMD Pattern**: Universal module support for Node.js, AMD, and browser environments
63

64
## Capabilities
65

66
### URI Construction and Parsing
67

68
Core functionality for creating, parsing, and building URI instances with full component access.
69

70
```javascript { .api }
71
// Constructor
72
function URI(url?: string, base?: string): URI;
73

74
// Static parsing and building
75
URI.parse(string: string, parts?: object): object;
76
URI.parseHost(string: string, parts?: object): object;
77
URI.parseAuthority(string: string, parts?: object): object;
78
URI.parseUserinfo(string: string, parts?: object): object;
79
URI.parseQuery(string: string, escapeQuerySpace?: boolean): object;
80
URI.build(parts: object): string;
81
URI.buildHost(parts: object): string;
82
URI.buildAuthority(parts: object): string;
83
URI.buildUserinfo(parts: object): string;
84
URI.buildQuery(data: object, duplicateParams?: boolean, escapeQuerySpace?: boolean): string;
85
```
86

87
[URI Construction](./uri-construction.md)
88

89
### Component Access and Manipulation  
90

91
Get and set individual URI components (protocol, hostname, port, path, query, fragment) with automatic URI rebuilding.
92

93
```javascript { .api }
94
// Primary component getters/setters (return property when no args, return URI instance when setting)
95
protocol(value?: string, build?: boolean): string | URI;
96
scheme(value?: string, build?: boolean): string | URI; // alias for protocol
97
hostname(value?: string, build?: boolean): string | URI;
98
port(value?: string | number, build?: boolean): string | URI;
99
path(value?: string, build?: boolean): string | URI;
100
pathname(value?: string, build?: boolean): string | URI; // alias for path
101
query(value?: string | object, build?: boolean): string | URI;
102
search(value?: string | object, build?: boolean): string | URI; // alias for query
103
fragment(value?: string, build?: boolean): string | URI;
104
hash(value?: string, build?: boolean): string | URI; // alias for fragment
105

106
// Compound component getters/setters
107
href(value?: string, build?: boolean): string | URI; // complete URI
108
origin(value?: string, build?: boolean): string | URI; // protocol + authority
109
authority(value?: string, build?: boolean): string | URI; // userinfo + host
110
userinfo(value?: string, build?: boolean): string | URI; // username + password
111
host(value?: string, build?: boolean): string | URI; // hostname + port
112
resource(value?: string, build?: boolean): string | URI; // path + query + fragment
113

114
// Individual userinfo components
115
username(value?: string, build?: boolean): string | URI;
116
password(value?: string, build?: boolean): string | URI;
117

118
// Domain component getters/setters
119
subdomain(value?: string, build?: boolean): string | URI;
120
domain(value?: string, build?: boolean): string | URI;
121
tld(value?: string, build?: boolean): string | URI;
122

123
// Path component getters/setters
124
directory(value?: string, build?: boolean): string | URI;
125
filename(value?: string, build?: boolean): string | URI;
126
suffix(value?: string, build?: boolean): string | URI;
127
```
128

129
[Component Manipulation](./component-manipulation.md)
130

131
### Query Parameter Management
132

133
Advanced query string manipulation with support for arrays, objects, and flexible parameter handling.
134

135
```javascript { .api }
136
setQuery(name: string | object, value?: string, build?: boolean): URI;
137
setSearch(name: string | object, value?: string, build?: boolean): URI; // alias
138
addQuery(name: string | object, value?: string, build?: boolean): URI;
139
addSearch(name: string | object, value?: string, build?: boolean): URI; // alias
140
removeQuery(name: string, value?: string, build?: boolean): URI;
141
removeSearch(name: string, value?: string, build?: boolean): URI; // alias
142
hasQuery(name: string, value?: string, withinArray?: boolean): boolean;
143
hasSearch(name: string, value?: string, withinArray?: boolean): boolean; // alias
144
```
145

146
[Query Management](./query-management.md)
147

148
### Path Manipulation
149

150
Path segment manipulation, directory/filename extraction, and path normalization.
151

152
```javascript { .api }
153
segment(segment?: number | string | string[], value?: string, build?: boolean): string | string[] | URI;
154
segmentCoded(segment?: number | string | string[], value?: string, build?: boolean): string | string[] | URI; // URL-decoded segments
155
directory(value?: string, build?: boolean): string | URI;
156
filename(value?: string, build?: boolean): string | URI;
157
suffix(value?: string, build?: boolean): string | URI;
158
```
159

160
[Path Manipulation](./path-manipulation.md)
161

162
### URI Normalization and Encoding
163

164
Normalize URIs according to RFC standards, handle different encoding schemes, and ensure URI validity.
165

166
```javascript { .api }
167
normalize(): URI;
168
normalizeProtocol(build?: boolean): URI;
169
normalizeHostname(build?: boolean): URI;
170
normalizePort(build?: boolean): URI;
171
normalizePath(build?: boolean): URI;
172
normalizePathname(build?: boolean): URI; // alias for normalizePath
173
normalizeQuery(build?: boolean): URI;
174
normalizeSearch(build?: boolean): URI; // alias for normalizeQuery
175
normalizeFragment(build?: boolean): URI;
176
normalizeHash(build?: boolean): URI; // alias for normalizeFragment
177
iso8859(): URI;
178
unicode(): URI;
179
readable(): URI;
180
```
181

182
[Normalization and Encoding](./normalization-encoding.md)
183

184
### URI Resolution and Comparison
185

186
Convert between relative and absolute URIs, resolve against base URIs, and compare URI equality.
187

188
```javascript { .api }
189
absoluteTo(base: string | URI): URI;
190
relativeTo(base: string | URI): URI;
191
equals(uri: string | URI): boolean;
192
```
193

194
[Resolution and Comparison](./resolution-comparison.md)
195

196
### Static Utilities
197

198
Utility functions for encoding/decoding, finding URIs in text, joining paths, and configuration.
199

200
```javascript { .api }
201
// Version and configuration properties
202
URI.version: string; // Library version (e.g., '1.19.11')
203
URI.preventInvalidHostname: boolean; // Global hostname validation control
204
URI.duplicateQueryParameters: boolean; // Global duplicate parameter handling
205
URI.escapeQuerySpace: boolean; // Global space encoding preference
206
URI.defaultPorts: object; // Protocol to default port mapping
207
URI.hostProtocols: string[]; // Protocols that require hostnames
208

209
// Encoding/decoding utilities
210
URI.encode(string: string): string;
211
URI.decode(string: string): string;
212
URI.encodeQuery(string: string, escapeQuerySpace?: boolean): string;
213
URI.decodeQuery(string: string, escapeQuerySpace?: boolean): string;
214
URI.encodePathSegment(string: string): string;
215
URI.decodePathSegment(string: string): string;
216
URI.encodeReserved(string: string): string;
217

218
// String processing utilities
219
URI.withinString(string: string, callback: function, options?: object): string;
220
URI.joinPaths(...paths: string[]): string;
221
URI.commonPath(one: string, two: string): string;
222

223
// Validation utilities
224
URI.ensureValidHostname(hostname: string, protocol?: string): string;
225
URI.ensureValidPort(port: string | number): string;
226
URI.getDomAttribute(node: Element): string;
227

228
// Environment utilities
229
URI.noConflict(removeAll?: boolean): URI; // Restore previous URI global
230
URI.iso8859(): void; // Set global encoding to ISO-8859-1
231
URI.unicode(): void; // Set global encoding to Unicode
232
```
233

234
[Static Utilities](./static-utilities.md)
235

236
### URI Utility Methods
237

238
Additional utility methods for URI manipulation and validation.
239

240
```javascript { .api }
241
// URI type checking - returns boolean
242
is(what: string): boolean; // 'relative', 'absolute', 'domain', 'ip', 'ip4', 'ip6', 'idn', 'url', 'urn', 'sld', 'punycode'
243

244
// URI manipulation
245
clone(): URI; // create deep copy
246
equals(uri: string | URI): boolean; // compare URIs for equality
247
toString(): string; // get string representation
248
valueOf(): string; // get string representation
249
readable(): string; // get human-readable representation
250

251
// Configuration methods (chainable)
252
preventInvalidHostname(v?: boolean): boolean | URI;
253
duplicateQueryParameters(v?: boolean): boolean | URI;
254
escapeQuerySpace(v?: boolean): boolean | URI;
255

256
// Internal build control
257
build(deferBuild?: boolean): URI;
258
```
259

260
## Extensions
261

262
### IPv6 Support
263

264
```javascript { .api }
265
IPv6.best(address: string): string;
266
```
267

268
[IPv6 Support](./ipv6-support.md)
269

270
### Second Level Domains
271

272
```javascript { .api }
273
SecondLevelDomains.has(domain: string): boolean;
274
SecondLevelDomains.is(domain: string): boolean;
275
SecondLevelDomains.get(domain: string): string;
276
```
277

278
[Second Level Domains](./second-level-domains.md)
279

280
### URI Templates (RFC 6570)
281

282
```javascript { .api }
283
function URITemplate(expression: string): URITemplate;
284
URITemplate.prototype.expand(data: object, opts?: object): string;
285
URI.expand(expression: string, data: object): URI;
286
```
287

288
[URI Templates](./uri-templates.md)
289

290
### Fragment Extensions
291

292
Enhanced fragment handling for query-like and URI-like fragment operations.
293

294
```javascript { .api }
295
setFragment(name: string, value: string, build?: boolean): URI;
296
setHash(name: string, value: string, build?: boolean): URI; // alias
297
addFragment(name: string, value: string, build?: boolean): URI;
298
addHash(name: string, value: string, build?: boolean): URI; // alias
299
removeFragment(name: string, value?: string, build?: boolean): URI;
300
removeHash(name: string, value?: string, build?: boolean): URI; // alias
301
```
302

303
[Fragment Extensions](./fragment-extensions.md)
304

305
### jQuery Integration
306

307
```javascript { .api }
308
$.fn.uri(uri?: string | URI): URI;
309
```
310

311
[jQuery Integration](./jquery-integration.md)