0
# URI Resolution and Comparison
1

2
Convert between relative and absolute URIs, resolve against base URIs, and compare URI equality with proper normalization.
3

4
## Capabilities
5

6
### URI Resolution
7

8
Methods for converting between relative and absolute URIs using base URI resolution.
9

10
```javascript { .api }
11
/**
12
 * Convert relative URI to absolute using base URI
13
 * @param base - Base URI for resolution (string or URI instance)
14
 * @returns New URI instance with absolute URI
15
 */
16
absoluteTo(base: string | URI): URI;
17

18
/**
19
 * Convert absolute URI to relative using base URI
20
 * @param base - Base URI for relativization (string or URI instance)
21
 * @returns New URI instance with relative URI
22
 */
23
relativeTo(base: string | URI): URI;
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
// Absolute resolution
30
const relative = new URI('../images/logo.png');
31
const base = 'http://example.com/docs/guide/';
32
const absolute = relative.absoluteTo(base);
33
console.log(absolute.toString()); // 'http://example.com/docs/images/logo.png'
34

35
// Complex relative resolution
36
const complex = new URI('../../api/v2/users?page=1');
37
const complexBase = 'http://api.example.com/docs/v1/guide/intro.html';
38
const resolved = complex.absoluteTo(complexBase);
39
console.log(resolved.toString()); // 'http://api.example.com/api/v2/users?page=1'
40

41
// Relative conversion
42
const abs = new URI('http://example.com/docs/images/logo.png');
43
const baseForRel = 'http://example.com/docs/guide/';
44
const rel = abs.relativeTo(baseForRel);
45
console.log(rel.toString()); // '../images/logo.png'
46

47
// Same directory
48
const sameDir = new URI('http://example.com/docs/guide/page.html');
49
const sameDirBase = 'http://example.com/docs/guide/intro.html';
50
const sameDirRel = sameDir.relativeTo(sameDirBase);
51
console.log(sameDirRel.toString()); // 'page.html'
52
```
53

54
### URI Comparison
55

56
Methods for comparing URI equality with proper normalization.
57

58
```javascript { .api }
59
/**
60
 * Compare URIs for equality
61
 * @param uri - URI to compare against (string or URI instance)
62
 * @returns Boolean indicating equality
63
 */
64
equals(uri: string | URI): boolean;
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
// Basic equality
71
const uri1 = new URI('http://example.com/path');
72
const uri2 = new URI('http://example.com/path');
73
console.log(uri1.equals(uri2)); // true
74

75
// Case insensitive comparison
76
const uri3 = new URI('HTTP://EXAMPLE.COM/path');
77
const uri4 = new URI('http://example.com/path');
78
console.log(uri3.equals(uri4)); // true (after normalization)
79

80
// Default port comparison
81
const uri5 = new URI('http://example.com:80/path');
82
const uri6 = new URI('http://example.com/path');
83
console.log(uri5.equals(uri6)); // true (port 80 is default for http)
84

85
// Path normalization comparison
86
const uri7 = new URI('http://example.com/path/../docs/./file.html');
87
const uri8 = new URI('http://example.com/docs/file.html');
88
console.log(uri7.equals(uri8)); // true (after path normalization)
89

90
// Query parameter order
91
const uri9 = new URI('http://example.com/search?a=1&b=2');
92
const uri10 = new URI('http://example.com/search?b=2&a=1');
93
console.log(uri9.equals(uri10)); // false (query order matters)
94

95
// Fragment comparison
96
const uri11 = new URI('http://example.com/page#section1');
97
const uri12 = new URI('http://example.com/page#section2');
98
console.log(uri11.equals(uri12)); // false
99
```
100

101
### Advanced Resolution Scenarios
102

103
Complex resolution patterns and edge cases.
104

105
**Usage Examples:**
106

