0
# Component Processing
1

2
Advanced component-level URI manipulation including encoding, escaping, path segment processing, and low-level component resolution. These functions provide fine-grained control over URI component handling.
3

4
## Capabilities
5

6
### Escape Component
7

8
Percent-encodes characters in URI components according to RFC 3986 or RFC 3987 rules.
9

10
```typescript { .api }
11
/**
12
 * Percent-encode characters in a URI component
13
 * @param str - The string to escape
14
 * @param options - Optional encoding configuration (iri mode affects which characters are escaped)
15
 * @returns Percent-encoded string
16
 */
17
function escapeComponent(str: string, options?: URIOptions): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { escapeComponent } from "uri-js";
24

25
// Basic escaping for URI components
26
const escaped = escapeComponent("hello world");
27
console.log(escaped); // "hello%20world"
28

29
// Escape special characters
30
const special = escapeComponent("user@domain.com");
31
console.log(special); // "user%40domain.com"
32

33
// Escape with IRI mode (preserves more Unicode characters)
34
const iriEscaped = escapeComponent("café", { iri: true });
35
console.log(iriEscaped); // "café" (Unicode preserved in IRI mode)
36

37
// Escape without IRI mode
38
const uriEscaped = escapeComponent("café");
39
console.log(uriEscaped); // "caf%C3%A9" (Unicode encoded)
40
```
41

42
### Unescape Component
43

44
Decodes percent-encoded characters in URI components.
45

46
```typescript { .api }
47
/**
48
 * Decode percent-encoded characters in a URI component
49
 * @param str - The string to unescape
50
 * @param options - Optional decoding configuration (iri mode affects decoding behavior)
51
 * @returns Decoded string
52
 */
53
function unescapeComponent(str: string, options?: URIOptions): string;
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { unescapeComponent } from "uri-js";
60

61
// Basic unescaping
62
const unescaped = unescapeComponent("hello%20world");
63
console.log(unescaped); // "hello world"
64

65
// Unescape encoded characters
66
const email = unescapeComponent("user%40domain.com");
67
console.log(email); // "user@domain.com"
68

69
// Unescape Unicode characters
70
const unicode = unescapeComponent("caf%C3%A9");
71
console.log(unicode); // "café"
72

73
// Unescape with IRI mode
74
const iriUnescaped = unescapeComponent("ros%C3%A9", { iri: true });
75
console.log(iriUnescaped); // "rosé"
76
```
77

78
### Remove Dot Segments
79

80
Removes dot segments from URI paths according to RFC 3986 algorithm. This is used internally for path normalization and resolution.
81

82
```typescript { .api }
83
/**
84
 * Remove dot segments from a URI path according to RFC 3986
85
 * @param input - The path string containing dot segments
86
 * @returns Path with dot segments removed
87
 */
88
function removeDotSegments(input: string): string;
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
import { removeDotSegments } from "uri-js";
95

96
// Remove single dot segments
97
const simple = removeDotSegments("/a/b/c/./../../g");
98
console.log(simple); // "/a/g"
99

100
// Remove complex dot segments
101
const complex = removeDotSegments("/a/b/c/./../d/./e/../f");
102
console.log(complex); // "/a/b/d/f"
103

104
// Handle edge cases
105
const edgeCase = removeDotSegments("../../../g");
106
console.log(edgeCase); // "g"
107

108
// Preserve trailing slashes
109
const trailing = removeDotSegments("/a/b/c/../");
110
console.log(trailing); // "/a/b/"
111
```
112

113
### Resolve Components
114

115
Resolves relative URI components against base URI components at the component level, providing more control than the string-based resolve function.
116

