Skip to content

validateUUID

Checks whether a value is a canonical UUID string. This helper uses the isUUID type guard internally. A UUID is considered valid when it matches the canonical 8-4-4-4-12 hexadecimal format and contains only hexadecimal digits and hyphens.

This validator does not check UUID version or variant bits. It only verifies the canonical shape without coercion.

It never throws and never mutates input. Use it when you need a strict UUID before normalization or further semantic validation.

Signature

function validateUUID(value: unknown): string | undefined

Parameters

Name Data type Description
value unknown The value to validate.

Returns

One of:

  • The original input string if the value is a canonical UUID.
  • undefined: if the value is not a UUID.

Behavior

  • Uses isUUID internally.
  • Only canonical 8-4-4-4-12 UUIDs pass.
  • Does not validate UUID version or variant bits.
  • Rejects non-strings, malformed UUIDs, incorrect segment lengths, and invalid characters.
  • Never mutates input.
  • Never throws.
  • Never coerces values (e.g., " uuid " is invalid).

Examples

validateUUID("123e4567-e89b-12d3-a456-426614174000")
// "123e4567-e89b-12d3-a456-426614174000"

validateUUID("123E4567-E89B-12D3-A456-426614174000")
// "123E4567-E89B-12D3-A456-426614174000"

validateUUID("not-a-uuid")
// undefined

validateUUID(123)
// undefined

validateUUID("123e4567e89b12d3a456426614174000")
// undefined

Notes

  • This validator does not normalize or lowercase UUIDs. It returns the original input exactly as provided.
  • Because it depends on isUUID, values with incorrect segment lengths, missing hyphens, or invalid hex characters automatically fail.
  • Suitable for validating identifiers, database keys, and any context requiring a guaranteed canonical UUID string.
  • The validator is pure, side-effect-free, and never throws.