1. O que é e para que serve

UUID (Universally Unique Identifier) é um padrão de identificação usado no desenvolvimento de software para criar chaves únicas sem a necessidade de gerenciamento centralizado. A biblioteca uuid para JavaScript (Node.js) oferece uma maneira simples e confiável de gerar UUIDs das versões 1, 3, 4, 5 e 7 (nas versões mais recentes). Ela é uma das bibliotecas mais populares e baixadas no ecossistema Node.js, com mais de 50 milhões de downloads por semana.

Por que usar isso? No desenvolvimento moderno, praticamente toda aplicação precisa de identificadores únicos: para registros em banco de dados, identificação de usuários, sessões, pedidos, arquivos e muito mais. O uso de UUID evita colisões (identificadores duplicados) mesmo em sistemas distribuídos, onde vários servidores geram identificadores simultaneamente. Por exemplo, se você tem uma arquitetura de microsserviços onde cada serviço cria registros de forma independente, o UUID garante que dois serviços nunca criarão um registro com o mesmo ID.

A biblioteca uuid suporta várias versões do padrão: v1 (baseada em tempo e endereço MAC), v4 (geração aleatória), v7 (timestamp + dados aleatórios — novo padrão otimizado para bancos de dados). A versão 4 é a mais comum devido à sua simplicidade e alto grau de exclusividade. A versão 7 é recomendada para novos projetos, pois oferece ordenação natural por tempo, melhorando o desempenho de índices em bancos de dados.

2. Instalação

A instalação da biblioteca uuid em um projeto Node.js é feita via npm (Node Package Manager). Abra o terminal na pasta raiz do seu projeto e execute o comando:

npm install uuid

Se você usa yarn:

yarn add uuid

Após a instalação, a biblioteca estará disponível para importação no seu código. Para projetos TypeScript, os tipos também estão disponíveis (instalados automaticamente junto com o pacote).

3. Início rápido — exemplo mínimo funcional

Crie um arquivo exemplo.js e adicione o seguinte código:

import { v4 as uuidv4 } from 'uuid';

// Gerando um UUID v4
const meuUUID = uuidv4();
console.log('UUID gerado:', meuUUID);
// Exemplo de saída: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

Execute o arquivo com o comando node exemplo.js. Você verá o UUID gerado no console. Este é um exemplo mínimo que demonstra a funcionalidade principal da biblioteca — gerar um único identificador.

4. Principais métodos/funções

A biblioteca uuid oferece várias funções para gerar UUIDs de diferentes versões. Vamos detalhar cada uma delas.

4.1. v1() — UUID versão 1 (baseado em tempo)

Assinatura: v1(options?, buffer?, offset?)

Descrição: Gera um UUID versão 1, que inclui um timestamp (intervalos de 100 nanossegundos desde 15 de outubro de 1582) e o endereço MAC do dispositivo. Isso garante exclusividade no tempo e no espaço. No entanto, o uso do endereço MAC pode ser um problema de privacidade.

import { v1 as uuidv1 } from 'uuid';

const uuid1 = uuidv1();
console.log('UUID v1:', uuid1);
// Exemplo: 'c9b1deb4-3b7d-11ec-8d3d-0242ac130003'

// Com opções: desabilitar MAC (usar nó aleatório)
const uuid1SemMac = uuidv1({ node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab] });
console.log('UUID v1 com nó personalizado:', uuid1SemMac);

4.2. v4() — UUID versão 4 (aleatório)