Core URI Operations

/**
 * Parse a URI string into component parts
 * @param uriString - The URI string to parse
 * @param options - Optional parsing configuration
 * @returns Parsed URI components object
 */
function parse(uriString: string, options: URIOptions = {}): URIComponents;

import { parse } from "uri-js";

// Basic URI parsing
const components = parse("https://user:pass@example.com:8443/path/to/resource?query=value&foo=bar#section");
console.log(components);
// {
//   scheme: "https",
//   userinfo: "user:pass",
//   host: "example.com", 
//   port: 8443,
//   path: "/path/to/resource",
//   query: "query=value&foo=bar",
//   fragment: "section",
//   reference: "uri"
// }

// Parse with IRI support
const iriComponents = parse("http://examplé.org/rosé", { iri: true });
console.log(iriComponents.host); // "examplé.org"

// Parse with unicode support
const unicodeComponents = parse("http://xn--exampl-gva.org/ros%C3%A9", { unicodeSupport: true });

// Parse relative URI
const relativeComponents = parse("../path/file.html");
console.log(relativeComponents.reference); // "relative"

/**
 * Convert URI components to a URI string
 * @param components - The URI components to serialize
 * @param options - Optional serialization configuration
 * @returns Serialized URI string
 */
function serialize(components: URIComponents, options: URIOptions = {}): string;

import { serialize } from "uri-js";

// Basic serialization
const uri = serialize({
  scheme: "https",
  host: "api.example.com",
  path: "/v1/users",
  query: "limit=10&offset=0"
});
console.log(uri); // "https://api.example.com/v1/users?limit=10&offset=0"

// Serialize with IRI output
const iriUri = serialize({
  scheme: "http",
  host: "xn--exampl-gva.org",
  path: "/ros%C3%A9"
}, { iri: true });
console.log(iriUri); // "http://examplé.org/rosé"

// Serialize with domain host processing
const domainUri = serialize({
  scheme: "http",
  host: "examplé.org"
}, { domainHost: true });

/**
 * Resolve a relative URI against a base URI
 * @param baseURI - The base URI string
 * @param relativeURI - The relative URI string to resolve
 * @param options - Optional resolution configuration
 * @returns Resolved absolute URI string
 */
function resolve(baseURI: string, relativeURI: string, options?: URIOptions): string;

import { resolve } from "uri-js";

// Basic resolution
const resolved = resolve("http://example.com/a/b/c/d", "../../g");
console.log(resolved); // "http://example.com/a/g"

// Resolve with query parameters
const withQuery = resolve("http://example.com/path", "?newquery");
console.log(withQuery); // "http://example.com/path?newquery"

// Resolve with fragments
const withFragment = resolve("http://example.com/path", "#section");
console.log(withFragment); // "http://example.com/path#section"

// Complex path resolution
const complex = resolve("http://example.com/a/b/c/", "../d/./e/../f");
console.log(complex); // "http://example.com/a/b/d/f"

/**
 * Normalize a URI string to canonical form
 * @param uri - The URI string to normalize
 * @param options - Optional normalization configuration
 * @returns Normalized URI string
 */
function normalize(uri: string, options?: URIOptions): string;

/**
 * Normalize URI components to canonical form
 * @param uri - The URI components to normalize
 * @param options - Optional normalization configuration
 * @returns Normalized URI components
 */
function normalize(uri: URIComponents, options?: URIOptions): URIComponents;

import { normalize } from "uri-js";

// String normalization
const normalized = normalize("HTTP://EXAMPLE.COM:80/%7Esmith/home.html");
console.log(normalized); // "http://example.com/~smith/home.html"

// IPv4 address normalization
const ipv4 = normalize("//192.068.001.000");
console.log(ipv4); // "//192.68.1.0"

// IPv6 address normalization
const ipv6 = normalize("//[2001:0:0DB8::0:0001]");
console.log(ipv6); // "//[2001:0:db8::1]"

// Components normalization
const components = normalize({
  scheme: "HTTP",
  host: "EXAMPLE.COM",
  path: "/%7Efoo"
});
console.log(components.scheme); // "http"
console.log(components.host); // "example.com"
console.log(components.path); // "/~foo"

/**
 * Compare two URI strings for equality
 * @param uriA - First URI string to compare
 * @param uriB - Second URI string to compare  
 * @param options - Optional comparison configuration
 * @returns True if URIs are equivalent
 */
function equal(uriA: string, uriB: string, options?: URIOptions): boolean;

/**
 * Compare two URI components for equality
 * @param uriA - First URI components to compare
 * @param uriB - Second URI components to compare
 * @param options - Optional comparison configuration
 * @returns True if URI components are equivalent
 */
function equal(uriA: URIComponents, uriB: URIComponents, options?: URIOptions): boolean;

import { equal } from "uri-js";

// String comparison
const isEqual = equal("http://example.com/", "HTTP://EXAMPLE.COM:80/");
console.log(isEqual); // true

// Case and encoding differences
const normalized = equal(
  "example://a/b/c/%7Bfoo%7D", 
  "eXAMPLE://a/./b/../b/%63/%7bfoo%7d"
);
console.log(normalized); // true

// Components comparison
const componentsEqual = equal(
  { scheme: "http", host: "example.com", path: "/" },
  { scheme: "HTTP", host: "EXAMPLE.COM", port: 80, path: "/" }
);
console.log(componentsEqual); // true

// IPv6 comparison
const ipv6Equal = equal(
  "//[2001:db8::1]",
  "//[2001:0db8:0000:0000:0000:0000:0000:0001]"
);
console.log(ipv6Equal); // true

interface URIOptions {
  /** Force treatment as specific scheme */
  scheme?: string;
  /** Reference format ("suffix" for suffix format parsing) */
  reference?: string;
  /** Enable relaxed URI resolving rules */
  tolerant?: boolean;
  /** Don't resolve relative path components during serialization */
  absolutePath?: boolean;
  /** Handle as IRI (RFC 3987) with Unicode support */
  iri?: boolean;
  /** Parse non-ASCII characters in output */
  unicodeSupport?: boolean;
  /** Treat host component as domain name for IDN processing */
  domainHost?: boolean;
}

interface URIComponents {
  /** URI scheme (e.g., "http", "https") */
  scheme?: string;
  /** User information part (e.g., "user:pass") */
  userinfo?: string;
  /** Host component (domain or IP address) */
  host?: string;
  /** Port number or string */
  port?: number | string;
  /** Path component */
  path?: string;
  /** Query string */
  query?: string;
  /** Fragment identifier */
  fragment?: string;
  /** Reference type: "uri", "absolute", "relative", "same-document" */
  reference?: string;
  /** Error message if parsing failed */
  error?: string;
}