Generador CUID

¿Qué es CUID?

CUID (Identificador Único Resistente a Colisiones) es un algoritmo de código abierto para generar IDs únicos que funcionan bien en sistemas distribuidos sin un coordinador central. A diferencia de un UUID simple, un CUID está diseñado para ser horizontalmente escalable — múltiples servidores o pestañas del navegador pueden generar IDs de forma independiente con un riesgo mínimo de colisión.

Todo CUID comienza con la letra minúscula c, haciendo que el formato sea inmediatamente reconocible de un vistazo. Los caracteres restantes son todos alfanuméricos en minúsculas (base36), por lo que un CUID es seguro para URLs y puede usarse directamente como segmento de ruta URL o clave primaria de base de datos sin codificación adicional.

La especificación original de CUID (v1) fue creada por Eric Elliott y popularizada a través del paquete npm cuid. Ahora está reemplazada por CUID v2, que proporciona seguridad criptográfica. Esta página — y el generador anterior — produce IDs CUID v1, el formato clásico que aún se encuentra ampliamente en bases de código en producción.

Estructura de CUID

Un CUID v1 tiene aproximadamente 25 caracteres de longitud y está compuesto de cinco segmentos concatenados, cada uno con un tipo diferente de entropía:

Los segmentos simplemente se concatenan — no hay separadores. La longitud total varía ligeramente según el valor de la marca de tiempo actual, pero se mantiene en aproximadamente 25 caracteres.

Cómo CUID Previene Colisiones

La resistencia a colisiones proviene de superponer fuentes independientes de entropía de modo que incluso en escenarios de peor caso (miles de IDs generados por milisegundo en muchas máquinas) la probabilidad de dos IDs idénticos permanezca extremadamente pequeña.

CUID vs UUID v4

Tanto CUID como UUID v4 son ampliamente usados para la generación de IDs del lado del cliente. Toman diferentes enfoques al mismo problema:

UUID v4 es la opción más segura para escenarios sensibles a la seguridad porque no revela información de tiempo. CUID tiene ventaja cuando quieres IDs vagamente ordenables, más cortos y sin guiones — útil para uso en URLs, nombres de archivo o registros donde deseas identificar rápidamente cuándo se creó un registro.

CUID v1 vs CUID2

La especificación CUID ha sido revisada significativamente. Entender las diferencias te ayuda a elegir la versión correcta para tu proyecto:

Para nuevos proyectos, CUID v2 es la opción recomendada. Su construcción basada en SHA-3 hace que la salida sea opaca — no se puede hacer ingeniería inversa del timestamp, contador o huella digital desde el ID. Usa CUID v1 solo cuando necesites compatibilidad hacia atrás con un conjunto de datos existente o quieras una implementación sin dependencias.

Casos de Uso

Ejemplos de Código

Instala el paquete oficial CUID v2 (recomendado) o escribe una implementación mínima de v1 sin dependencias:

// npm install @paralleldrive/cuid2  (recommended — CUID v2)
import { createId } from '@paralleldrive/cuid2'

const id = createId()
// → 'tz4a98xxat96iws9zmbrgj3a'

// Custom length
import { init } from '@paralleldrive/cuid2'
const createShortId = init({ length: 10 })
createShortId() // → 'zxp1l6mf4c'

Si prefieres una implementación Node.js sin dependencias del algoritmo v1:

// Pure Node.js — CUID v1 style (no dependencies)
let counter = 0

function pad(str, size) {
  return str.padStart(size, '0').slice(-size)
}

function fingerprint() {
  const os = require('os')
  const source = [process.pid, os.hostname().length].join('')
  let hash = 0
  for (const c of source) {
    hash = ((hash << 5) - hash) + c.charCodeAt(0)
    hash |= 0
  }
  return pad(Math.abs(hash).toString(36), 4)
}

function cuid() {
  const timestamp = Date.now().toString(36)
  const cnt       = pad((counter++ & 0xffff).toString(36), 4)
  const fp        = fingerprint()
  const rnd       = pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
              + pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
  return 'c' + timestamp + cnt + fp + rnd
}

console.log(cuid()) // → 'clrc4gkwz001ag2hs3k7f9m2q'

Usando CUID como clave primaria de base de datos con Prisma y PostgreSQL:

-- Use CUID as a primary key in PostgreSQL
CREATE TABLE users (
  id   TEXT        PRIMARY KEY DEFAULT gen_cuid(),
  name TEXT        NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Prisma schema (auto-generates CUID by default)
model User {
  id        String   @id @default(cuid())
  name      String
  createdAt DateTime @default(now())
}

Preguntas Frecuentes