Skip to content

parseUUID

parseUUID

Parses a value into a canonical lowercase UUID string. This parser combines the validateUUID semantic validator and the normalizeUUID normalizer to ensure that only well‑formed UUIDs in the 8‑4‑4‑4‑12 canonical format are accepted. This parser enforces versions one through five and variant correctness (8, 9, a, b) through the normalizer.

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

Signature

function parseUUID(value: unknown): ParseResult<string>

Behavior

  • Accepts UUID-like strings that:
  • Match the canonical 8‑4‑4‑4‑12 hex pattern.
  • Contain only hexadecimal digits and hyphens.
  • Normalizes valid UUIDs into lowercase canonical form.
  • Rejects:
  • Malformed UUIDs.
  • UUIDs with invalid version bits (must be 1–5).
  • UUIDs with invalid variant bits (must be 8, 9, a, or b).
  • Empty or whitespace-only strings.
  • Non-string values.
  • Never mutates input.
  • Never throws.

Returns

  • ok: true: And the canonical lowercase UUID when parsing succeeds.
  • ok: false, value: null: And a list of issues when parsing fails.

Examples

parseUUID("123e4567-e89b-12d3-a456-426614174000")
// { ok: true, value: "123e4567-e89b-12d3-a456-426614174000", issues: [] }

parseUUID("123E4567-E89B-12D3-A456-426614174000")
// { ok: true, value: "123e4567-e89b-12d3-a456-426614174000", issues: [] }

parseUUID("123e4567-e89b-f2d3-a456-426614174000")
// { ok: false, value: null, issues: ["Value could not be normalized into a canonical UUID"] }

parseUUID("not-a-uuid")
// { ok: false, value: null, issues: ["Value is not a canonical UUID string"] }

Notes

  • Normalization enforces lowercase output for consistency.
  • Version and variant validation is performed by the normalizer, not the type guard.
  • This parser is pure, side-effect-free, and safe for all runtime environments.