### Install fast-uri

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Install the fast-uri package using npm.

```bash
npm install fast-uri
```

--------------------------------

### Relative URI Component Example

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/types.md

Represents a URI component that is relative, lacking a scheme or host.

```javascript
{
  scheme: undefined,
  host: undefined,
  path: 'relative/path',
  reference: 'relative',
  error: undefined
}
```

--------------------------------

### HTTP URI Component Example

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/types.md

Represents a parsed HTTP or HTTPS URI with all common components.

```javascript
{
  scheme: 'https',
  userinfo: 'user:pass',
  host: 'example.com',
  port: 8080,
  path: '/path/to/resource',
  query: 'key=value&foo=bar',
  fragment: 'section',
  reference: 'uri',
  error: undefined
}
```

--------------------------------

### Normalizing URIs for Storage with Fast-URI

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Example of normalizing a URI for consistent storage keys using `fastUri.normalize` with options for domain host and Unicode support.

```javascript
function storageKey(uri) {
  return fastUri.normalize(uri, { domainHost: true, unicodeSupport: true })
}
```

--------------------------------

### WebSocket Component Example

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/types.md

Represents a parsed WebSocket URI, including host, port, and resource name. The 'secure' field indicates if it's a secure WebSocket ('wss').

```javascript
{
  scheme: 'wss',
  host: 'chat.example.com',
  port: 443,
  resourceName: '/chat?room=lobby',
  path: undefined,  // reconstructed from resourceName
  query: undefined,  // reconstructed from resourceName
  secure: true,
  reference: 'uri',
  error: undefined
}
```

--------------------------------

### URN Component Example

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/types.md

Represents a parsed URN (Uniform Resource Name) with namespace identifier (nid) and namespace-specific string (nss).

```javascript
{
  scheme: 'urn',
  nid: 'isbn',
  nss: '0451450523',
  reference: 'uri',
  error: undefined
}
```

--------------------------------

### API Reference Suite Overview

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/INDEX.md

The API reference suite for Fastify URI is organized into multiple files, each detailing specific aspects of the library's functionality. These documents include function signatures, import statements, detailed descriptions, parameter tables, return type documentation, error references, and usage examples.

```APIDOC
## API Reference Suite

Each API reference document follows the same structure:

1. Function signature
2. Import statement
3. Detailed description
4. Parameters table
5. Return type documentation
6. Error/exception reference
7. Multiple usage examples
8. Related functions
```

--------------------------------

### Malformed URI Preservation Examples

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-normalize.md

Shows examples of malformed URIs that are returned unchanged by the normalization function, such as invalid ports or authorities.

```javascript
const normalized = fastUri.normalize('http://example.com:99999')
console.log(normalized)  // 'http://example.com:99999' (unchanged, port invalid)

const normalized2 = fastUri.normalize('http://example.com@notapath')
console.log(normalized2)  // 'http://example.com@notapath' (unchanged, malformed authority)
```

--------------------------------

### URI Path Merging Example

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/types.md

Demonstrates merging a relative path with a base path. If the relative path is absolute, it's used directly. Otherwise, it's merged by removing the last segment of the base path and appending the relative path, followed by dot segment removal.

```plaintext
base = '/a/b/c'
relative = '../d'
merged = '/a/d'
```

--------------------------------

### Serialization as Suffix Reference

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Serialize a URI as a suffix reference by omitting the scheme and using the `reference: 'suffix'` option. This results in a URI starting with '//'.

```javascript
const uri = fastUri.serialize(
  {
    scheme: 'http',
    host: 'example.com',
    path: '/path'
  },
  { reference: 'suffix' }
)
console.log(uri)  // '//example.com/path' (no scheme)
```

--------------------------------

### schemes.md

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/INDEX.md

Comprehensive documentation for various URI schemes supported by Fastify URI, including rules for HTTP, HTTPS, WebSocket, URN, and custom schemes, along with practical examples.

```APIDOC
## schemes.md

**Purpose:** Comprehensive scheme documentation
- Handler architecture
- HTTP/HTTPS rules
- WebSocket rules (RFC 6455)
- URN rules (RFC 2141)
- URN:UUID rules (RFC 4122)
- Custom scheme handling
- Practical examples per scheme
```

--------------------------------

### Parse URI with Authority-Path Mismatch

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/errors.md

Shows an error when an authority component is present but the path does not start with '/'.

```javascript
const parsed = fastUri.parse('http://example.com@domain')
console.log(parsed.error)  // "URI path must start with \"/\" when authority is present."
```

--------------------------------

### Basic URI Serialization

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Construct a standard URI with scheme, host, path, query, and fragment. Ensure 'fast-uri' is required.

```javascript
const fastUri = require('fast-uri')

const uri = fastUri.serialize({
  scheme: 'https',
  host: 'example.com',
  path: '/path/to/resource',
  query: 'key=value',
  fragment: 'section'
})
console.log(uri)  // 'https://example.com/path/to/resource?key=value#section'
```

--------------------------------

### Define Basic Fast-URI Options

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/types.md

