Parse URL

import parseUrl from "parse-url";

const parseUrl = require("parse-url");

import parseUrl from "parse-url";

// Parse a standard HTTP URL
const httpUrl = parseUrl("http://ionicabizau.net/blog");
console.log(httpUrl);
// {
//   protocols: ["http"],
//   protocol: "http",
//   port: "",
//   resource: "ionicabizau.net", 
//   host: "ionicabizau.net",
//   user: "",
//   password: "",
//   pathname: "/blog",
//   hash: "",
//   search: "",
//   href: "http://ionicabizau.net/blog",
//   query: {},
//   parse_failed: false
// }

// Parse a Git SSH URL
const gitUrl = parseUrl("git@github.com:IonicaBizau/parse-url.git");
console.log(gitUrl);
// {
//   protocols: ["ssh"],
//   protocol: "ssh",
//   port: "",
//   resource: "github.com",
//   host: "github.com", 
//   user: "git",
//   password: "",
//   pathname: "/IonicaBizau/parse-url.git",
//   hash: "",
//   search: "",
//   href: "git@github.com:IonicaBizau/parse-url.git",
//   query: {},
//   parse_failed: false
// }

// Parse with URL normalization
const normalizedUrl = parseUrl("http://example.com//path", true);

/**
 * Parses the input url and returns detailed component information
 * @param url - The input URL to parse
 * @param normalize - Whether to normalize the URL. If true, normalizes using default options. If object, uses as normalize-url options
 * @returns Parsed URL object with detailed component information
 * @throws ParsingError if URL is invalid or parsing fails
 */
function parseUrl(url: string, normalize?: boolean | NormalizeOptions): ParsedUrl;

interface ParsedUrl {
  /** Array of URL protocols (usually contains one element) */
  protocols: string[];
  /** The first protocol, "ssh" for SSH URLs, or "file" for file URLs */
  protocol: string;
  /** The domain port as a string */
  port: string;
  /** The URL domain including subdomains */
  resource: string;
  /** The fully qualified domain name or IP address */
  host: string;
  /** The authentication user (typically for SSH URLs) */
  user: string;
  /** The authentication password */
  password: string;
  /** The URL pathname */
  pathname: string;
  /** The URL hash fragment */
  hash: string;
  /** The URL query string value */
  search: string;
  /** The original input URL */
  href: string;
  /** The URL query string parsed as an object */
  query: Record<string, any>;
  /** Whether the URL parsing failed */
  parse_failed: boolean;
}

/** 
 * Normalization options from the normalize-url package
 * See normalize-url documentation for complete options
 */
type NormalizeOptions = {
  /** Whether to strip the hash fragment during normalization */
  stripHash?: boolean;
  /** Additional normalize-url package options */
  [key: string]: any;
};

interface ParsingError extends Error {
  /** The URL that failed to parse */
  readonly subject_url: string;
}

/** Maximum allowed input URL length (2048 characters) */
const MAX_INPUT_LENGTH: 2048;

// SSH-style Git URLs are automatically detected and parsed
const gitSshUrl = parseUrl("git@github.com:user/repo.git");
// Returns protocol: "ssh", user: "git", resource: "github.com"

// Git+SSH URLs with full protocol
const gitPlusSchUrl = parseUrl("git+ssh://git@host.xz/path/name.git");
// Returns protocols: ["git", "ssh"], protocol: "git"

// Basic normalization
parseUrl("HTTP://EXAMPLE.COM//path", true);

// Custom normalization options
parseUrl("http://example.com/path#hash", {
  stripHash: false,
  stripWWW: true
});

try {
  parseUrl("");  // Empty URL
} catch (error: ParsingError) {
  console.log(error.subject_url);  // The URL that failed
}

try {
  parseUrl("a".repeat(3000));  // URL too long
} catch (error: ParsingError) {
  console.log("URL exceeds maximum length");
}

try {
  parseUrl("invalid-url-format");  // Unparseable URL
} catch (error: ParsingError) {
  console.log("URL parsing failed");
}