Component Manipulation

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

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

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

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

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

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

/**
 * Get or set the search string (query with ?)
 * @param value - New search value (with or without leading ?)
 * @param build - Whether to rebuild URI immediately
 * @returns Current search string or URI instance for chaining
 */
search(value?: string, build?: boolean): string | URI;

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

/**
 * Get or set the hash (fragment with #)
 * @param value - New hash value (with or without leading #)
 * @param build - Whether to rebuild URI immediately
 * @returns Current hash string or URI instance for chaining
 */
hash(value?: string, build?: boolean): string | URI;

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

const uri = new URI('http://user:pass@example.com:8080/path/to/file.html?query=value#section');

// Get components
console.log(uri.protocol()); // 'http'
console.log(uri.username()); // 'user'
console.log(uri.hostname()); // 'example.com'
console.log(uri.port()); // '8080'
console.log(uri.pathname()); // '/path/to/file.html'
console.log(uri.query()); // 'query=value'
console.log(uri.fragment()); // 'section'

// Set components (chainable)
uri.protocol('https')
   .hostname('newhost.com')
   .port(9000)
   .pathname('/new/path')
   .query('new=query')
   .fragment('newSection');

console.log(uri.toString()); 
// 'https://user:pass@newhost.com:9000/new/path?new=query#newSection'

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

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

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

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

/**
 * Get or set the resource (path + query + fragment)
 * @param value - New resource value
 * @param build - Whether to rebuild URI immediately
 * @returns Current resource string or URI instance for chaining
 */
resource(value?: string, build?: boolean): string | URI;

const uri = new URI('http://user:pass@example.com:8080/path/to/file.html?query=value#section');

// Get compound components
console.log(uri.origin()); // 'http://user:pass@example.com:8080'
console.log(uri.host()); // 'example.com:8080'
console.log(uri.authority()); // 'user:pass@example.com:8080'
console.log(uri.userinfo()); // 'user:pass'
console.log(uri.resource()); // '/path/to/file.html?query=value#section'

// Set compound components
uri.host('newhost.com:9000');
console.log(uri.hostname()); // 'newhost.com'
console.log(uri.port()); // '9000'

uri.userinfo('newuser:newpass');
console.log(uri.username()); // 'newuser'
console.log(uri.password()); // 'newpass'

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

/**
 * Get or set the domain name (without subdomain and TLD)
 * @param value - New domain value
 * @param build - Whether to rebuild URI immediately
 * @returns Current domain string or URI instance for chaining
 */
domain(value?: string, build?: boolean): string | URI;

/**
 * Get or set the top-level domain
 * @param value - New TLD value
 * @param build - Whether to rebuild URI immediately
 * @returns Current TLD string or URI instance for chaining
 */
tld(value?: string, build?: boolean): string | URI;

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

// Get domain parts
console.log(uri.subdomain()); // 'api.staging'
console.log(uri.domain()); // 'example'
console.log(uri.tld()); // 'com'

// Set domain parts
uri.subdomain('www')
   .domain('mysite')
   .tld('org');

console.log(uri.hostname()); // 'www.mysite.org'

// Complex subdomain example
const complexUri = new URI('http://www.blog.company.co.uk/');
console.log(complexUri.subdomain()); // 'www.blog'
console.log(complexUri.domain()); // 'company'
console.log(complexUri.tld()); // 'co.uk'

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

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

/**
 * Get or set the file extension (suffix)
 * @param value - New suffix value (with or without leading .)
 * @param build - Whether to rebuild URI immediately
 * @returns Current suffix string or URI instance for chaining
 */
suffix(value?: string, build?: boolean): string | URI;

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

// Get path parts
console.log(uri.directory()); // '/path/to'
console.log(uri.filename()); // 'document.pdf'
console.log(uri.suffix()); // 'pdf'

// Set path parts
uri.directory('/downloads/files')
   .filename('report')
   .suffix('html');

console.log(uri.pathname()); // '/downloads/files/report.html'

// Handle edge cases
const rootUri = new URI('http://example.com/file.txt');
console.log(rootUri.directory()); // ''
console.log(rootUri.filename()); // 'file.txt'

const dirUri = new URI('http://example.com/path/to/');  
console.log(dirUri.directory()); // '/path/to'
console.log(dirUri.filename()); // ''

/**
 * Set hostname validation for this instance
 * @param value - Whether to prevent invalid hostnames
 * @returns URI instance for chaining
 */
preventInvalidHostname(value: boolean): URI;

/**
 * Set duplicate query parameter handling for this instance
 * @param value - Whether to allow duplicate parameter names
 * @returns URI instance for chaining
 */
duplicateQueryParameters(value: boolean): URI;

/**
 * Set query space escaping for this instance
 * @param value - Whether to escape spaces as + instead of %20
 * @returns URI instance for chaining
 */
escapeQuerySpace(value: boolean): URI;

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

// Configure instance behavior
uri.preventInvalidHostname(true)
   .duplicateQueryParameters(true)
   .escapeQuerySpace(false);

// This will allow multiple values for same parameter
uri.addQuery('tag', 'javascript')
   .addQuery('tag', 'programming');

console.log(uri.query()); // 'tag=javascript&tag=programming'