Configure scheme and domain host behavior for URI parsing. Use this to specify an expected scheme or enable domain name interpretation.

```javascript
const options = {
  scheme: 'http',
  domainHost: true
}

const parsed = fastUri.parse('//example.com/path', options)
// Treats the authority as a domain name
```

--------------------------------

### configuration.md

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/INDEX.md

Reference for options and configuration settings in Fastify URI, explaining all configuration options, their use cases, common patterns, and runtime considerations.

```APIDOC
## configuration.md

**Purpose:** Options and configuration reference
- All 8 configuration options explained
- Use cases for each
- Common patterns
- Runtime considerations
- Environment interaction
```

--------------------------------

### utilities-reference.md

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/INDEX.md

Internal implementation reference for Fastify URI, covering utilities for IPv6 handling, path manipulation, percent-encoding, character validation, and authority recomposition.

```APIDOC
## utilities-reference.md

**Purpose:** Internal implementation reference
- IPv6 handling utilities
- Path manipulation (RFC 3986 compliant)
- Percent-encoding strategies
- Character validation functions
- Authority recomposition
- Performance optimizations
- Implementation notes
```

--------------------------------

### Parse and Serialize URI Components

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Demonstrates parsing a URI into its components and serializing components back into a URI string. Ensure the 'fast-uri' module is required.

```javascript
const fastUri = require('fast-uri')

// Parse a URI
const parsed = fastUri.parse('https://user:pass@example.com:8080/path?key=value#section')
console.log(parsed.scheme)  // 'https'
console.log(parsed.host)    // 'example.com'
console.log(parsed.path)    // '/path'

// Serialize components back to a string
const uri = fastUri.serialize({
  scheme: 'https',
  host: 'example.com',
  path: '/api/users'
})
console.log(uri)  // 'https://example.com/api/users'
```

--------------------------------

### URN:UUID Component Example

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/types.md

Represents a parsed URN specifically for UUIDs, including the canonical UUID value.

```javascript
{
  scheme: 'urn',
  nid: 'uuid',
  uuid: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
  nss: undefined,
  reference: 'uri',
  error: undefined
}
```

--------------------------------

### Root-Relative URI Resolution

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve.md

Resolves a relative URI that starts with a slash, indicating it's relative to the root of the authority.

```javascript
const resolved = fastUri.resolve('http://example.com/a/b/c', '/root/path')
console.log(resolved)  // 'http://example.com/root/path'
```

--------------------------------

### Parse and Serialize HTTP/HTTPS URIs

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/schemes.md

Demonstrates parsing an HTTPS URI with userinfo, host, port, path, query, and fragment. Also shows serialization of an HTTPS URI, including default port removal and root path normalization for HTTP URIs.

```javascript
const fastUri = require('fast-uri')

// Parse HTTP URI
const parsed = fastUri.parse('https://user:pass@example.com:8080/path?q=1#frag')
// Result:
// {
//   scheme: 'https',
//   userinfo: 'user:pass',
//   host: 'example.com',
//   port: 8080,
//   path: '/path',
//   query: 'q=1',
//   fragment: 'frag'
// }
```

```javascript
// Serialize with default port removal
const uri = fastUri.serialize({
  scheme: 'https',
  host: 'example.com',
  port: 443,
  path: '/secure'
})
// Result: 'https://example.com/secure' (port 443 omitted)
```

```javascript
// Root path normalization
const uri2 = fastUri.serialize({
  scheme: 'http',
  host: 'example.com'
})
// Result: 'http://example.com/' (path set to '/')
```

--------------------------------

### File-Style Path Resolution

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve.md

Demonstrates resolution with URIs using the 'file://' scheme.

```javascript
const resolved = fastUri.resolve('file:///home/user/docs/readme.txt', './other.txt')
console.log(resolved)  // 'file:///home/user/docs/other.txt'
```

--------------------------------

### Absolute Path in Relative URI

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve.md

Resolves a relative URI that starts with an absolute path. The base URI's path is replaced entirely.

```javascript
const resolved = fastUri.resolve('http://example.com/a/b/c', '/x/y/z')
console.log(resolved)  // 'http://example.com/x/y/z'
```

--------------------------------

### Relative URI Comparison

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-equal.md

Compares relative URIs. Scheme-relative URIs (starting with '//') are compared case-insensitively for host. Other relative paths are compared case-sensitively.

```javascript
const isEqual = fastUri.equal(
  '//example.com/path',
  '//example.com/path'
)
console.log(isEqual)  // true

const notEqual = fastUri.equal(
  './relative',
  './relative'
)
console.log(notEqual)  // false (comparison is case-sensitive for relative paths)
```

--------------------------------

### Comparison with Options

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-equal.md

Allows for advanced comparison options, such as enabling IDN domain host comparison.

