URI Construction and Parsing

/**
 * URI constructor - can be called with or without 'new'
 * @param url - URI string to parse (defaults to current location in browser)
 * @param base - Base URI for resolving relative URLs
 * @returns URI instance for chaining operations
 */
function URI(url?: string, base?: string): URI;

// Basic construction
const uri = new URI('http://example.com/path');
const uri2 = URI('http://example.com/path'); // 'new' is optional

// With base resolution
const relative = new URI('../other/path.html', 'http://example.com/current/page.html');
console.log(relative.toString()); // 'http://example.com/other/path.html'

// Current location (browser only)
const current = new URI(); // Uses window.location.href

/**
 * Parse URI string into components object
 * @param string - URI string to parse
 * @param parts - Optional existing parts object to populate
 * @returns Object with URI components (protocol, hostname, port, etc.)
 */
URI.parse(string: string, parts?: object): ParsedURI;

/**
 * Parse hostname portion of URI
 * @param string - Hostname string potentially containing port
 * @param parts - Parts object to populate
 * @returns Parts object with hostname and port
 */
URI.parseHost(string: string, parts: object): object;

/**
 * Parse authority portion (userinfo + host)
 * @param string - Authority string
 * @param parts - Parts object to populate
 * @returns Parts object with userinfo and host components
 */
URI.parseAuthority(string: string, parts: object): object;

/**
 * Parse userinfo portion (username:password)
 * @param string - Userinfo string
 * @param parts - Parts object to populate
 * @returns Parts object with username and password
 */
URI.parseUserinfo(string: string, parts: object): object;

/**
 * Parse query string into object representation
 * @param string - Query string (without leading ?)
 * @param escapeQuerySpace - Whether to treat + as space
 * @returns Object representing query parameters
 */
URI.parseQuery(string: string, escapeQuerySpace?: boolean): object;

interface ParsedURI {
  protocol?: string;
  username?: string;
  password?: string;
  hostname?: string;
  port?: string;
  pathname?: string;
  query?: string;
  fragment?: string;
}

// Parse complete URI
const parts = URI.parse('http://user:pass@example.com:8080/path?query=value#fragment');
console.log(parts);
// {
//   protocol: 'http',
//   username: 'user',
//   password: 'pass',
//   hostname: 'example.com',
//   port: '8080',
//   pathname: '/path',
//   query: 'query=value',
//   fragment: 'fragment'
// }

// Parse query string
const queryObj = URI.parseQuery('name=John&age=30&tags=js&tags=web');
console.log(queryObj);
// { name: 'John', age: '30', tags: ['js', 'web'] }

/**
 * Build URI string from parts object
 * @param parts - Parts object with URI components
 * @returns Complete URI string
 */
URI.build(parts: object): string;

/**
 * Build host string from parts (hostname + port)
 * @param parts - Parts object with hostname and port
 * @returns Host string
 */
URI.buildHost(parts: object): string;

/**
 * Build authority string from parts (userinfo + host)
 * @param parts - Parts object with userinfo and host components
 * @returns Authority string
 */
URI.buildAuthority(parts: object): string;

/**
 * Build userinfo string from parts (username:password)
 * @param parts - Parts object with username and password
 * @returns Userinfo string
 */
URI.buildUserinfo(parts: object): string;

/**
 * Build query string from data object
 * @param data - Object or string to convert to query string
 * @param duplicateQueryParameters - Allow duplicate parameter names
 * @param escapeQuerySpace - Escape spaces as + instead of %20
 * @returns Query string (without leading ?)
 */
URI.buildQuery(data: object | string, duplicateQueryParameters?: boolean, escapeQuerySpace?: boolean): string;

// Build from parts
const uriString = URI.build({
  protocol: 'https',
  hostname: 'api.example.com',
  port: '443',
  pathname: '/v1/users',
  query: 'limit=10&offset=0'
});
console.log(uriString); // 'https://api.example.com:443/v1/users?limit=10&offset=0'

// Build query string
const queryString = URI.buildQuery({
  search: 'javascript',
  category: 'programming',
  tags: ['web', 'frontend']
});
console.log(queryString); // 'search=javascript&category=programming&tags=web&tags=frontend'

/**
 * Get or set the complete URI
 * @param href - New URI string to set
 * @param build - Whether to rebuild URI immediately
 * @returns Current href string or URI instance for chaining
 */
href(href?: string, build?: boolean): string | URI;

/**
 * Build URI string from current parts
 * @param deferBuild - Don't trigger automatic rebuilding
 * @returns Complete URI string
 */
build(deferBuild?: boolean): string;

/**
 * Create a copy of this URI instance
 * @returns New URI instance with same components
 */
clone(): URI;

/**
 * Convert URI to string representation
 * @returns Complete URI string
 */
toString(): string;

/**
 * Get primitive value (same as toString)
 * @returns Complete URI string
 */
valueOf(): string;

const uri = new URI('http://example.com/path');

// Get complete URI
console.log(uri.href()); // 'http://example.com/path'

// Set new URI
uri.href('https://newsite.com/newpath');
console.log(uri.toString()); // 'https://newsite.com/newpath'

// Clone URI
const copy = uri.clone();
copy.hostname('different.com');
console.log(uri.hostname()); // 'newsite.com' (original unchanged)
console.log(copy.hostname()); // 'different.com'

/**
 * Check various URI properties
 * @param what - Property to check: 'relative', 'absolute', 'domain', 'sld', 'ip', 'ip4', 'ip6', 'idn', 'url', 'urn', 'punycode'
 * @returns Boolean indicating if URI has the specified property
 */
is(what: string): boolean;

const uri1 = new URI('http://example.com/path');
const uri2 = new URI('../relative/path');
const uri3 = new URI('http://192.168.1.1/');

console.log(uri1.is('absolute')); // true
console.log(uri2.is('relative')); // true
console.log(uri3.is('ip')); // true
console.log(uri3.is('ip4')); // true

const domainUri = new URI('http://example.co.uk/');
console.log(domainUri.is('sld')); // true (has second-level domain)

// Version information
URI.version: string; // '1.19.11'

// Behavior configuration
URI.preventInvalidHostname: boolean; // Default: false
URI.duplicateQueryParameters: boolean; // Default: false  
URI.escapeQuerySpace: boolean; // Default: true

// Regular expressions for validation
URI.protocol_expression: RegExp;
URI.idn_expression: RegExp;
URI.punycode_expression: RegExp;
URI.ip4_expression: RegExp;
URI.ip6_expression: RegExp;
URI.find_uri_expression: RegExp;

// Default port mappings
URI.defaultPorts: {
  http: '80',
  https: '443',
  ftp: '21',
  gopher: '70',
  ws: '80',
  wss: '443'
};