Skip to content

Parse URL string

parseUrlString parses URL strings into normalized URL values.

It accepts only syntactically valid, fully qualified URLs and rejects any malformed or incomplete input. If the value is not a string or cannot be parsed by the URL constructor, the rule emits no parse result.

Signature

Through the API:

.parse('url');

And internally:

export const parseUrlString: ParseRule<string>
(value: unknown, path: FieldPath) => ParseResult<string>[]

Events

Event code Description
string.now.url Parsed string into a normalized URL.

Design rationale

  • Accepts only fully qualified URLs, including protocol (http://, https://, and so on.).
  • Rejects ambiguous or partial forms such as "example.com", "//example.com", or "http:/example.com".
  • Uses the WHATWG URL parser to ensure standards‑compliant validation.
  • Normalizes the URL using .toString(), guaranteeing consistent formatting.
  • Produces a single parse step containing the normalized URL and one parseEvent.
  • Never guesses, normalizes text, or attempts partial repair — parsing is explicit and opt‑in.

Invoke

parseUrlString runs only when explicitly included in a boundary or pipeline. It is not affected by normalization mode and does not run automatically.

The rule activates when:

  • The value is a string.
  • new URL(value) succeeds without throwing.
  • The resulting URL is fully qualified and syntactically valid.

Examples

Valid URL strings

parseUrlString("https://example.com/path?x=1", "$");
// → [
//     {
//       path: "$",
//       nextValue: "https://example.com/path?x=1",
//       events: [
//         JaneEvent{ kind: "info", code: "string.now.url", ... }
//       ]
//     }
//   ]

Invalid URLs — no parse

parseUrlString("example.com", "$");        // → []
parseUrlString("http:/example.com", "$");  // → []
parseUrlString("://broken", "$");          // → []
parseUrlString("not a url", "$");          // → []

Non‑string value

parseUrlString(42, "$"); // → []