Générer un UUID en JavaScript

Les identifiants uniques universels (UUID) sont des identifiants de 128 bits conçus pour garantir un niveau d'unicité exceptionnel sans coordination centralisée. Dans les environnements JavaScript modernes (navigateurs, Node.js, Deno, Bun et Cloudflare Workers), la création et la manipulation d'UUID sont directes et performantes.

Démarrage rapide#

Dans les environnements modernes, l'API globale crypto permet de générer des UUID v4 natifs sans aucune dépendance :

1// JavaScript moderne natif (Node.js 14.17+, navigateurs modernes, Bun, Deno)2const uuid = crypto.randomUUID();34console.log(uuid);5// Résultat : "36b8f84d-df4e-4d49-b662-bcde71a8764f"

La méthode crypto.randomUUID() s'appuie sur le générateur de nombres pseudo-aléatoires cryptographiquement sécurisé (CSPRNG) du système d'exploitation sous-jacent, conforme aux RFC 4122 et RFC 9562.

Générer des UUID avec le paquet uuid#

Pour les projets nécessitant des identifiants ordonnés dans le temps (UUID v7) ou un hachage d'espace de noms (UUID v5), le paquet standard uuid est la référence :

1npm install uuid

1import { v4 as uuidv4, v7 as uuidv7 } from "uuid";23// UUID v4 aléatoire standard4const idAleatoire = uuidv4();5console.log("v4 :", idAleatoire);67// UUID v7 ordonné par le temps (idéal pour les clés primaires SQL)8const idOrdonne = uuidv7();9console.log("v7 :", idOrdonne);

Analyser un UUID en octets binaires#

Un UUID canonique fait 36 caractères avec 4 tirets. Lors du stockage compact dans des bases de données ou des protocoles binaires, vous pouvez le convertir en un tableau Uint8Array de 16 octets :

1import { parse as parseUuid, stringify as stringifyUuid } from "uuid";23const uuidStr = "710b962e-041c-11e1-9234-0123456789ab";45// Conversion en Uint8Array de 16 octets6const bytes = parseUuid(uuidStr);7console.log("Nombre d'octets :", bytes.length); // 1689// Reconstruction de la chaîne canonique10const reconstruit = stringifyUuid(bytes);11console.log("Identique :", reconstruit === uuidStr); // true

Valider un UUID#

Valider les identifiants entrants permet de vérifier leur conformité syntaxique et d'éviter les enregistrements corrompus en base. Attention : la validation seule ne protège pas contre les injections SQL ; associez-la impérativement à des requêtes paramétrées :

1import { validate as validateUuid, version as uuidVersion } from "uuid";23const entree = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";45if (validateUuid(entree)) {6  console.log("UUID valide, version :", uuidVersion(entree));7} else {8  console.error("Format d'UUID invalide");9}

UUID v4 vs UUID v7 en JavaScript#

• UUID v4 : Entièrement aléatoire. Idéal pour les jetons de session, les cookies ou les références publiques non indexées.
• UUID v7 : Ordonné temporellement. Intègre un horodatage milliseconde dans les 48 premiers bits, évitant la fragmentation des index B-tree. La monotonie stricte lors d'appels multiples dans la même milliseconde requiert un compteur ou mécanisme d'incrémentation défini (RFC 9562, section 6.2).

Bonnes pratiques#

1. Privilégiez crypto.randomUUID() : Évite d'alourdir le bundle applicatif lorsque seul le v4 standard est requis.
2. N'utilisez jamais Math.random() : Trop prévisible et non conforme aux exigences cryptographiques.
3. Sensibilité à la casse : Le texte d'un UUID est insensible à la casse. La RFC 9562 autorise les majuscules, minuscules ou une combinaison des deux en entrée, bien que les minuscules soient privilégiées en sortie.

Références#

• RFC 9562 : Universally Unique IDentifiers (UUIDs)
• MDN Web Docs : Crypto.randomUUID()
• Paquet npm uuid