0
# URI.js
1

2
URI.js is an RFC 3986/3987 compliant, scheme extendable URI parsing, normalizing, resolving, and serializing library for JavaScript environments. It provides comprehensive support for URI and IRI handling with built-in scheme support, IPv4/IPv6 address normalization, and internationalized domain name (IDN) processing.
3

4
## Package Information
5

6
- **Package Name**: uri-js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install uri-js`
10

11
## Core Imports
12

13
```typescript
14
import * as URI from "uri-js";
15
```
16

17
For named imports:
18

19
```typescript
20
import { 
21
  parse, 
22
  serialize, 
23
  resolve, 
24
  normalize, 
25
  equal,
26
  escapeComponent,
27
  unescapeComponent,
28
  removeDotSegments,
29
  resolveComponents,
30
  pctEncChar,
31
  pctDecChars,
32
  SCHEMES,
33
  URIComponents,
34
  URIOptions,
35
  URISchemeHandler,
36
  URIRegExps
37
} from "uri-js";
38
```
39

40
For CommonJS:
41

42
```javascript
43
const URI = require("uri-js");
44
// or
45
const { 
46
  parse, 
47
  serialize, 
48
  resolve, 
49
  normalize, 
50
  equal,
51
  escapeComponent,
52
  unescapeComponent,
53
  removeDotSegments,
54
  resolveComponents,
55
  pctEncChar,
56
  pctDecChars,
57
  SCHEMES 
58
} = require("uri-js");
59
```
60

61
## Basic Usage
62

63
```typescript
64
import { parse, serialize, resolve, normalize, equal } from "uri-js";
65

66
// Parse a URI into components
67
const components = parse("http://user:pass@example.com:8080/path?query=value#fragment");
68
console.log(components);
69
// {
70
//   scheme: "http",
71
//   userinfo: "user:pass", 
72
//   host: "example.com",
73
//   port: 8080,
74
//   path: "/path",
75
//   query: "query=value",
76
//   fragment: "fragment"
77
// }
78

79
// Serialize components back to URI string
80
const uri = serialize({
81
  scheme: "https",
82
  host: "example.com",
83
  path: "/api/data",
84
  query: "format=json"
85
});
86
console.log(uri); // "https://example.com/api/data?format=json"
87

88
// Resolve relative URIs
89
const resolved = resolve("http://example.com/a/b/c", "../d/e");
90
console.log(resolved); // "http://example.com/a/d/e"
91

92
// Normalize URIs
93
const normalized = normalize("HTTP://EXAMPLE.COM:80/%7Efoo");
94
console.log(normalized); // "http://example.com/~foo"
95

