0
# Scheme Support
1

2
Built-in handlers for common URI schemes with protocol-specific parsing and serialization logic. URI.js provides an extensible scheme system with pre-built support for HTTP, HTTPS, WebSocket, mailto, URN, and UUID protocols.
3

4
## Capabilities
5

6
### Scheme Handler Interface
7

8
The core interface for implementing custom scheme handlers.
9

10
```typescript { .api }
11
/**
12
 * Interface for URI scheme handlers providing protocol-specific processing
13
 */
14
interface URISchemeHandler<
15
  Components extends URIComponents = URIComponents, 
16
  Options extends URIOptions = URIOptions, 
17
  ParentComponents extends URIComponents = URIComponents
18
> {
19
  /** The scheme name this handler processes */
20
  scheme: string;
21
  /** Parse method for scheme-specific component processing */
22
  parse(components: ParentComponents, options: Options): Components;
23
  /** Serialize method for scheme-specific component serialization */
24
  serialize(components: Components, options: Options): ParentComponents;
25
  /** Whether this scheme supports Unicode characters */
26
  unicodeSupport?: boolean;
27
  /** Whether this scheme treats host as domain name */
28
  domainHost?: boolean;
29
  /** Whether this scheme requires absolute paths */
30
  absolutePath?: boolean;
31
}
32
```
33

34
### Scheme Registry
35

36
Global registry of scheme handlers used by parsing and serialization functions.
37

38
```typescript { .api }
39
/**
40
 * Global registry of scheme handlers
41
 * Schemes are automatically registered when imported
42
 */
43
const SCHEMES: {[scheme: string]: URISchemeHandler};
44
```
45

46
## Built-in Scheme Handlers
47

48
### HTTP Scheme
49

50
Handler for HTTP URLs with default port normalization and path requirements.
51

52
```typescript { .api }
53
// HTTP scheme handler properties
54
// scheme: "http"
55
// domainHost: true (enables IDN processing)
56
// Default port: 80 (normalized away)
57
// Empty paths become "/"
58
```
59

60
**Usage Examples:**
61

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

65
// HTTP parsing normalizes default port
66
const httpComponents = parse("http://example.com:80/path");
67
console.log(httpComponents.port); // undefined (default port removed)
68

69
// HTTP serialization ensures path presence
70
const httpUri = serialize({
71
  scheme: "http",
72
  host: "example.com"
73
});
74
console.log(httpUri); // "http://example.com/" (path added)
75

76
// HTTP equality with port normalization
77
const isEqual = equal("HTTP://ABC.COM:80", "http://abc.com/");
78
console.log(isEqual); // true
79
```
80

81
### HTTPS Scheme
82

83
Handler for HTTPS URLs extending HTTP behavior with secure port defaults.
84

85
```typescript { .api }
86
// HTTPS scheme handler properties  
87
// scheme: "https"
88
// domainHost: true (enables IDN processing)
89
// Default port: 443 (normalized away)
90
// Empty paths become "/"
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import { parse, serialize, equal } from "uri-js";
97

98
// HTTPS parsing normalizes default secure port
99
const httpsComponents = parse("https://example.com:443/secure");
100
console.log(httpsComponents.port); // undefined (default port removed)
101

102
// HTTPS equality with port normalization
103
const isSecureEqual = equal("https://abc.com", "HTTPS://ABC.COM:443/");
104
console.log(isSecureEqual); // true
105
```
106

107
### WebSocket Scheme (WS)
108

109
Handler for WebSocket URLs with resource name composition and security flags.
110

111
```typescript { .api }
112
interface WSComponents extends URIComponents {
113
  /** Combined path and query for WebSocket resource name */
114
  resourceName?: string;
115
  /** Security flag (false for ws://) */
116
  secure?: boolean;
117
}
118
```
119

120
**Usage Examples:**
121

122
```typescript
123
import { parse, serialize, equal } from "uri-js";
124

125
// WebSocket parsing adds resourceName and secure properties
126
const wsComponents = parse("ws://example.com/chat?room=general");
127
console.log(wsComponents);
128
// {
129
//   scheme: "ws",
130
//   host: "example.com",
131
//   path: "/chat",
132
//   query: "room=general", 
133
//   resourceName: "/chat?room=general",
134
//   secure: false
135
// }
136

137
// WebSocket equality ignores fragments
138
const wsEqual = equal("WS://ABC.COM:80/chat#one", "ws://abc.com/chat");
139
console.log(wsEqual); // true
140
```
141

142
### WebSocket Secure Scheme (WSS)
143

144
Handler for secure WebSocket URLs extending WS behavior with security flags.
145

146
```typescript { .api }
147
// WSS scheme handler properties
148
// scheme: "wss" 
149
// Default port: 443 (normalized away)
150
// secure: true (security flag enabled)
151
// resourceName: path + query combination
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { parse } from "uri-js";
158

159
// WSS parsing sets secure flag
160
const wssComponents = parse("wss://example.com/secure-chat");
161
console.log(wssComponents.secure); // true
162
console.log(wssComponents.resourceName); // "/secure-chat"
163
```
164

165
### Mailto Scheme
166

167
Handler for mailto URLs with email address parsing and header support.
168

169
```typescript { .api }
170
interface MailtoHeaders {
171
  [hfname: string]: string;
172
}
173

