Decodificador UUID

Estrutura UUID

Um UUID (Identificador Universalmente Único) é um valor de 128 bits representado como 32 dígitos hexadecimais divididos em cinco grupos por hífens:

A versão e a variante são os únicos dois campos garantidos de estar presentes em cada UUID. Todos os outros campos dependem da versão.

O Campo de Versão

O nibble de versão é o primeiro dígito hexadecimal do terceiro grupo (posição 14 na string completa). Ele identifica qual versão UUID foi usada para gerar o identificador.

const hex = uuid.replace(/-/g, '')
const version = parseInt(hex[12], 16)  // single hex digit → 1, 2, 3, 4, 5, 6, 7, or 8

A versão 7 (UUID v7) é a versão de uso mais amplo mais recente, introduzida no RFC 9562 (2024). Ela codifica um timestamp Unix em milissegundos nos bits mais significativos para ordenabilidade.

O Campo de Variante

A variante é codificada nos bits mais significativos do primeiro byte do quarto grupo. Ela identifica o layout e as convenções de ordenação de bytes usadas pelo UUID.

Na prática, praticamente todos os UUIDs que você encontra usam a variante RFC 4122 / RFC 9562 (padrão de bits 10xx xxxx, primeiro byte do quarto grupo no intervalo 0x80–0xBF). As variantes NCS, Microsoft COM e Reserved são formatos legados raramente vistos em sistemas modernos.

Referência de Versões UUID

RFC 4122 definiu as versões 1–5. RFC 9562 (2024) adicionou as versões 6, 7 e 8:

Decodificando Timestamps UUID v1

UUID v1 incorpora um timestamp gregoriano de 60 bits (intervalos de 100 nanossegundos desde 15 de outubro de 1582) dividido em três campos: time_low (bits 0–31), time_mid (bits 32–47) e time_hi (bits 48–59). Esta ferramenta os remonta e converte para uma data UTC padrão.

// UUID v1: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
//           ^^^^^^^^ ^^^^ ^^^^ ^^^^^ ^^^^^^^^^^^^
//           time-low  mid  hi  clk   node (MAC)
//                          ^
//                          version nibble (1)

const hex = '6ba7b8109dad11d180b400c04fd430c8'

const tLow = parseInt(hex.slice(0, 8),  16)  // 0x6ba7b810
const tMid = parseInt(hex.slice(8, 12), 16)  // 0x9dad
const tHi  = parseInt(hex.slice(13, 16), 16) // 0x1d1 (skip version nibble at index 12)

// Reconstruct 60-bit timestamp (100-ns intervals since Oct 15, 1582)
const t = (BigInt(tHi) << 48n) | (BigInt(tMid) << 32n) | BigInt(tLow)

// Subtract Gregorian offset (Oct 15, 1582 → Jan 1, 1970 in 100-ns units)
const GREGORIAN_OFFSET = 122192928000000000n
const unixMs = (t - GREGORIAN_OFFSET) / 10000n

console.log(new Date(Number(unixMs)).toISOString())
// → 1998-02-04T22:13:53.578Z

UUID v1 deve ser tratado como sensível: o endereço MAC incorporado e o timestamp preciso podem identificar tanto a máquina geradora quanto o tempo de geração.

Decodificando Timestamps UUID v7

UUID v7 incorpora um timestamp Unix de 48 bits em milissegundos nos primeiros 48 bits (primeiro grupo + primeiros 4 dígitos do segundo grupo). Esta ferramenta lê esses bits e os converte para uma data UTC com precisão de milissegundos.

// UUID v7: 018e4bc8-1000-7000-8000-000000000001
//           ^^^^^^^^^^^^
//           48-bit Unix ms timestamp

const hex = '018e4bc8100070008000000000000001'

// First 48 bits (12 hex chars) = Unix timestamp in milliseconds
const ms = parseInt(hex.slice(0, 12), 16)  // 0x018e4bc81000

console.log(new Date(ms).toISOString())
// → 2024-03-11T…Z

// Everything after byte 6 is random (except version/variant bits)

Ao contrário do UUID v1, o timestamp do UUID v7 usa a familiar época Unix (1 de janeiro de 1970) e não incorpora nenhuma informação do host. Os 74 bits restantes são aleatórios.

Como Esta Ferramenta Detecta Versão e Variante UUID

O decodificador lê a posição 14 (nibble de versão) e a posição 19 (nibble de variante) da string UUID canônica. Nenhum estado externo ou contexto é necessário — todas as informações estão autocontidas na string UUID.

// Detect UUID version from the 13th hex character (index 12)
function uuidVersion(uuid) {
  const clean = uuid.replace(/-/g, '')
  return parseInt(clean[12], 16)
}

uuidVersion('550e8400-e29b-41d4-a716-446655440000') // → 4
uuidVersion('018e4bc8-1000-7000-8000-000000000001') // → 7
uuidVersion('6ba7b810-9dad-11d1-80b4-00c04fd430c8') // → 1

// Detect variant from the 17th hex character (index 16, first char of 4th group)
function uuidVariant(uuid) {
  const clean = uuid.replace(/-/g, '')
  const b = parseInt(clean[16], 16)
  if ((b & 0x8) === 0)      return 'NCS'
  if ((b & 0xC) === 0x8)    return 'RFC 4122'
  if ((b & 0xE) === 0xC)    return 'Microsoft'
  return 'Reserved'
}

UUIDs Especiais

UUID Nulo

O UUID nulo 00000000-0000-0000-0000-000000000000 é todo zeros. É definido pelo RFC 4122 como um valor sentinela significando 'nenhum UUID' — análogo a null. Não é um UUID gerado válido.

UUID Máximo

O UUID máximo ffffffff-ffff-ffff-ffff-ffffffffffff é todo uns (0xFF em cada byte). Definido no RFC 9562, é o complemento do UUID nulo e serve como valor sentinela máximo.

Perguntas Frequentes