Generate UUID

uuid

The uuid function generates UUIDs across all major RFC-compliant versions (1, 3, 4, 5, 6, 7, 8), following standards from RFC4122. Default version is v4.

Function Signature & Types

// Function Signature
uuid<V extends SupportedVersion = 'v4'>(options?: UUIDOptions<V>): UUID<V>

/** UUID versions as string from `v1-v8` */
type UUIDVersion = `v${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}`;

/** Supported UUID versions (without `v2`) as string */
type SupportedVersion = `v${1 | 3 | 4 | 5 | 6 | 7 | 8}`;

/** Branded UUID string type */
type UUID<V extends UUIDVersion> = Branded<string, V>;

/** Options for UUID generation */
type UUIDOptions<V extends SupportedVersion = 'v4'> = 
  V extends 'v3' | 'v5' 
    ? { version: V; namespace: string; name: string; uppercase?: boolean }
    : { version?: V; uppercase?: boolean };

Parameters

Version Behavior

• v1 → Timestamp & node-identifier–based, uses a generated pseudo-node identifier
• v3 → MD5(namespace + name), uses internal MD5 implementations and remain fully deterministic.
• v4 → Uses Math.random when crypto.getRandomValues is unavailable (correct variant + version injection)
• v5 → SHA-1(namespace + name), uses internal SHA-1 implementations and remain fully deterministic.
• v6 → Re-ordered timestamp variant of v1 (lexicographically sortable)
• v7 → Unix-time–based (milliseconds), monotonic-friendly, extremely high throughput may still cause rare collisions.
• v8 → Uses a simple timestamp + randomness layout; Custom layouts are not supported here, randomness follows same logic as v4.

Return Value

Returns a 5-part UUID string formatted with correct version/variant bits as a branded type.

Example Usage

Notes

• Engine Agnostic: Provides complete RFC compliance without relying on crypto APIs
• Deterministic: v3 and v5 use internal MD5/SHA-1 implementations and remain fully deterministic
• Privacy Focused: v1 and v6 use pseudo-random node identifiers, not real MAC addresses

Limitations

• v1/v6: Node identifier is pseudo-random, not derived from real MAC addresses
• v3/v5: MD5/SHA-1 algorithms follow RFC specs but are not cryptographically secure
• v7: Millisecond precision; extremely high throughput may cause rare collisions
• v8: Uses simple timestamp + randomness layout; custom layouts not supported

See Also

• md5 - MD5 hashing implementation used in v3 UUIDs
• sha1 - SHA-1 hashing implementation used in v5 UUIDs
• randomHex - For hex-only strings with custom length
• generateRandomID - For customized ID generation