174
interface MailtoComponents extends URIComponents {
175
  /** Array of recipient email addresses */
176
  to: Array<string>;
177
  /** Additional email headers */
178
  headers?: MailtoHeaders;
179
  /** Email subject line */
180
  subject?: string;
181
  /** Email body content */
182
  body?: string;
183
}
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
import { parse, serialize } from "uri-js";
190

191
// Mailto parsing extracts email components
192
const mailtoComponents = parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!");
193
console.log(mailtoComponents);
194
// {
195
//   scheme: "mailto",
196
//   to: ["alpha@example.com", "bravo@example.com"],
197
//   subject: "SUBSCRIBE", 
198
//   body: "Sign me up!"
199
// }
200

201
// Mailto serialization with headers
202
const mailtoUri = serialize({
203
  scheme: "mailto",
204
  to: ["alpha@example.com"],
205
  subject: "REMOVE",
206
  body: "Please remove me",
207
  headers: {
208
    cc: "charlie@example.com"
209
  }
210
});
211
console.log(mailtoUri); 
212
// "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me"
213
```
214

215
### URN Scheme
216

217
Handler for Uniform Resource Names with namespace identifier parsing.
218

219
```typescript { .api }
220
interface URNComponents extends URIComponents {
221
  /** Namespace Identifier */
222
  nid?: string;
223
  /** Namespace Specific String */
224
  nss?: string;
225
}
226

227
interface URNOptions extends URIOptions {
228
  nid?: string;
229
}
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
import { parse } from "uri-js";
236

237
// URN parsing extracts namespace components
238
const urnComponents = parse("urn:example:foo");
239
console.log(urnComponents);
240
// {
241
//   scheme: "urn",
242
//   nid: "example",
243
//   nss: "foo"
244
// }
245

246
// More complex URN
247
const complexUrn = parse("urn:isbn:0451450523");
248
console.log(complexUrn);
249
// {
250
//   scheme: "urn", 
251
//   nid: "isbn",
252
//   nss: "0451450523"
253
// }
254
```
255

256
### URN UUID Scheme
257

258
Specialized handler for UUID URNs with UUID validation and parsing.
259

260
```typescript { .api }
261
interface UUIDComponents extends URNComponents {
262
  /** Parsed UUID string */
263
  uuid?: string;
264
}
265
```
266

267
**Usage Examples:**
268

269
```typescript
270
import { parse } from "uri-js";
271

272
// UUID URN parsing extracts UUID
273
const uuidComponents = parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
274
console.log(uuidComponents);
275
// {
276
//   scheme: "urn",
277
//   nid: "uuid", 
278
//   uuid: "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
279
// }
280
```
281

282
## Custom Scheme Implementation
283

284
You can register custom scheme handlers by adding them to the SCHEMES registry:
285

286
```typescript
287
import { SCHEMES, URISchemeHandler, URIComponents, URIOptions } from "uri-js";
288

289
// Example custom scheme handler
290
const customHandler: URISchemeHandler = {
291
  scheme: "custom",
292
  
293
  parse(components: URIComponents, options: URIOptions): URIComponents {
294
    // Custom parsing logic
295
    if (!components.host) {
296
      components.error = components.error || "Custom URIs must have a host.";
297
    }
298
    return components;
299
  },
300
  
301
  serialize(components: URIComponents, options: URIOptions): URIComponents {
302
    // Custom serialization logic
303
    if (components.port === 9999) {
304
      components.port = undefined; // Normalize default port
305
    }
306
    return components;
307
  },
308
  
309
  domainHost: true
310
};
311

312
// Register the custom handler
313
SCHEMES[customHandler.scheme] = customHandler;
314
```
315

316
## Protocol-Specific Features
317

318
### IPv6 and Zone Identifier Support
319

320
All schemes support IPv6 addresses and zone identifiers:
321

322
```typescript
323
import { parse } from "uri-js";
324

325
// IPv6 address parsing
326
const ipv6 = parse("http://[2001:db8::1]/path");
327
console.log(ipv6.host); // "2001:db8::1"
328

329
// IPv6 with zone identifier  
330
const ipv6Zone = parse("http://[2001:db8::7%en1]/path");
331
console.log(ipv6Zone.host); // "2001:db8::7%en1"
332
```
333

334
### Internationalized Domain Names (IDN)
335

336
Schemes with `domainHost: true` support IDN processing:
337

338
```typescript
339
import { parse, serialize } from "uri-js";
340

341
// IDN to ASCII conversion
342
const idnUri = serialize(parse("http://examplé.org/rosé"));
343
console.log(idnUri); // "http://xn--exampl-gva.org/ros%C3%A9"
344

345
// ASCII to IDN conversion with IRI option
346
const iriUri = serialize(parse("http://xn--exampl-gva.org/ros%C3%A9"), { iri: true });
347
console.log(iriUri); // "http://examplé.org/rosé"
348
```
349

350
## Error Handling
351

352
Scheme handlers can add error messages to the components object:
353

354
```typescript
355
import { parse } from "uri-js";
356

357
// HTTP without host generates error
358
const httpError = parse("http:///path");
359
console.log(httpError.error); // "HTTP URIs must have a host."
360

361
// URN with invalid format
362
const urnError = parse("urn:invalid");
363
console.log(urnError.error); // Error message from URN handler
364
```