UUID — v1, v4, v5, v7

Universally Unique Identifiers (UUIDs) are 128-bit identifiers represented as 36-character hexadecimal strings formatted in five groups separated by hyphens: 8-4-4-4-12. @readytools/id provides full, zero-dependency implementations of UUID v1, v4, v5, and the cutting-edge RFC 9562 standard UUIDv7.

@readytools/id vs standard 'uuid' npm Package

If you are currently using the classic uuid package (npm install uuid), @readytools/id serves as a superior, zero-dependency drop-in replacement with several major architectural benefits:

Migration from 'uuid' package

Migrating from uuid to @readytools/id is instant without requiring awkward alias imports:

// Before (with standard uuid npm package):
// import { v4 as uuidv4, v1 as uuidv1 } from 'uuid';

// After (with @readytools/id):
import { uuidv4, uuidv7, uuidv1, uuidv5 } from '@readytools/id';

// Upgrade your primary keys from random v4 to index-friendly v7:
const newPrimaryKey = uuidv7();

UUIDv7 — Time-Ordered Monotonic (RFC 9562)

UUIDv7 is the modern standard for database primary keys. Unlike UUIDv4 which scatters random inserts across database pages and causes severe B-Tree index fragmentation, UUIDv7 encodes a 48-bit Unix timestamp in milliseconds in the highest bits, followed by 74 bits of cryptographically secure random entropy. This ensures sequential, append-only index insertion while maintaining global uniqueness.

import { uuidv7 } from '@readytools/id';

const id = uuidv7();
// Returns: "018f6f89-8d2a-7140-9a3b-586b9e248b11"

Bit Structure of UUIDv7

• 0..47 (48 bits): Unix timestamp in milliseconds (Date.now()).
• 48..51 (4 bits): Version number (0111 for version 7).
• 52..63 (12 bits): Cryptographically secure random entropy.
• 64..65 (2 bits): RFC variant (10 for Variant 1).
• 66..127 (62 bits): Cryptographically secure random entropy.

Database Schema Example (Prisma & PostgreSQL)

Using UUIDv7 in your database models maximizes write throughput and minimizes cache misses:

import { uuidv7 } from '@readytools/id';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

async function createNewUser(email, name) {
  return await prisma.user.create({
    data: {
      id: uuidv7(), // Generates sequential, index-friendly primary key
      email,
      name
    }
  });
}

UUIDv4 — Cryptographically Random (RFC 4122)

UUIDv4 generates 122 bits of pure cryptographic randomness using the native Web Crypto API (crypto.randomUUID). It is ideal for session IDs, correlation IDs, and non-indexed unique values.

import { uuidv4 } from '@readytools/id';

const id = uuidv4();
// Returns: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

UUIDv5 — Deterministic Name-Based (SHA-1)

UUIDv5 generates a deterministic, reproducible UUID by computing a SHA-1 hash of a namespace UUID concatenated with a name string. Supplying the same namespace and name will always produce the identical UUID across all systems.

import { uuidv5 } from '@readytools/id';

// Standard DNS Namespace UUID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
const DNS_NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';

const id1 = uuidv5('example.com', DNS_NAMESPACE);
// Returns: "cf517e59-fad7-567f-9c1d-cad2c9332e4d"

const id2 = uuidv5('example.com', DNS_NAMESPACE);
// Always identical to id1: "cf517e59-fad7-567f-9c1d-cad2c9332e4d"

UUIDv1 — Time and MAC-Based

UUIDv1 uses a 60-bit timestamp based on the Gregorian calendar reform (100-nanosecond intervals since Oct 15, 1582), combined with a 14-bit clock sequence and a randomized 48-bit multicast node ID to maintain privacy and zero-dependency portability.

import { uuidv1 } from '@readytools/id';

const id = uuidv1();
// Returns: "d9428888-122b-11ee-be56-0242ac120002"