```APIDOC
## fastUri.equal(uri1, uri2, options)

### Description
Compares two URIs for equality with additional options.

### Method
`equal`

### Parameters
- **uri1** (string | object) - The first URI to compare.
- **uri2** (string | object) - The second URI to compare.
- **options** (object) - Optional configuration for comparison.
  - **domainHost** (boolean) - If true, compares Internationalized Domain Names (IDNs) by converting them to punycode before comparison. Defaults to `false`.

### Request Example
```javascript
const isEqual = fastUri.equal(
  'http://münchen.de/path',
  'http://xn--mnchen-3ya.de/path',
  { domainHost: true }
)
console.log(isEqual) // true
```

### Response
- **boolean** - Returns `true` if the URIs are equal after normalization and considering options, `false` otherwise.
```

--------------------------------

### Building URIs Programmatically with Fast-URI

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Constructs a URI string from its components using `fastUri.serialize`. Demonstrates serialization of scheme, host, path, query, and fragment.

```javascript
const component = {
  scheme: 'https',
  host: 'api.example.com',
  path: '/v1/users',
  query: 'page=1&limit=10',
  fragment: 'results'
}

const uri = fastUri.serialize(component)
// 'https://api.example.com/v1/users?page=1&limit=10#results'
```

--------------------------------

### resolveComponent with Relative URI and Scheme

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Illustrates how a relative URI with its own scheme and host takes full control during resolution when tolerant is false.

```APIDOC
## resolveComponent with Relative URI and Scheme

### Description
Resolves a relative URI component against a base URI. When `tolerant` is false, a relative URI with its own scheme and host takes precedence.

### Parameters
- **baseComponent** (object) - The base URI component.
- **relativeComponent** (object) - The relative URI component to resolve.
- **options** (object) - Options for resolution. Set `tolerant: false` to enable this behavior.

### Request Example
```javascript
const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a' },
  { scheme: 'https', host: 'other.com', path: '/b' },
  { tolerant: false }
)
console.log(resolved)
```

### Response Example
```json
{
  "scheme": "https",
  "host": "other.com",
  "path": "/b",
  "...": "..."
}
```
```

--------------------------------

### Case-Insensitive Scheme and Host Comparison

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-equal.md

Demonstrates that scheme and host components are compared case-insensitively. Other components are case-sensitive.

```javascript
const isEqual = fastUri.equal('HTTP://EXAMPLE.COM/PATH', 'http://example.com/path')
console.log(isEqual)  // true (scheme and host are lowercased)
```

--------------------------------

### Handle URN Serialization Error

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Calling serialize on a URN component without a namespace identifier (nid) will throw an error. This example demonstrates how to catch and log this specific error message.

```javascript
try {
  fastUri.serialize({ scheme: 'urn', nss: '0451450523' })
} catch (e) {
  console.log(e.message)  // "URN without nid cannot be serialized"
}
```

--------------------------------

### Basic Serialization

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Serializes a URI object with scheme, host, path, query, and fragment into a standard URI string.

```APIDOC
## serialize

### Description
Serializes a URI object into a standard URI string.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scheme** (string) - Required - The URI scheme (e.g., 'https', 'http').
- **host** (string) - Required - The host name or IP address.
- **path** (string) - Optional - The path component of the URI.
- **query** (string) - Optional - The query string component of the URI.
- **fragment** (string) - Optional - The fragment identifier of the URI.

### Request Example
```javascript
const fastUri = require('fast-uri')

const uri = fastUri.serialize({
  scheme: 'https',
  host: 'example.com',
  path: '/path/to/resource',
  query: 'key=value',
  fragment: 'section'
})
console.log(uri)  // 'https://example.com/path/to/resource?key=value#section'
```

### Response
#### Success Response (200)
- **uri** (string) - The serialized URI string.

#### Response Example
```json
{
  "uri": "https://example.com/path/to/resource?key=value#section"
}
```
```

--------------------------------

### resolveComponent Basic Usage

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Demonstrates the basic resolution of a relative path component against a base URI.

```APIDOC
## resolveComponent

### Description
Resolves a relative URI component against a base URI component.

### Parameters
- **baseComponent** (object) - The base URI component.
- **relativeComponent** (object) - The relative URI component to resolve.
- **options** (object) - Options for resolution.
- **skipNormalization** (boolean, optional) - If true, skips normalization steps.

### Request Example
```javascript
const fastUri = require('fast-uri')

const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a/b/c' },
  { path: '../d' },
  {}
)
console.log(resolved)
```

### Response Example
```json
{
  "scheme": "http",
  "host": "example.com",
  "path": "/a/d",
  "...": "..."
}
```
```

--------------------------------

### Fast-URI Exports for Different Environments

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Demonstrates how to import Fast-URI in CommonJS (Node.js) environments using require, including named and default export patterns.

```javascript
// CommonJS (Node.js)
const fastUri = require('fast-uri')

// Named exports
const { parse, serialize, normalize, resolve, equal } = require('fast-uri')

// Default export
const fastUri = require('fast-uri').default
```

--------------------------------

### Import and Use equal()

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-equal.md

Import the equal function from the fast-uri library and use it to compare two URIs. The comparison is case-insensitive.

```javascript
const fastUri = require('fast-uri')
const isEqual = fastUri.equal('http://example.com/path', 'HTTP://EXAMPLE.COM/path')
```

--------------------------------

