Skip to content

Is URL

isUrl validates that a value is a syntactically valid absolute URL using the WHATWG URL parser.

It enforces strict structural and format requirements: the value must be a string, and the WHATWG parser must successfully construct a URL object from it. Any non‑string value or string that fails WHATWG parsing results in a single validation event. Otherwise, it produces no validation output.

Signature

Through the API:

.isUrl();

And internally:

export const isUrl: ValidationRule
(value: unknown, path: FieldPath) => Promise<ReadonlyArray<JaneEvent>>

Events

Event code Description
string.not.string Value is not a string.
string.not.url String is not a valid WHATWG‑parsed URL.

Design rationale

  • Uses the WHATWG URL constructor for canonical, standards‑aligned URL validation.
  • Rejects non‑string values early with a structural‑type diagnostic.
  • Ensures only absolute URLs are accepted — relative URLs fail WHATWG parsing.
  • Avoids regex‑based heuristics in favor of the platform’s authoritative parser.
  • Emits exactly one event per failure for clarity and composability.
  • Pure, total, async‑compatible, and returns a readonly array of JaneEvent objects.
  • Preserves the provided path and supports pipeline‑level userMessage overrides.

Invoke

isUrl runs only when explicitly included in a boundary or pipeline. It does not run automatically and is disabled when strict mode is enabled.

The rule activates when:

  • The value is any JavaScript value.
  • If the value is not a string, emits string.not.string.
  • If new URL(value) throws, emits string.not.url.
  • Otherwise, returns an empty result set.

Examples

Valid — absolute URLs

await isUrl("https://example.com", "$");
// → []

await isUrl("https://sub.domain.org/path?query=1#hash", "$");
// → []

Invalid — non‑string values

await isUrl(12345, "$");
// → [
//     JaneEvent{
//       kind: "error",
//       code: "string.not.string",
//       path: "$",
//       ...
//     }
//   ]

Invalid — malformed or incomplete URLs

await isUrl("not a url", "$");
// → [
//     JaneEvent{
//       kind: "error",
//       code: "string.not.url",
//       path: "$",
//       ...
//     }
//   ]

await isUrl("/relative/path", "$"); // WHATWG requires absolute URLs
// → [
//     JaneEvent{
//       kind: "error",
//       code: "string.not.url",
//       path: "$",
//       ...
//     }
//   ]