Query Parameter Management

/**
 * Set query parameters (replaces existing)
 * @param name - Parameter name or object of name-value pairs
 * @param value - Parameter value (ignored if name is object)
 * @param build - Whether to rebuild URI immediately
 * @returns URI instance for chaining
 */
setQuery(name: string | object, value?: string, build?: boolean): URI;
setSearch(name: string | object, value?: string, build?: boolean): URI; // Alias

/**
 * Add query parameters (preserves existing)
 * @param name - Parameter name or object of name-value pairs
 * @param value - Parameter value (ignored if name is object)
 * @param build - Whether to rebuild URI immediately
 * @returns URI instance for chaining
 */
addQuery(name: string | object, value?: string, build?: boolean): URI;
addSearch(name: string | object, value?: string, build?: boolean): URI; // Alias

/**
 * Remove query parameters
 * @param name - Parameter name or array of names to remove
 * @param value - Specific value to remove (removes all if not specified)
 * @param build - Whether to rebuild URI immediately
 * @returns URI instance for chaining
 */
removeQuery(name: string | string[], value?: string, build?: boolean): URI;
removeSearch(name: string | string[], value?: string, build?: boolean): URI; // Alias

/**
 * Check if query parameters exist
 * @param name - Parameter name to check
 * @param value - Specific value to check for
 * @param withinArray - Whether to check within array values
 * @returns Boolean indicating parameter existence
 */
hasQuery(name: string, value?: string, withinArray?: boolean): boolean;
hasSearch(name: string, value?: string, withinArray?: boolean): boolean; // Alias

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

// Set single parameter
uri.setQuery('page', '1');
console.log(uri.query()); // 'page=1'

// Set multiple parameters with object
uri.setQuery({
  page: 2,
  limit: 10,
  sort: 'name'
});
console.log(uri.query()); // 'page=2&limit=10&sort=name'

// Add parameters (preserves existing)
uri.addQuery('filter', 'active')
   .addQuery('tag', 'javascript')
   .addQuery('tag', 'web'); // Multiple values for same key

console.log(uri.query()); // 'page=2&limit=10&sort=name&filter=active&tag=javascript&tag=web'

// Check parameter existence  
console.log(uri.hasQuery('page')); // true
console.log(uri.hasQuery('tag', 'javascript')); // true
console.log(uri.hasQuery('missing')); // false

// Remove specific parameter value
uri.removeQuery('tag', 'web');
console.log(uri.hasQuery('tag', 'web')); // false
console.log(uri.hasQuery('tag', 'javascript')); // true

// Remove all values for parameter
uri.removeQuery('tag');
console.log(uri.hasQuery('tag')); // false

/**
 * Enhanced query getter/setter with object support
 * @param value - Query string, object, or function to transform query
 * @param build - Whether to rebuild URI immediately
 * @returns Current query string/object or URI instance for chaining
 */
query(value?: string | object | function, build?: boolean): string | object | URI;

const uri = new URI('http://example.com/api?page=1&tags=js&tags=web');

// Get query as object
const queryObj = uri.query(true); // true means return as object
console.log(queryObj);
// { page: '1', tags: ['js', 'web'] }

// Set query from object
uri.query({
  search: 'javascript',
  category: 'programming',
  active: true
});
console.log(uri.query()); // 'search=javascript&category=programming&active=true'

// Transform query with function
uri.query(function(data) {
  data.timestamp = Date.now();
  delete data.active;
  return data;
});

// Complex nested structures
uri.setQuery({
  filters: {
    status: 'active',
    type: ['article', 'tutorial']
  },
  meta: {
    version: '1.0',
    format: 'json'
  }
});

/**
 * Add query parameters to a data object
 * @param data - Existing query data object
 * @param name - Parameter name to add
 * @param value - Parameter value to add
 * @returns Modified data object
 */
URI.addQuery(data: object, name: string, value: string): object;