### Error Cases Demonstration

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-parse.md

Demonstrates how the parser reports validation errors for malformed URIs, such as out-of-range ports, missing hosts for HTTP schemes, and incorrect path formatting when authority is present.

```javascript
// Port out of range
const parsed = fastUri.parse('http://example.com:99999')
console.log(parsed.error)  // "URI port is malformed."

// Missing host for HTTP
const parsed2 = fastUri.parse('http:///path')
console.log(parsed2.error)  // "HTTP URIs must have a host."

// Authority without leading slash in path
const parsed3 = fastUri.parse('http://example.com@domain')
console.log(parsed3.error)  // "URI path must start with "/" when authority is present."
```

--------------------------------

### Basic URI Equality

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-equal.md

Compares two identical URIs for equality. Requires importing the fast-uri module.

```javascript
const fastUri = require('fast-uri')

const isEqual = fastUri.equal('http://example.com/path', 'http://example.com/path')
console.log(isEqual)  // true
```

--------------------------------

### Domain Host / IDN Conversion

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-parse.md

Shows how to enable Internationalized Domain Name (IDN) conversion to Punycode.

```APIDOC
## fasturi.parse(uri, [options])

### Description
Enables Punycode conversion for domain names.

### Method
`parse(uri: string, options: { domainHost: true }): object`

### Parameters
#### Path Parameters
- **uri** (string) - Required - The URI string with an internationalized domain name.
- **options** (object) - Required - Must include `domainHost: true`.

### Response
#### Success Response
The `host` field will contain the Punycode representation of the domain name.

#### Response Example
```json
{
  "scheme": "http",
  "host": "xn--mnchen-3ya.de",
  "port": undefined,
  "path": "/",
  "reference": "uri",
  "error": undefined
}
```
```

--------------------------------

### Configure URI Parsing with Domain Support

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Enables domain name support (IDN to ASCII conversion) during URI parsing by passing the `domainHost: true` option.

```javascript
const fastUri = require('fast-uri')

// Parse with domain name support (IDN to ASCII conversion)
const parsed = fastUri.parse('http://münchen.de/', { domainHost: true })
console.log(parsed.host)  // 'xn--mnchen-3ya.de'
```

--------------------------------

### Basic URI Comparison

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-equal.md

Compares two simple URIs for equality. The comparison is case-insensitive for scheme and host, and normalizes default ports.

```APIDOC
## fastUri.equal(uri1, uri2)

### Description
Compares two URIs for equality, performing necessary normalizations.

### Method
`equal`

### Parameters
- **uri1** (string | object) - The first URI to compare.
- **uri2** (string | object) - The second URI to compare.

### Request Example
```javascript
const fastUri = require('fast-uri')
const isEqual = fastUri.equal('http://example.com/path', 'http://example.com/path')
console.log(isEqual) // true
```

### Response
- **boolean** - Returns `true` if the URIs are equal after normalization, `false` otherwise.
```

--------------------------------

### Authority with Port

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Demonstrates how to include userinfo and a specific port in the authority component of a URI.

```APIDOC
## serialize

### Description
Serializes a URI object including userinfo and a specific port in the authority.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scheme** (string) - Required - The URI scheme.
- **userinfo** (string) - Optional - User information for authentication (e.g., 'user:pass').
- **host** (string) - Required - The host name or IP address.
- **port** (number) - Optional - The port number.
- **path** (string) - Optional - The path component.

### Request Example
```javascript
const uri = fastUri.serialize({
  scheme: 'http',
  userinfo: 'user:pass',
  host: 'example.com',
  port: 8080,
  path: '/api'
})
console.log(uri)  // 'http://user:pass@example.com:8080/api'
```

### Response
#### Success Response (200)
- **uri** (string) - The serialized URI string.

#### Response Example
```json
{
  "uri": "http://user:pass@example.com:8080/api"
}
```
```

--------------------------------

### Main Fast-URI Exports

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Import and use the primary functions for URI manipulation: parse, serialize, normalize, resolve, and equal. Access built-in scheme handlers via SCHEMES.

```javascript
const fastUri = require('fast-uri')

fastUri.parse(uri, opts)                    // Parse URI string
fastUri.serialize(component, opts)          // Serialize component to string
fastUri.normalize(uri, opts)                // Normalize URI
fastUri.resolve(baseURI, relativeURI, opts) // Resolve relative URI
fastUri.resolveComponent(...)
fastUri.equal(uriA, uriB, opts)             // Compare URIs
fastUri.SCHEMES                              // Built-in scheme handlers (read-only)
```

--------------------------------

### resolveComponent with Skip Normalization

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Demonstrates how to skip the normalization process by passing `true` as the fourth argument.

```APIDOC
## resolveComponent with Skip Normalization

### Description
Resolves a relative URI component against a base URI, skipping the default normalization process. This is faster but assumes components are already well-formed.

### Parameters
- **baseComponent** (object) - The base URI component.
- **relativeComponent** (object) - The relative URI component to resolve.
- **options** (object) - Options for resolution.
- **skipNormalization** (boolean) - Set to `true` to skip normalization.

### Request Example
```javascript
const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a/b' },
  { path: '../c' },
  {},
  true  // skipNormalization
)
console.log(resolved)
```

### Response Example
```json
{
  "scheme": "http",
  "host": "example.com",
  "path": "/a/c",
  "...": "..."
}
```
```