96
// Compare URIs for equality
97
const isEqual = equal("http://example.com/", "HTTP://EXAMPLE.COM:80/");
98
console.log(isEqual); // true
99
```
100

101
## Architecture
102

103
URI.js is built around several key components:
104

105
- **Core Parser**: RFC 3986/3987 compliant parsing engine with support for both URI and IRI formats
106
- **Component System**: Structured representation of URI parts (scheme, host, path, query, etc.)  
107
- **Scheme Handlers**: Extensible scheme-specific processing for HTTP, HTTPS, WebSocket, mailto, and URN protocols
108
- **Normalization Engine**: Standardization of URI formatting including case normalization and percent-encoding
109
- **Resolution System**: Relative URI resolution following RFC 3986 algorithms
110
- **Type System**: Full TypeScript support with comprehensive type definitions
111

112
## Capabilities
113

114
### Core URI Operations
115

116
Essential URI parsing, serialization, and manipulation functions for standard URI processing workflows.
117

118
```typescript { .api }
119
function parse(uriString: string, options?: URIOptions): URIComponents;
120
function serialize(components: URIComponents, options?: URIOptions): string;
121
function resolve(baseURI: string, relativeURI: string, options?: URIOptions): string;
122
function normalize(uri: string, options?: URIOptions): string;
123
function normalize(uri: URIComponents, options?: URIOptions): URIComponents;
124
function equal(uriA: string, uriB: string, options?: URIOptions): boolean;
125
function equal(uriA: URIComponents, uriB: URIComponents, options?: URIOptions): boolean;
126
```
127

128
[Core Operations](./core-operations.md)
129

130
### Component Processing
131

132
Advanced component-level URI manipulation including encoding, escaping, and path segment processing.
133

134
```typescript { .api }
135
function escapeComponent(str: string, options?: URIOptions): string;
136
function unescapeComponent(str: string, options?: URIOptions): string; 
137
function removeDotSegments(input: string): string;
138
function resolveComponents(base: URIComponents, relative: URIComponents, options?: URIOptions, skipNormalization?: boolean): URIComponents;
139
function pctEncChar(chr: string): string;
140
function pctDecChars(str: string): string;
141
```
142

143
[Component Processing](./component-processing.md)
144

145
### Scheme Support
146

147
Built-in handlers for common URI schemes with protocol-specific parsing and serialization logic.
148

149
```typescript { .api }
150
interface URISchemeHandler<Components extends URIComponents = URIComponents, Options extends URIOptions = URIOptions, ParentComponents extends URIComponents = URIComponents> {
151
  scheme: string;
152
  parse(components: ParentComponents, options: Options): Components;
153
  serialize(components: Components, options: Options): ParentComponents;
154
  unicodeSupport?: boolean;
155
  domainHost?: boolean;
156
  absolutePath?: boolean;
157
}
158

159
const SCHEMES: {[scheme: string]: URISchemeHandler};
160
```
161

162
Built-in scheme support includes: HTTP, HTTPS, WebSocket (WS/WSS), mailto, URN, and URN UUID.
163

164
[Scheme Support](./scheme-support.md)
165

166

167
## Core Types
168

169
```typescript { .api }
170
interface URIComponents {
171
  scheme?: string;
172
  userinfo?: string;
173
  host?: string;
174
  port?: number | string;
175
  path?: string;
176
  query?: string;
177
  fragment?: string;
178
  reference?: string;
179
  error?: string;
180
}
181

182
interface URIOptions {
183
  scheme?: string;
184
  reference?: string;
185
  tolerant?: boolean;
186
  absolutePath?: boolean;
187
  iri?: boolean;
188
  unicodeSupport?: boolean;
189
  domainHost?: boolean;
190
}
191

192
interface URIRegExps {
193
  NOT_SCHEME: RegExp;
194
  NOT_USERINFO: RegExp;
195
  NOT_HOST: RegExp;
196
  NOT_PATH: RegExp;
197
  NOT_PATH_NOSCHEME: RegExp;
198
  NOT_QUERY: RegExp;
199
  NOT_FRAGMENT: RegExp;
200
  ESCAPE: RegExp;
201
  UNRESERVED: RegExp;
202
  OTHER_CHARS: RegExp;
203
  PCT_ENCODED: RegExp;
204
  IPV4ADDRESS: RegExp;
205
  IPV6ADDRESS: RegExp;
206
}
207
```
208

209
## Specialized Component Types
210

211
These interfaces extend the base URIComponents for scheme-specific parsing and serialization. They are used internally by scheme handlers and returned by parsing functions when processing specific URI schemes.
212

213
```typescript { .api }
214
interface WSComponents extends URIComponents {
215
  resourceName?: string;
216
  secure?: boolean;
217
}
218

219
interface MailtoHeaders {
220
  [hfname: string]: string;
221
}
222

223
interface MailtoComponents extends URIComponents {
224
  to: Array<string>;
225
  headers?: MailtoHeaders;
226
  subject?: string;
227
  body?: string;
228
}
229

230
interface URNComponents extends URIComponents {
231
  nid?: string;
232
  nss?: string;
233
}
234

235
interface URNOptions extends URIOptions {
236
  nid?: string;
237
}
238

239
interface UUIDComponents extends URNComponents {
240
  uuid?: string;
241
}
242
```