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.

info

Does not rely on Node.js or Web APIs. Works on any JS engine

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

Parameter	Type	Description
`options`	`UUIDOptions<V>` (optional)	Controls version, formatting, and required fields for `v3` and `v5`.

Version Behavior

v1 → Timestamp & node-identifier–based
v3 → MD5(namespace + name)
v4 → Pure random (correct variant + version injection)
v5 → SHA-1(namespace + name)
v6 → Re-ordered timestamp variant of v1 (lexicographically sortable)
v7 → Unix-time–based, monotonic-friendly
v8 → Custom layout, "Future" variant (timestamp + randomness)

Return Value

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

Warning

Throws Error if namespace is missing or not a valid uuid or name is not a valid string for v3 and v5!

Example Usage

import { uuid } from 'nhb-toolbox/hash';

// Generate a random UUID v4 (default)
const id1 = uuid();
// → "f47ac10b-58cc-4372-a567-0e02b2c3d479"

// Generate uppercase v7
const id2 = uuid({ version: 'v7', uppercase: true });
// → "017F22E2-79B0-7CC3-98C4-DC0C0C07398F"

// Generate v5 UUID with namespace
const id3 = uuid({
  version: 'v5',
  namespace: uuid(),
  name: 'example'
});
// → "aad5a5a7-6c6a-5b5c-8c8c-9c9c9c9c9c9c"

// Generate v3 UUID
const id4 = uuid({
  version: 'v3', 
  namespace: uuid(),
  name: 'test'
});
// → "5df41881-3aed-3515-88a7-2f4a814cf09e"

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

uuid​

Function Signature & Types​

Parameters​

Version Behavior​

Return Value​

Example Usage​

Notes​

Limitations​

See Also​