--------------------------------

### Basic URI Parsing

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-parse.md

Parses a standard absolute URI with userinfo, host, port, path, query, and fragment.

```APIDOC
## fasturi.parse(uri, [options])

### Description
Parses a given URI string into its components.

### Method
`parse(uri: string, options?: object): object`

### Parameters
#### Path Parameters
- **uri** (string) - Required - The URI string to parse.
- **options** (object) - Optional - Configuration options for parsing.
  - **domainHost** (boolean) - Optional - If true, attempts to convert Internationalized Domain Names (IDNs) to Punycode.
  - **reference** (string) - Optional - Specifies the expected type of URI reference ('uri', 'relative', 'absolute', 'urn').

### Response
#### Success Response
Returns an object containing the parsed URI components. The structure includes fields like `scheme`, `userinfo`, `host`, `port`, `path`, `query`, `fragment`, `reference`, and `error`.

#### Response Example
```json
{
  "scheme": "https",
  "userinfo": "user:pass",
  "host": "example.com",
  "port": 8080,
  "path": "/path/to/resource",
  "query": "key=value",
  "fragment": "section",
  "reference": "uri",
  "error": undefined
}
```
```

--------------------------------

### WebSocket Serialization

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Demonstrates serialization for WebSocket URIs (ws:// or wss://), including resource names and secure flag.

```APIDOC
## serialize

### Description
Serializes a WebSocket URI (ws or wss), optionally including security context.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scheme** (string) - Required - 'ws' or 'wss'.
- **host** (string) - Required - The WebSocket server host.
- **resourceName** (string) - Optional - The resource path and query for the WebSocket connection.
- **secure** (boolean) - Optional - Indicates if the connection is secure (redundant if scheme is 'wss').

### Request Example
```javascript
const uri = fastUri.serialize({
  scheme: 'wss',
  host: 'chat.example.com',
  resourceName: '/chat?room=lobby',
  secure: true
})
console.log(uri)  // 'wss://chat.example.com/chat?room=lobby'
```

### Response
#### Success Response (200)
- **uri** (string) - The serialized WebSocket URI string.

#### Response Example
```json
{
  "uri": "wss://chat.example.com/chat?room=lobby"
}
```
```

--------------------------------

### Fast-URI Usage in TypeScript

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Shows how to import and use Fast-URI with default import syntax in a TypeScript project. Type definitions are available in `types/index.d.ts`.

```typescript
import fastUri from 'fast-uri'

const parsed = fastUri.parse('http://example.com')
```

--------------------------------

### resolveComponent with Current Directory Reference

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Shows how a current directory reference ('./') in the relative path is handled.

```APIDOC
## resolveComponent with Current Directory Reference

### Description
Resolves a relative URI component against a base URI, correctly handling a current directory reference ('./') in the relative path.

### Parameters
- **baseComponent** (object) - The base URI component.
- **relativeComponent** (object) - The relative URI component to resolve.
- **options** (object) - Options for resolution.

### Request Example
```javascript
const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a/b/c' },
  { path: './' },
  {}
)
console.log(resolved)
```

### Response Example
```json
{
  "scheme": "http",
  "host": "example.com",
  "path": "/a/b/",
  "...": "..."
}
```
```

--------------------------------

### Import and Resolve URI

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve.md

Import the fast-uri library and use the resolve function to combine a base URI with a relative URI. This is the primary way to use the resolve functionality.

```javascript
const fastUri = require('fast-uri')
const resolved = fastUri.resolve('http://example.com/a/b/c', '../d')
```

--------------------------------

### URN Parsing

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-parse.md

Demonstrates parsing a Uniform Resource Name (URN) with a namespace identifier and specific string.

```APIDOC
## fasturi.parse(uri, [options])

### Description
Parses a URN.

### Method
`parse(uri: string, options?: object): object`

### Parameters
#### Path Parameters
- **uri** (string) - Required - The URN string to parse.

### Response
#### Success Response
URNs are parsed into `nid` (namespace identifier) and `nss` (namespace specific string) fields.

#### Response Example
```json
{
  "scheme": "urn",
  "nid": "isbn",
  "nss": "0451450523",
  "path": undefined,
  "reference": "uri",
  "error": undefined
}
```
```

--------------------------------

### Consistent Options with Variables

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/configuration.md

Since fast-uri has no global configuration, store frequently used options in a variable for consistent application across multiple function calls.

```javascript
const MY_OPTIONS = { domainHost: true, tolerant: false }

const parsed1 = fastUri.parse(uri1, MY_OPTIONS)
const parsed2 = fastUri.parse(uri2, MY_OPTIONS)
```

--------------------------------

### resolveComponent with Empty Base Path

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Shows how a leading slash is added to a relative path when the base URI has an empty path and an authority.