/**
 * Set query parameters in a data object
 * @param data - Existing query data object
 * @param name - Parameter name to set
 * @param value - Parameter value to set
 * @returns Modified data object
 */
URI.setQuery(data: object, name: string, value: string): object;

/**
 * Remove query parameters from a data object
 * @param data - Existing query data object
 * @param name - Parameter name to remove
 * @param value - Specific value to remove (optional)
 * @returns Modified data object
 */
URI.removeQuery(data: object, name: string, value?: string): object;

/**
 * Check if query parameters exist in a data object
 * @param data - Query data object to check
 * @param name - Parameter name to check
 * @param value - Specific value to check for (optional)
 * @param withinArray - Whether to check within array values
 * @returns Boolean indicating parameter existence
 */
URI.hasQuery(data: object, name: string, value?: string, withinArray?: boolean): boolean;

// Work with query data objects directly
let queryData = { page: '1', sort: 'name' };

// Add parameters
URI.addQuery(queryData, 'filter', 'active');
URI.addQuery(queryData, 'tag', 'javascript');
URI.addQuery(queryData, 'tag', 'web');
console.log(queryData);
// { page: '1', sort: 'name', filter: 'active', tag: ['javascript', 'web'] }

// Check existence
console.log(URI.hasQuery(queryData, 'tag', 'javascript')); // true
console.log(URI.hasQuery(queryData, 'tag')); // true
console.log(URI.hasQuery(queryData, 'missing')); // false

// Remove specific value
URI.removeQuery(queryData, 'tag', 'web');
console.log(queryData.tag); // ['javascript']

// Remove entire parameter
URI.removeQuery(queryData, 'tag');
console.log(queryData.hasOwnProperty('tag')); // false

/**
 * Encode query string with proper escaping
 * @param string - String to encode
 * @param escapeQuerySpace - Whether to encode spaces as + instead of %20
 * @returns Encoded string
 */
URI.encodeQuery(string: string, escapeQuerySpace?: boolean): string;

/**
 * Decode query string
 * @param string - String to decode
 * @param escapeQuerySpace - Whether to decode + as space
 * @returns Decoded string
 */
URI.decodeQuery(string: string, escapeQuerySpace?: boolean): string;

// Encode query values
const encoded = URI.encodeQuery('hello world & more');
console.log(encoded); // 'hello+world+%26+more' (with escapeQuerySpace: true)

const encodedPct = URI.encodeQuery('hello world & more', false);
console.log(encodedPct); // 'hello%20world%20%26%20more'

// Decode query values
const decoded = URI.decodeQuery('hello+world+%26+more');
console.log(decoded); // 'hello world & more'

// Use in URI construction
const uri = new URI('http://example.com/search');
uri.setQuery('q', 'javascript & web development');
console.log(uri.toString()); // 'http://example.com/search?q=javascript+%26+web+development'

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

// Add multiple values for same parameter
uri.addQuery('category', 'web')
   .addQuery('category', 'mobile')
   .addQuery('category', 'desktop');

console.log(uri.query()); // 'category=web&category=mobile&category=desktop'

// Get as object shows arrays
const queryObj = uri.query(true);
console.log(queryObj.category); // ['web', 'mobile', 'desktop']

// Set array directly
uri.setQuery('tags', ['javascript', 'react', 'node']);
console.log(uri.query()); // 'tags=javascript&tags=react&tags=node'

// Check array values
console.log(uri.hasQuery('tags', 'react')); // true
console.log(uri.hasQuery('tags', 'vue')); // false

// Remove from array
uri.removeQuery('tags', 'node');
const remaining = uri.query(true);
console.log(remaining.tags); // ['javascript', 'react']

// Configure duplicate parameter behavior
uri.duplicateQueryParameters(false); // Disable duplicates
uri.setQuery('tags', ['a', 'b', 'c']);
// Will use a different serialization format depending on configuration