Generatore CUID

Cos'è CUID?

CUID (Collision-Resistant Unique Identifier) è un algoritmo open-source per generare ID univoci che funzionano bene nei sistemi distribuiti senza un coordinatore centrale. A differenza di un semplice UUID, un CUID è progettato per essere orizzontalmente scalabile — più server o schede del browser possono generare ID in modo indipendente con un rischio minimo di collisione.

Ogni CUID inizia con la lettera minuscola c, rendendo il formato immediatamente riconoscibile a colpo d'occhio. I caratteri rimanenti sono tutti alfanumerici minuscoli (base36), quindi un CUID è sicuro per gli URL e può essere utilizzato direttamente come segmento di percorso URL o chiave primaria del database senza codifica aggiuntiva.

La specifica CUID originale (v1) è stata creata da Eric Elliott e resa popolare tramite il pacchetto npm cuid. Ora è sostituita da CUID v2, che fornisce sicurezza crittografica. Questa pagina — e il generatore sopra — produce ID CUID v1, il formato classico ancora ampiamente presente nelle basi di codice di produzione.

Struttura di CUID

Un CUID v1 è lungo circa 25 caratteri ed è composto da cinque segmenti concatenati, ognuno dei quali porta un tipo diverso di entropia:

I segmenti sono semplicemente concatenati — non ci sono separatori. La lunghezza totale varia leggermente a seconda del valore attuale del timestamp, ma rimane di circa 25 caratteri.

Come CUID Previene le Collisioni

La resistenza alle collisioni deriva dalla stratificazione di fonti di entropia indipendenti in modo che anche negli scenari peggiori (migliaia di ID generati per millisecondo su molte macchine) la probabilità di due ID identici rimanga estremamente piccola.

CUID vs UUID v4

Sia CUID che UUID v4 sono ampiamente usati per la generazione di ID lato client. Adottano approcci diversi allo stesso problema:

UUID v4 è la scelta più sicura per scenari sensibili alla sicurezza perché non rivela informazioni temporali. CUID ha il vantaggio quando si vogliono ID vagamente ordinabili, più corti e privi di trattini — utile per l'uso in URL, nomi di file o log dove si vuole identificare rapidamente quando è stato creato un record.

CUID v1 vs CUID2

La specifica CUID è stata rivista in modo significativo. Capire le differenze aiuta a scegliere la versione giusta per il proprio progetto:

Per i nuovi progetti, CUID v2 è la scelta raccomandata. La sua costruzione basata su SHA-3 significa che l'output è opaco — nessun timestamp, contatore o impronta digitale può essere ricavato per ingegneria inversa dall'ID. Usa CUID v1 solo quando hai bisogno di compatibilità con un set di dati esistente o vuoi un'implementazione senza dipendenze.

Casi d'Uso

Esempi di Codice

Installa il pacchetto ufficiale CUID v2 (raccomandato) o scrivi un'implementazione minima di v1 senza dipendenze:

// 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'

Se preferisci un'implementazione Node.js senza dipendenze dell'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'

Usare CUID come chiave primaria del database con Prisma e 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())
}

Domande Frequenti