URL Parsing

/**
 * Parse a URL string according to WHATWG URL specification
 * @param {string} input - URL string to parse
 * @param {Object} [options] - Parsing options
 * @param {URLRecord|null} [options.baseURL] - Base URL for relative URLs
 * @returns {URLRecord|null} URL record object or null if parsing fails
 */
function parseURL(input, options)

const { parseURL } = require("whatwg-url");

// Parse absolute URL
const absolute = parseURL("https://example.com/path?query=value#fragment");
console.log(absolute);
// {
//   scheme: "https",
//   username: "",
//   password: "",
//   host: "example.com",
//   port: null,
//   path: ["", "path"],
//   query: "query=value",
//   fragment: "fragment"
// }

// Parse relative URL with base
const base = parseURL("https://example.com/api/");
const relative = parseURL("../users", { baseURL: base });
console.log(relative.path); // ["", "users"]

// Handle parsing failure
const invalid = parseURL("not-a-valid-url");
console.log(invalid); // null

/**
 * Basic URL parser with state override support
 * @param {string} input - URL string to parse
 * @param {Object} [options] - Parsing options
 * @param {URLRecord|null} [options.baseURL] - Base URL for relative URLs
 * @param {URLRecord} [options.url] - Existing URL record to modify
 * @param {string} [options.stateOverride] - Parser state to start from
 * @returns {URLRecord|null} URL record object or null if parsing fails
 */
function basicURLParse(input, options)

const { basicURLParse } = require("whatwg-url");

// Basic parsing (equivalent to parseURL)
const url = basicURLParse("https://example.com/path");

// Parse with state override (advanced usage)
const existingUrl = parseURL("https://example.com/");
const modified = basicURLParse("new-path", {
  url: existingUrl,
  stateOverride: "path"
});

// Parse hostname only
const hostResult = basicURLParse("example.com", {
  stateOverride: "hostname"
});

/**
 * Serialize a URL record to string
 * @param {URLRecord} urlRecord - URL record to serialize
 * @param {boolean} [excludeFragment=false] - Whether to exclude fragment
 * @returns {string} Serialized URL string
 */
function serializeURL(urlRecord, excludeFragment)

/**
 * Serialize the path component of a URL record
 * @param {URLRecord} urlRecord - URL record with path to serialize
 * @returns {string} Serialized path string
 */
function serializePath(urlRecord)

/**
 * Serialize the host component of a URL record
 * @param {string|null} host - Host from URL record
 * @returns {string} Serialized host string
 */
function serializeHost(host)

/**
 * Serialize the origin of a URL record
 * @param {URLRecord} urlRecord - URL record to serialize origin from
 * @returns {string} Serialized origin string or "null" for opaque origins
 */
function serializeURLOrigin(urlRecord)

/**
 * Serialize an integer according to URL specification
 * @param {number} number - Integer to serialize
 * @returns {string} Serialized integer string
 */
function serializeInteger(number)

const { 
  parseURL, 
  serializeURL, 
  serializePath, 
  serializeHost, 
  serializeURLOrigin,
  serializeInteger 
} = require("whatwg-url");

// Parse and serialize
const url = parseURL("https://example.com:8080/path/to/resource?query=value#section");

console.log(serializeURL(url)); 
// "https://example.com:8080/path/to/resource?query=value#section"

console.log(serializeURL(url, true)); // exclude fragment
// "https://example.com:8080/path/to/resource?query=value"

console.log(serializePath(url)); 
// "/path/to/resource"

console.log(serializeHost(url.host)); 
// "example.com:8080"

// Serialize custom URL record
const customUrl = {
  scheme: "http",
  username: "",
  password: "", 
  host: "localhost",
  port: 3000,
  path: ["", "api", "users"],
  query: "limit=10",
  fragment: null
};

console.log(serializeURL(customUrl));
// "http://localhost:3000/api/users?limit=10"

// Serialize origins
console.log(serializeURLOrigin(url));
// "https://example.com:8080"

// Different schemes return different origins
const fileUrl = parseURL("file:///path/to/file.txt");
console.log(serializeURLOrigin(fileUrl)); // "null"

const dataUrl = parseURL("data:text/plain,Hello");
console.log(serializeURLOrigin(dataUrl)); // "null"

// Serialize integers
console.log(serializeInteger(8080)); // "8080"
console.log(serializeInteger(443)); // "443"

/**
 * URL record object structure
 */
interface URLRecord {
  /** URL scheme (e.g., "https", "file") */
  scheme: string;
  
  /** Username component */
  username: string;
  
  /** Password component */
  password: string;
  
  /** Host component (domain, IP, or null for file: URLs) */
  host: string | null;
  
  /** Port number (null for default ports) */
  port: number | null;
  
  /** Path segments array (normal URLs) or opaque path string */
  path: string[] | string;
  
  /** Query string component (null if no query) */
  query: string | null;
  
  /** Fragment component (null if no fragment) */
  fragment: string | null;
}

// Normal URL with path array
const httpUrl = parseURL("https://example.com/api/users/123");
console.log(httpUrl.path); // ["", "api", "users", "123"]

// Opaque URL with path string  
const dataUrl = parseURL("data:text/plain;base64,SGVsbG8gV29ybGQ=");
console.log(dataUrl.path); // "text/plain;base64,SGVsbG8gV29ybGQ="
console.log(typeof dataUrl.path); // "string"