117
```typescript { .api }
118
/**
119
 * Resolve relative URI components against base URI components
120
 * @param base - Base URI components
121
 * @param relative - Relative URI components to resolve
122
 * @param options - Optional resolution configuration
123
 * @param skipNormalization - Skip normalization of input components (default: false)
124
 * @returns Resolved URI components
125
 */
126
function resolveComponents(
127
  base: URIComponents, 
128
  relative: URIComponents, 
129
  options: URIOptions = {}, 
130
  skipNormalization?: boolean
131
): URIComponents;
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
import { resolveComponents } from "uri-js";
138

139
// Basic component resolution
140
const base = {
141
  scheme: "http",
142
  host: "example.com",
143
  path: "/a/b/c/d"
144
};
145

146
const relative = {
147
  path: "../../g"
148
};
149

150
const resolved = resolveComponents(base, relative);
151
console.log(resolved);
152
// {
153
//   scheme: "http",
154
//   host: "example.com", 
155
//   path: "/a/g"
156
// }
157

158
// Resolve with query changes
159
const withQuery = resolveComponents(base, { query: "newquery" });
160
console.log(withQuery.query); // "newquery"
161
console.log(withQuery.path); // "/a/b/c/d" (preserved from base)
162

163
// Resolve with fragment
164
const withFragment = resolveComponents(base, { fragment: "section" });
165
console.log(withFragment.fragment); // "section"
166

167
// Resolve with authority override
168
const withAuthority = resolveComponents(base, {
169
  host: "other.com",
170
  path: "/new/path"
171
});
172
console.log(withAuthority);
173
// {
174
//   scheme: "http",
175
//   host: "other.com",
176
//   path: "/new/path"
177
// }
178

179
// Skip normalization for performance
180
const skipNorm = resolveComponents(base, relative, {}, true);
181
```
182

183
### Low-Level Encoding Functions
184

185
Internal encoding functions exposed for advanced use cases.
186

187
```typescript { .api }
188
/**
189
 * Percent-encode a single character
190
 * @param chr - Character to encode  
191
 * @returns Percent-encoded character
192
 */
193
function pctEncChar(chr: string): string;
194

195
/**
196
 * Decode a sequence of percent-encoded characters
197
 * @param str - String containing percent-encoded sequences
198
 * @returns Decoded string
199
 */
200
function pctDecChars(str: string): string;
201
```
202

203
**Usage Examples:**
204

205
```typescript
206
import { pctEncChar, pctDecChars } from "uri-js";
207

208
// Encode single character
209
const encoded = pctEncChar("@");
210
console.log(encoded); // "%40"
211

212
// Encode Unicode character
213
const unicode = pctEncChar("é");
214
console.log(unicode); // "%C3%A9"
215

216
// Decode character sequence
217
const decoded = pctDecChars("%48%65%6C%6C%6F");
218
console.log(decoded); // "Hello"
219

220
// Decode Unicode sequence
221
const unicodeDecoded = pctDecChars("%C3%A9");
222
console.log(unicodeDecoded); // "é"
223
```
224

225
## Advanced Component Manipulation
226

227
For complex URI manipulation scenarios, you can combine these functions:
228

229
```typescript
230
import { parse, serialize, resolveComponents, removeDotSegments, escapeComponent } from "uri-js";
231

232
// Parse, modify components, and rebuild
233
const original = "http://example.com/path with spaces/../file.html";
234
const components = parse(original);
235

236
// Clean up the path
237
components.path = removeDotSegments(components.path || "");
238

239
// Escape spaces in path
240
components.path = escapeComponent(components.path);
241

242
// Add query parameter
243
components.query = "version=1.0";
244

245
// Rebuild URI
246
const result = serialize(components);
247
console.log(result); // "http://example.com/path%20with%20spaces/file.html?version=1.0"
248
```
249

250
## Error Handling
251

252
Component processing functions are generally safe and don't throw exceptions under normal use. However, some edge cases to be aware of:
253

254
- Invalid percent-encoding sequences in `pctDecChars` may result in replacement characters
255
- Empty or null inputs are handled gracefully
256
- Malformed dot segments are processed according to RFC 3986 rules
257

258
```typescript
259
import { unescapeComponent, removeDotSegments } from "uri-js";
260

261
// Handles invalid encoding gracefully
262
const invalid = unescapeComponent("%ZZ");
263
console.log(invalid); // "%ZZ" (unchanged)
264

265
// Handles empty input
266
const empty = removeDotSegments("");
267
console.log(empty); // ""
268
```