Skip to content

parseURL

Parses a value into a fully-qualified absolute URL instance. This parser combines the the validateURL semantic validator and the normalizeURL normalizer to ensure that only well-formed absolute URLs are accepted.

The parser never throws and never mutates input. It returns a structured ParseResult<URL> describing success or failure.

Signature

function parseURL(value: unknown): ParseResult<URL>

Behavior

  • Accepts URL instances directly.
  • Accepts absolute URL strings that:
  • Match the minimal <scheme>:// shape.
  • Can be parsed by the WHATWG URL constructor.
  • Rejects:
  • Malformed URL strings.
  • Relative URLs.
  • Empty or whitespace-only strings.
  • Non-string, non-URL values.
  • Normalizes valid strings into real URL instances.
  • Never mutates input.
  • Never throws.

Returns

  • ok: true: And the normalized URL instance when parsing succeeds.
  • ok: false, value: null: And a list of issues when parsing fails.

Examples

parseURL("https://example.com")
// { ok: true, value: URL("https://example.com"), issues: [] }

parseURL("http:/broken.com")
// { ok: false, value: null, issues: ["Value is not a valid absolute URL string"] }

parseURL("/relative")
// { ok: false, value: null, issues: ["Value could not be normalized into a valid absolute URL"] }

Notes

  • Relative URLs are intentionally rejected to avoid environment-dependent resolution.
  • Normalization always produces a fully-qualified absolute URL.
  • This parser is pure, side-effect-free, and safe for all runtime environments.