0
# Component Manipulation
1

2
Get and set individual URI components (protocol, hostname, port, path, query, fragment) with automatic URI rebuilding and chainable operations.
3

4
## Capabilities
5

6
### Basic Component Accessors
7

8
Individual component getters and setters for all URI parts.
9

10
```javascript { .api }
11
/**
12
 * Get or set the protocol (scheme)
13
 * @param value - New protocol value (without :)
14
 * @param build - Whether to rebuild URI immediately
15
 * @returns Current protocol string or URI instance for chaining
16
 */
17
protocol(value?: string, build?: boolean): string | URI;
18
scheme(value?: string, build?: boolean): string | URI; // Alias for protocol
19

20
/**
21
 * Get or set the username
22
 * @param value - New username value
23
 * @param build - Whether to rebuild URI immediately
24
 * @returns Current username string or URI instance for chaining
25
 */
26
username(value?: string, build?: boolean): string | URI;
27

28
/**
29
 * Get or set the password
30
 * @param value - New password value
31
 * @param build - Whether to rebuild URI immediately
32
 * @returns Current password string or URI instance for chaining
33
 */
34
password(value?: string, build?: boolean): string | URI;
35

36
/**
37
 * Get or set the hostname
38
 * @param value - New hostname value
39
 * @param build - Whether to rebuild URI immediately
40
 * @returns Current hostname string or URI instance for chaining
41
 */
42
hostname(value?: string, build?: boolean): string | URI;
43

44
/**
45
 * Get or set the port
46
 * @param value - New port value (string or number)
47
 * @param build - Whether to rebuild URI immediately
48
 * @returns Current port string or URI instance for chaining
49
 */
50
port(value?: string | number, build?: boolean): string | URI;
51

52
/**
53
 * Get or set the pathname
54
 * @param value - New pathname value
55
 * @param build - Whether to rebuild URI immediately
56
 * @returns Current pathname string or URI instance for chaining
57
 */
58
pathname(value?: string, build?: boolean): string | URI;
59
path(value?: string, build?: boolean): string | URI; // Alias for pathname
60

61
/**
62
 * Get or set the search string (query with ?)
63
 * @param value - New search value (with or without leading ?)
64
 * @param build - Whether to rebuild URI immediately
65
 * @returns Current search string or URI instance for chaining
66
 */
67
search(value?: string, build?: boolean): string | URI;
68

69
/**
70
 * Get or set the query string
71
 * @param value - New query value (without leading ?)
72
 * @param build - Whether to rebuild URI immediately
73
 * @returns Current query string or URI instance for chaining
74
 */
75
query(value?: string | object, build?: boolean): string | URI;
76

77
/**
78
 * Get or set the hash (fragment with #)
79
 * @param value - New hash value (with or without leading #)
80
 * @param build - Whether to rebuild URI immediately
81
 * @returns Current hash string or URI instance for chaining
82
 */
83
hash(value?: string, build?: boolean): string | URI;
84

85
/**
86
 * Get or set the fragment
87
 * @param value - New fragment value (without leading #)
88
 * @param build - Whether to rebuild URI immediately
89
 * @returns Current fragment string or URI instance for chaining
90
 */
91
fragment(value?: string, build?: boolean): string | URI;
92
```
93

94
**Usage Examples:**
95

96
```javascript
97
const uri = new URI('http://user:pass@example.com:8080/path/to/file.html?query=value#section');
98

99
// Get components
100
console.log(uri.protocol()); // 'http'
101
console.log(uri.username()); // 'user'
102
console.log(uri.hostname()); // 'example.com'
103
console.log(uri.port()); // '8080'
104
console.log(uri.pathname()); // '/path/to/file.html'
105
console.log(uri.query()); // 'query=value'
106
console.log(uri.fragment()); // 'section'
107

108
// Set components (chainable)
109
uri.protocol('https')
110
   .hostname('newhost.com')
111
   .port(9000)
112
   .pathname('/new/path')
113
   .query('new=query')
114
   .fragment('newSection');
115

116
console.log(uri.toString()); 
117
// 'https://user:pass@newhost.com:9000/new/path?new=query#newSection'
118
```
119

120
### Compound Component Accessors
121

122
Higher-level accessors that work with multiple related components.
123

124
```javascript { .api }
125
/**
126
 * Get or set the origin (protocol + authority)
127
 * @param value - New origin value
128
 * @param build - Whether to rebuild URI immediately
129
 * @returns Current origin string or URI instance for chaining
130
 */
131
origin(value?: string, build?: boolean): string | URI;
132

133
/**
134
 * Get or set the host (hostname + port)
135
 * @param value - New host value
136
 * @param build - Whether to rebuild URI immediately
137
 * @returns Current host string or URI instance for chaining
138
 */
139
host(value?: string, build?: boolean): string | URI;
140

141
/**
142
 * Get or set the authority (userinfo + host)
143
 * @param value - New authority value
144
 * @param build - Whether to rebuild URI immediately
145
 * @returns Current authority string or URI instance for chaining
146
 */
147
authority(value?: string, build?: boolean): string | URI;
148

149
/**
150
 * Get or set the userinfo (username:password)
151
 * @param value - New userinfo value
152
 * @param build - Whether to rebuild URI immediately
153
 * @returns Current userinfo string or URI instance for chaining
154
 */
155
userinfo(value?: string, build?: boolean): string | URI;
156

157
/**
158
 * Get or set the resource (path + query + fragment)
159
 * @param value - New resource value
160
 * @param build - Whether to rebuild URI immediately
161
 * @returns Current resource string or URI instance for chaining
162
 */
163
resource(value?: string, build?: boolean): string | URI;
164
```
165

166
**Usage Examples:**
167