```APIDOC
## resolveComponent with Empty Base Path

### Description
Resolves a relative URI component against a base URI that has an empty path. A leading slash is added to the relative path if an authority is present.

### Parameters
- **baseComponent** (object) - The base URI component.
- **relativeComponent** (object) - The relative URI component to resolve.
- **options** (object) - Options for resolution.

### Request Example
```javascript
const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com' },
  { path: 'relative/path' },
  {}
)
console.log(resolved)
```

### Response Example
```json
{
  "scheme": "http",
  "host": "example.com",
  "path": "/relative/path",
  "...": "..."
}
```
```

--------------------------------

### WebSocket URI Parsing

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/schemes.md

Demonstrates how to parse a WebSocket URI using `fastUri.parse()`. It shows how the library handles schemes, authority, resource names, and security flags, and how fragments are removed.

```APIDOC
## fastUri.parse(uri: string)

### Description
Parses a WebSocket URI (ws or wss) and returns an object with its components. It specifically handles WebSocket-specific rules like combining path and query into `resourceName` and removing fragments.

### Method
`parse`

### Parameters
#### Path Parameters
- **uri** (string) - Required - The WebSocket URI string to parse.

### Response
#### Success Response (Object)
- **scheme** (string) - The URI scheme ('ws' or 'wss').
- **host** (string) - The domain host of the URI.
- **port** (number) - The port number of the URI.
- **resourceName** (string) - The combined path and query of the URI.
- **path** (undefined) - Always undefined after parsing WebSocket URIs.
- **query** (undefined) - Always undefined after parsing WebSocket URIs.
- **secure** (boolean) - True if the scheme is 'wss' or if explicitly set to true.
- **fragment** (undefined) - Always undefined as fragments are removed.

### Request Example
```javascript
const fastUri = require('fast-uri')
const parsed = fastUri.parse('wss://chat.example.com:443/chat?room=lobby#ignored')
// parsed will be:
// {
//   scheme: 'wss',
//   host: 'chat.example.com',
//   port: 443,
//   resourceName: '/chat?room=lobby',
//   path: undefined,
//   query: undefined,
//   secure: true,
//   fragment: undefined
// }
```
```

--------------------------------

### Userinfo Comparison

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-equal.md

Compares URIs based on their userinfo component. Identical userinfo results in equality, while different userinfo results in inequality.

```javascript
const isEqual = fastUri.equal(
  'http://user:pass@example.com/path',
  'http://user:pass@example.com/path'
)
console.log(isEqual)  // true

const notEqual = fastUri.equal(
  'http://user1:pass@example.com/path',
  'http://user2:pass@example.com/path'
)
console.log(notEqual)  // false (different userinfo)
```

--------------------------------

### Handle Host as Domain Name (IDN to ASCII)

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/configuration.md

The 'domainHost' option treats the host component as a domain name, converting International Domain Names (IDN) to ASCII (punycode) per RFC 5891. This is useful for ensuring compatibility with ASCII-only systems.

```javascript
const fastUri = require('fast-uri')

// Without domainHost
const parsed1 = fastUri.parse('http://münchen.de/')
console.log(parsed1.host)  // 'münchen.de' (unchanged)

// With domainHost
const parsed2 = fastUri.parse('http://münchen.de/', { domainHost: true })
console.log(parsed2.host)  // 'xn--mnchen-3ya.de' (punycode)

// Failed conversion
const parsed3 = fastUri.parse('http://invalid-domain/', { domainHost: true })
// May set error if conversion fails (rare with valid domains)
```

--------------------------------

### Import and Normalize URI

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-normalize.md

Import the fast-uri library and use the normalize function to process a given URI string. This is the primary way to use the normalization functionality.

```javascript
const fastUri = require('fast-uri')
const normalized = fastUri.normalize('http://example.com/a%2Fb')
```

--------------------------------

### Parse and Serialize URN:UUID with Fast-URI

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/schemes.md

Demonstrates parsing a valid URN:UUID, including case normalization, and serializing a UUID back into a URN. Also shows error handling for invalid UUIDs and the behavior in tolerant mode.

```javascript
const fastUri = require('fast-uri')

// Parse valid UUID
const parsed = fastUri.parse('urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479')
// Result:
// {
//   scheme: 'urn',
//   nid: 'uuid',
//   uuid: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
//   nss: undefined
// }
```

```javascript
// UUID case normalization
const parsed2 = fastUri.parse('urn:uuid:F47AC10B-58CC-4372-A567-0E02B2C3D479')
console.log(parsed2.uuid)  // 'f47ac10b-58cc-4372-a567-0e02b2c3d479' (lowercase)
```

```javascript
// Invalid UUID (default: error)
const parsed3 = fastUri.parse('urn:uuid:not-a-uuid')
console.log(parsed3.error)  // "UUID is not valid."
```

```javascript
// Invalid UUID (tolerant mode)
const parsed4 = fastUri.parse('urn:uuid:not-a-uuid', { tolerant: true })
console.log(parsed4.error)  // undefined (no error in tolerant mode)
```

