Decode UUID

decodeUUID

The decodeUUID function decodes a UUID into its internal components, including version, variant, timestamps for time-based UUIDs, and other metadata. Supports RFC4122 UUID versions: 1-8.

Function Signature

decodeUUID(uuid: string): DecodedUUID | null

Parameters

Return Value

Returns a structured DecodedUUID object for valid UUIDs, or null for invalid UUIDs.

Example Usage

Return Type

interface DecodedUUID {
  /** Original UUID string */
  raw: UUID<UUIDVersion>;
  /** Plain version without hyphens */
  plain: string;
  /** UUID version as number (1-8) */
  version: $UUIDVersion;
  /** UUID variant specification */
  variant: 'NCS' | 'RFC4122' | 'Microsoft' | 'Future';
  /** Single integer representation as BigInt */
  singleInt: bigint;
  /** Timestamp in milliseconds since Unix epoch (v1, v6, v7, v8) */
  timestamp?: number;
  /** Node identifier for v1 UUIDs */
  node?: string;
}

Features

• Cross-runtime compatibility: Works in any JavaScript environment
• Spec-accurate decoding: Follows RFC4122 standards precisely
• Timestamp conversion: Automatically converts v1/v6 timestamps from UUID epoch (1582-10-15) to Unix milliseconds
• Variant detection: Identifies all standard UUID variants (NCS, RFC4122, Microsoft, Future)
• BigInt support: Provides the UUID as a single integer for mathematical operations

Timestamp Handling

Limitations

• v2 UUIDs: Specific decoding not implemented (deprecated standard)
• v8 layouts: Only returns timestamp for known layouts; custom layouts have limited decoding
• Variant detection: Based on RFC4122 rules; some edge cases may not be handled

Use Cases

• Debugging and analyzing UUID generation
• Extracting creation timestamps from time-based UUIDs
• Validating UUID structure and compliance
• Converting between UUID representations
• Audit logging and traceability

See Also

• uuid - Generate UUIDs across all versions
• isUUID - Validate UUID strings
• randomHex - Generate random hexadecimal strings