168
```javascript
169
const uri = new URI('http://user:pass@example.com:8080/path/to/file.html?query=value#section');
170

171
// Get compound components
172
console.log(uri.origin()); // 'http://user:pass@example.com:8080'
173
console.log(uri.host()); // 'example.com:8080'
174
console.log(uri.authority()); // 'user:pass@example.com:8080'
175
console.log(uri.userinfo()); // 'user:pass'
176
console.log(uri.resource()); // '/path/to/file.html?query=value#section'
177

178
// Set compound components
179
uri.host('newhost.com:9000');
180
console.log(uri.hostname()); // 'newhost.com'
181
console.log(uri.port()); // '9000'
182

183
uri.userinfo('newuser:newpass');
184
console.log(uri.username()); // 'newuser'
185
console.log(uri.password()); // 'newpass'
186
```
187

188
### Domain Component Accessors
189

190
Specialized accessors for domain-specific components.
191

192
```javascript { .api }
193
/**
194
 * Get or set the subdomain portion
195
 * @param value - New subdomain value
196
 * @param build - Whether to rebuild URI immediately
197
 * @returns Current subdomain string or URI instance for chaining
198
 */
199
subdomain(value?: string, build?: boolean): string | URI;
200

201
/**
202
 * Get or set the domain name (without subdomain and TLD)
203
 * @param value - New domain value
204
 * @param build - Whether to rebuild URI immediately
205
 * @returns Current domain string or URI instance for chaining
206
 */
207
domain(value?: string, build?: boolean): string | URI;
208

209
/**
210
 * Get or set the top-level domain
211
 * @param value - New TLD value
212
 * @param build - Whether to rebuild URI immediately
213
 * @returns Current TLD string or URI instance for chaining
214
 */
215
tld(value?: string, build?: boolean): string | URI;
216
```
217

218
**Usage Examples:**
219

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

223
// Get domain parts
224
console.log(uri.subdomain()); // 'api.staging'
225
console.log(uri.domain()); // 'example'
226
console.log(uri.tld()); // 'com'
227

228
// Set domain parts
229
uri.subdomain('www')
230
   .domain('mysite')
231
   .tld('org');
232

233
console.log(uri.hostname()); // 'www.mysite.org'
234

235
// Complex subdomain example
236
const complexUri = new URI('http://www.blog.company.co.uk/');
237
console.log(complexUri.subdomain()); // 'www.blog'
238
console.log(complexUri.domain()); // 'company'
239
console.log(complexUri.tld()); // 'co.uk'
240
```
241

242
### Path Component Accessors
243

244
Specialized accessors for path-specific components.
245

246
```javascript { .api }
247
/**
248
 * Get or set the directory portion of the path
249
 * @param value - New directory value
250
 * @param build - Whether to rebuild URI immediately
251
 * @returns Current directory string or URI instance for chaining
252
 */
253
directory(value?: string, build?: boolean): string | URI;
254

255
/**
256
 * Get or set the filename portion of the path
257
 * @param value - New filename value
258
 * @param build - Whether to rebuild URI immediately
259
 * @returns Current filename string or URI instance for chaining
260
 */
261
filename(value?: string, build?: boolean): string | URI;
262

263
/**
264
 * Get or set the file extension (suffix)
265
 * @param value - New suffix value (with or without leading .)
266
 * @param build - Whether to rebuild URI immediately
267
 * @returns Current suffix string or URI instance for chaining
268
 */
269
suffix(value?: string, build?: boolean): string | URI;
270
```
271

272
**Usage Examples:**
273

274
```javascript
275
const uri = new URI('http://example.com/path/to/document.pdf');
276

277
// Get path parts
278
console.log(uri.directory()); // '/path/to'
279
console.log(uri.filename()); // 'document.pdf'
280
console.log(uri.suffix()); // 'pdf'
281

282
// Set path parts
283
uri.directory('/downloads/files')
284
   .filename('report')
285
   .suffix('html');
286

287
console.log(uri.pathname()); // '/downloads/files/report.html'
288

289
// Handle edge cases
290
const rootUri = new URI('http://example.com/file.txt');
291
console.log(rootUri.directory()); // ''
292
console.log(rootUri.filename()); // 'file.txt'
293

294
const dirUri = new URI('http://example.com/path/to/');  
295
console.log(dirUri.directory()); // '/path/to'
296
console.log(dirUri.filename()); // ''
297
```
298

299
### Instance Configuration Methods
300

301
Methods to configure behavior for individual URI instances.
302

303
```javascript { .api }
304
/**
305
 * Set hostname validation for this instance
306
 * @param value - Whether to prevent invalid hostnames
307
 * @returns URI instance for chaining
308
 */
309
preventInvalidHostname(value: boolean): URI;
310

311
/**
312
 * Set duplicate query parameter handling for this instance
313
 * @param value - Whether to allow duplicate parameter names
314
 * @returns URI instance for chaining
315
 */
316
duplicateQueryParameters(value: boolean): URI;
317

318
/**
319
 * Set query space escaping for this instance
320
 * @param value - Whether to escape spaces as + instead of %20
321
 * @returns URI instance for chaining
322
 */
323
escapeQuerySpace(value: boolean): URI;
324
```
325

326
**Usage Examples:**
327

328
```javascript
329
const uri = new URI('http://example.com/');
330

331
// Configure instance behavior
332
uri.preventInvalidHostname(true)
333
   .duplicateQueryParameters(true)
334
   .escapeQuerySpace(false);
335

336
// This will allow multiple values for same parameter
337
uri.addQuery('tag', 'javascript')
338
   .addQuery('tag', 'programming');
339

340
console.log(uri.query()); // 'tag=javascript&tag=programming'
341
```