UUID en JavaScript (Node.js): guía completa con ejemplos

1. ¿Qué es y para qué sirve?

UUID (Identificador Único Universal) es un estándar de identificación utilizado en el desarrollo de software para crear claves únicas sin necesidad de una gestión centralizada. La librería uuid para JavaScript (Node.js) ofrece una forma sencilla y fiable de generar UUID de las versiones 1, 3, 4, 5 y 7 (en las versiones más recientes). Es una de las librerías más populares y descargadas del ecosistema Node.js, con más de 50 millones de descargas semanales.

¿Para qué sirve? En el desarrollo moderno, prácticamente toda aplicación necesita identificadores únicos: para registros en bases de datos, identificación de usuarios, sesiones, pedidos, archivos y mucho más. El uso de UUID evita colisiones (identificadores duplicados) incluso en sistemas distribuidos donde varios servidores generan identificadores simultáneamente. Por ejemplo, si tienes una arquitectura de microservicios donde cada servicio crea registros de forma independiente, UUID garantiza que dos servicios nunca generen un registro con el mismo ID.

La librería uuid soporta varias versiones del estándar: v1 (basada en tiempo y dirección MAC), v4 (generación aleatoria), v7 (marca de tiempo + datos aleatorios — nuevo estándar optimizado para bases de datos). La versión 4 es la más común por su simplicidad y alto grado de unicidad. La versión 7 se recomienda para proyectos nuevos, ya que permite ordenar naturalmente por tiempo, mejorando el rendimiento de los índices en bases de datos.

2. Instalación

La instalación de la librería uuid en un proyecto Node.js se realiza mediante npm (Node Package Manager). Abre la terminal en la carpeta raíz de tu proyecto y ejecuta el comando:

npm install uuid

Si usas yarn:

yarn add uuid

Una vez instalada, la librería estará disponible para importarla en tu código. Para proyectos TypeScript, los tipos se instalan automáticamente junto con el paquete.

3. Inicio rápido — ejemplo mínimo funcional

Crea un archivo ejemplo.js y añade el siguiente código:

import { v4 as uuidv4 } from 'uuid';

// Generar un UUID v4
const miUUID = uuidv4();
console.log('UUID generado:', miUUID);
// Ejemplo de salida: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

Ejecuta el archivo con el comando node ejemplo.js. Verás el UUID generado en la consola. Este es un ejemplo mínimo que demuestra la funcionalidad básica de la librería: generar un único identificador.

4. Métodos/funciones principales

La librería uuid proporciona varias funciones para generar UUID de diferentes versiones. Veamos cada una en detalle.

4.1. `v1()` — UUID versión 1 (basado en tiempo)

Firma: v1(opciones?, buffer?, offset?)

Descripción: Genera un UUID versión 1 que incluye una marca de tiempo (intervalos de 100 nanosegundos desde el 15 de octubre de 1582) y la dirección MAC del dispositivo. Esto garantiza unicidad en tiempo y espacio. Sin embargo, el uso de la dirección MAC puede ser un problema de privacidad.

import { v1 as uuidv1 } from 'uuid';

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

// Con opciones: desactivar dirección MAC (usar nodo aleatorio)
const uuid1SinMac = uuidv1({ node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab] });
console.log('UUID v1 con nodo personalizado:', uuid1SinMac);