0
# Core URI Operations
1
2
Essential URI parsing, serialization, and manipulation functions for standard URI processing workflows. These functions form the foundation of URI.js functionality.
3
4
## Capabilities
5
6
### Parse Function
7
8
Parses a URI string into component parts according to RFC 3986/3987 specifications.
9
10
```typescript { .api }
11
/**
12
* Parse a URI string into component parts
13
* @param uriString - The URI string to parse
14
* @param options - Optional parsing configuration
15
* @returns Parsed URI components object
16
*/
17
function parse(uriString: string, options: URIOptions = {}): URIComponents;
18
```
19
20
**Usage Examples:**
21
22
```typescript
23
import { parse } from "uri-js";
24
25
// Basic URI parsing
26
const components = parse("https://user:pass@example.com:8443/path/to/resource?query=value&foo=bar#section");
27
console.log(components);
28
// {
29
// scheme: "https",
30
// userinfo: "user:pass",
31
// host: "example.com",
32
// port: 8443,
33
// path: "/path/to/resource",
34
// query: "query=value&foo=bar",
35
// fragment: "section",
36
// reference: "uri"
37
// }
38
39
// Parse with IRI support
40
const iriComponents = parse("http://examplé.org/rosé", { iri: true });
41
console.log(iriComponents.host); // "examplé.org"
42
43
// Parse with unicode support
44
const unicodeComponents = parse("http://xn--exampl-gva.org/ros%C3%A9", { unicodeSupport: true });
45
46
// Parse relative URI
47
const relativeComponents = parse("../path/file.html");
48
console.log(relativeComponents.reference); // "relative"
49
```
50
51
### Serialize Function
52
53
Converts URI components object back into a URI string with optional formatting options.
54
55
```typescript { .api }
56
/**
57
* Convert URI components to a URI string
58
* @param components - The URI components to serialize
59
* @param options - Optional serialization configuration
60
* @returns Serialized URI string
61
*/
62
function serialize(components: URIComponents, options: URIOptions = {}): string;
63
```
64
65
**Usage Examples:**
66
67
```typescript
68
import { serialize } from "uri-js";
69
70
// Basic serialization
71
const uri = serialize({
72
scheme: "https",
73
host: "api.example.com",
74
path: "/v1/users",
75
query: "limit=10&offset=0"
76
});
77
console.log(uri); // "https://api.example.com/v1/users?limit=10&offset=0"
78
79
// Serialize with IRI output
80
const iriUri = serialize({
81
scheme: "http",
82
host: "xn--exampl-gva.org",
83
path: "/ros%C3%A9"
84
}, { iri: true });
85
console.log(iriUri); // "http://examplé.org/rosé"
86
87
// Serialize with domain host processing
88
const domainUri = serialize({
89
scheme: "http",
90
host: "examplé.org"
91
}, { domainHost: true });
92
```
93
94
### Resolve Function
95
96
Resolves a relative URI against a base URI according to RFC 3986 resolution algorithms.
97
98
```typescript { .api }
99
/**
100
* Resolve a relative URI against a base URI
101
* @param baseURI - The base URI string
102
* @param relativeURI - The relative URI string to resolve
103
* @param options - Optional resolution configuration
104
* @returns Resolved absolute URI string
105
*/
106
function resolve(baseURI: string, relativeURI: string, options?: URIOptions): string;
107
```
108
109
**Usage Examples:**
110
111
```typescript
112
import { resolve } from "uri-js";
113
114
// Basic resolution
115
const resolved = resolve("http://example.com/a/b/c/d", "../../g");
116
console.log(resolved); // "http://example.com/a/g"
117
118
// Resolve with query parameters
119
const withQuery = resolve("http://example.com/path", "?newquery");
120
console.log(withQuery); // "http://example.com/path?newquery"
121
122
// Resolve with fragments
123
const withFragment = resolve("http://example.com/path", "#section");
124
console.log(withFragment); // "http://example.com/path#section"
125
126
// Complex path resolution
127
const complex = resolve("http://example.com/a/b/c/", "../d/./e/../f");
128
console.log(complex); // "http://example.com/a/b/d/f"
129
```
130
131
### Normalize Function (Overloaded)
132
133
Normalizes a URI string or components object to a standard canonical form.
134
135
```typescript { .api }
136
/**
137
* Normalize a URI string to canonical form
138
* @param uri - The URI string to normalize
139
* @param options - Optional normalization configuration
140
* @returns Normalized URI string
141
*/
142
function normalize(uri: string, options?: URIOptions): string;
143
144
/**
145
* Normalize URI components to canonical form
146
* @param uri - The URI components to normalize
147
* @param options - Optional normalization configuration
148
* @returns Normalized URI components
149
*/
150
function normalize(uri: URIComponents, options?: URIOptions): URIComponents;
151
```
152
153
**Usage Examples:**
154
155
```typescript
156
import { normalize } from "uri-js";
157
158
// String normalization
159
const normalized = normalize("HTTP://EXAMPLE.COM:80/%7Esmith/home.html");
160
console.log(normalized); // "http://example.com/~smith/home.html"
161
162
// IPv4 address normalization
163
const ipv4 = normalize("//192.068.001.000");
164
console.log(ipv4); // "//192.68.1.0"
165
166
// IPv6 address normalization
167
const ipv6 = normalize("//[2001:0:0DB8::0:0001]");
168
console.log(ipv6); // "//[2001:0:db8::1]"
169
170
// Components normalization
171
const components = normalize({
172
scheme: "HTTP",
173
host: "EXAMPLE.COM",
174
path: "/%7Efoo"
175
});
176
console.log(components.scheme); // "http"
177
console.log(components.host); // "example.com"
178
console.log(components.path); // "/~foo"
179
```
180
181
### Equal Function (Overloaded)
182
183
Compares two URIs for equivalence after normalization.
184
185
```typescript { .api }
186
/**
187
* Compare two URI strings for equality
188
* @param uriA - First URI string to compare
189
* @param uriB - Second URI string to compare
190
* @param options - Optional comparison configuration
191
* @returns True if URIs are equivalent
192
*/
193
function equal(uriA: string, uriB: string, options?: URIOptions): boolean;
194
195
/**
196
* Compare two URI components for equality
197
* @param uriA - First URI components to compare
198
* @param uriB - Second URI components to compare
199
* @param options - Optional comparison configuration
200
* @returns True if URI components are equivalent
201
*/
202
function equal(uriA: URIComponents, uriB: URIComponents, options?: URIOptions): boolean;
203
```
204
205
**Usage Examples:**
206
207
```typescript
208
import { equal } from "uri-js";
209
210
// String comparison
211
const isEqual = equal("http://example.com/", "HTTP://EXAMPLE.COM:80/");
212
console.log(isEqual); // true
213
214
// Case and encoding differences
215
const normalized = equal(
216
"example://a/b/c/%7Bfoo%7D",
217
"eXAMPLE://a/./b/../b/%63/%7bfoo%7d"
218
);
219
console.log(normalized); // true
220
221
// Components comparison
222
const componentsEqual = equal(
223
{ scheme: "http", host: "example.com", path: "/" },
224
{ scheme: "HTTP", host: "EXAMPLE.COM", port: 80, path: "/" }
225
);
226
console.log(componentsEqual); // true
227
228
// IPv6 comparison
229
const ipv6Equal = equal(
230
"//[2001:db8::1]",
231
"//[2001:0db8:0000:0000:0000:0000:0000:0001]"
232
);
233
console.log(ipv6Equal); // true
234
```
235
236
## Configuration Options
237
238
All core functions accept an optional `URIOptions` parameter for customizing behavior:
239
240
```typescript { .api }
241
interface URIOptions {
242
/** Force treatment as specific scheme */
243
scheme?: string;
244
/** Reference format ("suffix" for suffix format parsing) */
245
reference?: string;
246
/** Enable relaxed URI resolving rules */
247
tolerant?: boolean;
248
/** Don't resolve relative path components during serialization */
249
absolutePath?: boolean;
250
/** Handle as IRI (RFC 3987) with Unicode support */
251
iri?: boolean;
252
/** Parse non-ASCII characters in output */
253
unicodeSupport?: boolean;
254
/** Treat host component as domain name for IDN processing */
255
domainHost?: boolean;
256
}
257
```
258
259
## Return Types
260
261
```typescript { .api }
262
interface URIComponents {
263
/** URI scheme (e.g., "http", "https") */
264
scheme?: string;
265
/** User information part (e.g., "user:pass") */
266
userinfo?: string;
267
/** Host component (domain or IP address) */
268
host?: string;
269
/** Port number or string */
270
port?: number | string;
271
/** Path component */
272
path?: string;
273
/** Query string */
274
query?: string;
275
/** Fragment identifier */
276
fragment?: string;
277
/** Reference type: "uri", "absolute", "relative", "same-document" */
278
reference?: string;
279
/** Error message if parsing failed */
280
error?: string;
281
}
282
```