qapinterface/lib/url.js

Comprehensive API utilities for Node.js applications including authentication, security, request processing, and response handling with zero external dependencies

/**
 * Secure URL Query Parameter Builder
 * 
 * SINGLE RESPONSIBILITY: Safe query parameter appending to URLs ONLY
 * 
 * SECURITY AND RELIABILITY FOCUS:
 * URL construction is a common source of security vulnerabilities and bugs in web applications.
 * This utility addresses several critical concerns:
 * - URL encoding to prevent injection attacks
 * - Proper handling of special characters and Unicode
 * - Prevention of duplicate parameter names
 * - Null/undefined value filtering to avoid malformed URLs
 * - Standards-compliant URL construction using native URL API
 * 
 * WHY USE URL API:
 * The native URL API provides robust parsing and encoding that handles edge cases
 * better than manual string concatenation. It automatically handles:
 * - URL encoding of parameter names and values
 * - Proper separator characters (& vs ?)
 * - Unicode normalization
 * - Protocol and hostname preservation
 * 
 * DESIGN DECISIONS:
 * - Null/undefined filtering prevents empty parameters in URLs
 * - String coercion ensures consistent parameter value types
 * - Immutable approach: doesn't modify the input baseUrl
 * - Returns complete URL string for direct use in requests
 */

/**
 * Safely appends query parameters to a base URL with proper encoding.
 * 
 * PARAMETER HANDLING:
 * - Filters out null/undefined values to prevent malformed URLs
 * - Converts all values to strings for consistent URL encoding
 * - Uses URLSearchParams for standards-compliant parameter encoding
 * - Preserves existing query parameters in the base URL
 * 
 * SECURITY FEATURES:
 * - Automatic URL encoding prevents injection attacks
 * - Unicode-safe parameter handling
 * - No manual string concatenation to avoid parsing errors
 * 
 * @param {string} baseUrl - The base URL (must be valid URL format)
 * @param {Object<string, string|number>} [queryParams={}] - Key-value pairs for query parameters
 * @returns {string} Complete URL with appended query parameters
 * @throws {TypeError} If baseUrl is not a valid URL format
 */
function appendQueryParams(baseUrl, queryParams = {}) {
  // URL parsing: Create URL object for safe parameter manipulation
  // This validates the baseUrl format and provides secure parameter handling
  // Will throw TypeError if baseUrl is malformed
  const url = new URL(baseUrl);
  
  // Parameter processing: Iterate through provided query parameters
  Object.entries(queryParams).forEach(([key, value]) => {
    // Value filtering: Skip null/undefined to prevent empty parameters
    // This prevents URLs like "example.com/path?key=" which can cause issues
    if (value !== null && value !== undefined) {
      // Parameter appending: Use append() to handle multiple values for same key
      // String() coercion ensures consistent type handling (numbers, booleans, etc.)
      // URL.searchParams automatically handles URL encoding
      url.searchParams.append(key, String(value));
    }
  });
  
  // URL reconstruction: Return complete URL string with encoded parameters
  return url.toString();
}

module.exports = {
  appendQueryParams
};