107
```javascript
108
// Protocol-relative URLs
109
const protocolRel = new URI('//cdn.example.com/assets/script.js');
110
const httpsBase = 'https://example.com/page';
111
const resolvedHttps = protocolRel.absoluteTo(httpsBase);
112
console.log(resolvedHttps.toString()); // 'https://cdn.example.com/assets/script.js'
113

114
// Root-relative URLs
115
const rootRel = new URI('/api/users');
116
const deepBase = 'http://example.com/app/admin/dashboard.html';
117
const rootResolved = rootRel.absoluteTo(deepBase);
118
console.log(rootResolved.toString()); // 'http://example.com/api/users'
119

120
// Query and fragment preservation
121
const relWithQuery = new URI('../search?q=test#results');
122
const baseWithQuery = 'http://example.com/docs/guide?version=1.0#intro';
123
const resolvedWithQuery = relWithQuery.absoluteTo(baseWithQuery);
124
console.log(resolvedWithQuery.toString()); // 'http://example.com/search?q=test#results'
125

126
// Cross-domain resolution
127
const crossDomain = new URI('http://other.com/page');
128
const localBase = 'http://example.com/current';
129
const crossResolved = crossDomain.absoluteTo(localBase);
130
console.log(crossResolved.toString()); // 'http://other.com/page' (unchanged)
131

132
// Edge case: empty relative
133
const empty = new URI('');
134
const emptyBase = 'http://example.com/path/to/page.html';
135
const emptyResolved = empty.absoluteTo(emptyBase);
136
console.log(emptyResolved.toString()); // 'http://example.com/path/to/page.html'
137
```
138

139
### Relative Path Calculation
140

141
Calculating relative paths between different URIs.
142

143
**Usage Examples:**
144

145
```javascript
146
// Different directories
147
const from = new URI('http://example.com/docs/api/reference.html');
148
const to = new URI('http://example.com/assets/images/logo.png');
149
const relative = to.relativeTo(from);
150
console.log(relative.toString()); // '../../assets/images/logo.png'
151

152
// Same directory different files
153
const sameDir1 = new URI('http://example.com/docs/intro.html');
154
const sameDir2 = new URI('http://example.com/docs/advanced.html');
155
const sameDirRel = sameDir2.relativeTo(sameDir1);
156
console.log(sameDirRel.toString()); // 'advanced.html'
157

158
// Subdirectory to parent
159
const child = new URI('http://example.com/docs/api/endpoints/users.html');
160
const parent = new URI('http://example.com/docs/index.html');
161
const upRel = parent.relativeTo(child);
162
console.log(upRel.toString()); // '../../index.html'
163

164
// Different hosts (cannot be relative)
165
const host1 = new URI('http://example.com/page');
166
const host2 = new URI('http://other.com/page');
167
const crossHostRel = host2.relativeTo(host1);
168
console.log(crossHostRel.toString()); // 'http://other.com/page' (absolute)
169

170
// With query parameters
171
const withQuery1 = new URI('http://example.com/search?q=old');
172
const withQuery2 = new URI('http://example.com/results?q=new');
173
const queryRel = withQuery2.relativeTo(withQuery1);
174
console.log(queryRel.toString()); // 'results?q=new'
175
```
176

177
### URI Base Extraction
178

179
Extracting base URIs and working with URI hierarchies.
180

181
**Usage Examples:**
182

183
```javascript
184
// Extract directory base
185
const fileUri = new URI('http://example.com/docs/guide/intro.html');
186
const dirBase = fileUri.clone().filename('').toString();
187
console.log(dirBase); // 'http://example.com/docs/guide/'
188

189
// Extract domain base
190
const domainBase = fileUri.clone().pathname('').query('').fragment('').toString();
191
console.log(domainBase); // 'http://example.com'
192

193
// Working with URI hierarchies
194
const deepUri = new URI('http://api.example.com/v1/users/123/posts/456?details=true');
195

196
// Get parent resource
197
const segments = deepUri.segment();
198
segments.pop(); // Remove last segment
199
const parentResource = deepUri.clone().segment(segments).query('').toString();
200
console.log(parentResource); // 'http://api.example.com/v1/users/123/posts'
201

202
// Get collection URI
203
const collectionSegments = deepUri.segment();
204
collectionSegments.splice(-1, 1); // Remove resource ID
205
const collectionUri = deepUri.clone().segment(collectionSegments).query('').toString();
206
console.log(collectionUri); // 'http://api.example.com/v1/users/123/posts'
207
```