Skip to content

normalizeUUID

Normalizes a UUID‑like value into a canonical lowercase UUID string or returns null.

This helper accepts string representations of UUIDs in the standard 8‑4‑4‑4‑12 format. It trims whitespace, validates structure, and returns the UUID in lowercase canonical form. It never throws and never mutates input.

Signature

function normalizeUUID(value: unknown): string | null

Parameters

Name Data type Description
value unknown The value to normalize into a UUID string.

Returns

One of:

  • A canonical lowercase UUID string.
  • null: If the value cannot be interpreted as a valid UUID.

Behavior

  • Accepts only strings.
  • Trims whitespace before parsing.
  • Requires the canonical UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
  • Enforces correct version (1–5) and variant bits.
  • Returns the UUID in lowercase.
  • Rejects malformed UUIDs, URNs, braces, missing hyphens, and non‑hex characters.
  • Never throws and never mutates input.

Examples

normalizeUUID("550E8400-E29B-41D4-A716-446655440000");
// → "550e8400-e29b-41d4-a716-446655440000"

normalizeUUID("   550e8400-e29b-41d4-a716-446655440000   ");
// → "550e8400-e29b-41d4-a716-446655440000"

normalizeUUID("not-a-uuid");
// → null

normalizeUUID(123);
// → null

Notes

  • This helper enforces the canonical UUID textual representation.
  • It does not attempt to parse or normalize URNs (urn:uuid:...) or brace‑wrapped UUIDs.