```javascript
// Serialize UUID
const uri = fastUri.serialize({
  scheme: 'urn',
  nid: 'uuid',
  uuid: 'F47AC10B-58CC-4372-A567-0E02B2C3D479'
})
// Result: 'urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479'
```

--------------------------------

### Comparing Canonical URIs with Fast-URI

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Compares two URIs for canonical equality using `fastUri.equal` with the `domainHost: true` option for accurate comparison.

```javascript
function isSameResource(uri1, uri2) {
  return fastUri.equal(uri1, uri2, { domainHost: true })
}
```

--------------------------------

### Fast-uri Benchmark Results

Source: https://github.com/fastify/fast-uri/blob/main/README.md

Benchmark results for fast-uri, showing average and median latency and throughput for various URI parsing and serialization tasks. These results can be used to compare performance against other libraries.

```bash
fast-uri benchmark
```

--------------------------------

### Suffix Reference (no scheme/authority)

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Demonstrates creating a URI reference string without a scheme or authority using the `reference: 'suffix'` option.

```APIDOC
## serialize

### Description
Serializes a URI object into a reference string, omitting the scheme and authority if present, using the `reference: 'suffix'` option.

### Parameters
#### Path Parameters
None

#### Query Parameters
- **reference** (string) - Optional - If set to 'suffix', serializes as a reference string without scheme/authority.

#### Request Body
- **scheme** (string) - Optional - The URI scheme.
- **host** (string) - Optional - The host name.
- **path** (string) - Optional - The path component.

### Request Example
```javascript
const uri = fastUri.serialize(
  {
    scheme: 'http',
    host: 'example.com',
    path: '/path'
  },
  { reference: 'suffix' }
)
console.log(uri)  // '//example.com/path' (no scheme)
```

### Response
#### Success Response (200)
- **uri** (string) - The serialized URI reference string.

#### Response Example
```json
{
  "uri": "//example.com/path"
}
```
```

--------------------------------

### IPv6 Address Parsing

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-parse.md

Shows how IPv6 addresses within brackets are parsed correctly, including the port.

```APIDOC
## fasturi.parse(uri, [options])

### Description
Parses a URI containing an IPv6 address.

### Method
`parse(uri: string, options?: object): object`

### Parameters
#### Path Parameters
- **uri** (string) - Required - The URI string with an IPv6 address.

### Response
#### Success Response
The `host` field will contain the normalized IPv6 address.

#### Response Example
```json
{
  "scheme": "http",
  "host": "2001:db8::1",
  "port": 8080,
  "path": "/path",
  "reference": "uri",
  "error": undefined
}
```
```

--------------------------------

### Basic Component Resolution

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Resolves a relative path component against a base URI. By default, normalization is applied, ensuring consistent component parsing.

```javascript
const fastUri = require('fast-uri')

const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a/b/c' },
  { path: '../d' },
  {}
)
console.log(resolved)
// Output:
// {
//   scheme: 'http',
//   host: 'example.com',
//   path: '/a/d',
//   ...
// }
```

--------------------------------

### HTTP and HTTPS Scheme Handling

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/schemes.md

Details the characteristics and specific parsing/serialization rules for HTTP and HTTPS URIs, including authority, default ports, domain host support, and path normalization.

```APIDOC
## HTTP (RFC 2616) and HTTPS (RFC 2818)

### Description
Handles URIs with the `http` and `https` schemes, supporting authority, default ports, domain names (including IDN), and path normalization.

### Characteristics
- **Scheme names**: `http`, `https`
- **Authority**: Required (must have a host)
- **Default ports**: 80 (http), 443 (https)
- **Domain host**: Yes (domains are supported; IDN conversion available)
- **Path normalization**: Yes (dot segments removed)

### HTTP-Specific Rules

**Parsing (`httpParse`):**
- Validates that a host component is present.
- If missing, sets error: "HTTP URIs must have a host."

**Serialization (`httpSerialize`):**
- Removes default ports from the output:
  - Port 80 for http URIs
  - Port 443 for https URIs
  - Empty string ports (`''`) are also removed.
- Normalizes empty paths to `/` (the root path).
  - Input: `{ scheme: 'http', host: 'example.com' }`
  - Output: `http://example.com/`

### Request Example
```javascript
const fastUri = require('fast-uri')

// Parse HTTP URI
const parsed = fastUri.parse('https://user:pass@example.com:8080/path?q=1#frag')
// Result:
// {
//   scheme: 'https',
//   userinfo: 'user:pass',
//   host: 'example.com',
//   port: 8080,
//   path: '/path',
//   query: 'q=1',
//   fragment: 'frag'
// }

// Serialize with default port removal
const uri = fastUri.serialize({
  scheme: 'https',
  host: 'example.com',
  port: 443,
  path: '/secure'
})
// Result: 'https://example.com/secure' (port 443 omitted)

// Root path normalization
const uri2 = fastUri.serialize({
  scheme: 'http',
  host: 'example.com'
})
// Result: 'http://example.com/' (path set to '/')
```
```

--------------------------------

### parse(uri, opts)

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-parse.md

Parses a URI string into its component parts according to RFC 3986. It breaks down a URI into its constituent components: scheme, authority (userinfo, host, port), path, query, and fragment. Special schemes like http, https, ws, wss, urn, and urn:uuid have scheme-specific parsing rules applied.

```APIDOC
## Function Signature
```javascript
parse(uri: string, opts?: Options): URIComponent
```

## Import
```javascript
const fastUri = require('fast-uri')
const parsed = fastUri.parse('https://example.com/path')
```

## Parameters
#### Path Parameters
- **uri** (string) - Required - The URI string to parse
- **opts** (Options) - Optional - Parsing options object

## Options Parameter Details
#### Query Parameters
- **scheme** (string) - Optional - Override the detected scheme; useful for parsing URI references without a scheme
- **reference** (string) - Optional - Validate that the URI matches a specific reference type: 'same-document', 'relative', 'absolute', or 'uri'
- **unicodeSupport** (boolean) - Optional - If true, the parser unescapes non-ASCII characters in the output as per RFC 3987
- **domainHost** (boolean) - Optional - If true, treat the host as a domain name and convert IDNs (International Domain Names) as per RFC 5891
- **tolerant** (boolean) - Optional - If true, the parser relaxes validation rules (e.g., allows invalid UUIDs in urn:uuid)
- **nid** (string) - Optional - For URN parsing, override the namespace identifier
```

--------------------------------

### URI Serialization with Port and Userinfo

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-serialize.md

Serialize a URI including userinfo and a non-default port number in the authority component.

```javascript
const uri = fastUri.serialize({
  scheme: 'http',
  userinfo: 'user:pass',
  host: 'example.com',
  port: 8080,
  path: '/api'
})
console.log(uri)  // 'http://user:pass@example.com:8080/api'
```

--------------------------------

### Resolution with Multiple Dot Segments

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Handles resolution of relative paths containing multiple '..' segments, correctly navigating the directory structure.

```javascript
const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a/b/c/d' },
  { path: '../../x/y' },
  {}
)
console.log(resolved)
// Output:
// {
//   scheme: 'http',
//   host: 'example.com',
//   path: '/a/x/y',
//   ...
// }
```

--------------------------------

### uri-js Benchmark Results

Source: https://github.com/fastify/fast-uri/blob/main/README.md

Benchmark results for uri-js, detailing average and median latency and throughput for different URI operations. This data is useful for performance comparisons.

```bash
uri-js benchmark
```

--------------------------------

### URI Comparison

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/README.md

Compares two URIs for equivalence, considering normalization rules.

```APIDOC
## fastUri.equal(uri1, uri2, [options])

### Description
Compares two URIs to determine if they are equivalent.

### Parameters
#### Path Parameters
- **uri1** (string) - Required - The first URI to compare.
- **uri2** (string) - Required - The second URI to compare.
- **options** (object) - Optional - Configuration options for comparison.

### Request Example
```javascript
const fastUri = require('fast-uri')
const equal = fastUri.equal('HTTP://EXAMPLE.COM/', 'http://example.com:443/')
console.log(equal) // true (if https) or depends on scheme defaults
```
```

--------------------------------

### resolveComponent with Path Inheritance

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Illustrates how query parameters are inherited from the base URI when not present in the relative component.

```APIDOC
## resolveComponent with Path Inheritance

### Description
Resolves a relative URI component against a base URI, showing how query parameters are inherited if not specified in the relative component.

### Parameters
- **baseComponent** (object) - The base URI component.
- **relativeComponent** (object) - The relative URI component to resolve.
- **options** (object) - Options for resolution.

### Request Example
```javascript
const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a/b/c', query: 'old=1' },
  { path: 'd' },
  {}
)
console.log(resolved)
```

### Response Example
```json
{
  "scheme": "http",
  "host": "example.com",
  "path": "/a/b/d",
  "query": "old=1",
  "...": "..."
}
```
```

--------------------------------

### resolveComponent with Absolute Path

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve-component.md

Demonstrates how an absolute path in the relative component replaces the base path.

```APIDOC
## resolveComponent with Absolute Path

### Description
Resolves a relative URI component against a base URI, where the relative component contains an absolute path that replaces the base path.

### Parameters
- **baseComponent** (object) - The base URI component.
- **relativeComponent** (object) - The relative URI component to resolve.
- **options** (object) - Options for resolution.

### Request Example
```javascript
const resolved = fastUri.resolveComponent(
  { scheme: 'http', host: 'example.com', path: '/a/b/c' },
  { path: '/x/y/z' },
  {}
)
console.log(resolved)
```

### Response Example
```json
{
  "scheme": "http",
  "host": "example.com",
  "path": "/x/y/z",
  "...": "..."
}
```
```

--------------------------------

### Empty Base Path Resolution

Source: https://github.com/fastify/fast-uri/blob/main/_autodocs/api-reference-resolve.md

Resolves a relative path against a base URI that has an empty path component.

```javascript
const resolved = fastUri.resolve('http://example.com', 'relative/path')
console.log(resolved)  // 'http://example.com/relative/path'
```