# uuid — RFC-Compliant UUID Generation for JavaScript

> The standard library for generating RFC 9562-compliant v1, v4, v5, v6, and v7 UUIDs in Node.js and the browser.

## Install

Save in your project root:

# uuid — RFC-Compliant UUID Generation for JavaScript

## Quick Use
```bash
npm install uuid
```
```js
import { v4 as uuidv4, v7 as uuidv7 } from 'uuid';
console.log(uuidv4()); // e.g. '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
console.log(uuidv7()); // e.g. '01932f0e-8b3a-7dcf-a947-c4f1d42e8a70'
```

## Introduction
The uuid package is the canonical JavaScript implementation of RFC 9562 (formerly RFC 4122), providing functions to generate universally unique identifiers. It supports time-based, random, name-based, and the newer sortable UUID versions, making it the go-to choice for database keys, request tracing, and distributed system coordination.

## What uuid Does
- Generates v1 (timestamp + MAC), v4 (random), v3/v5 (namespace + name hash) UUIDs
- Supports v6 (reordered timestamp) and v7 (Unix epoch millisecond sortable) from the latest RFC
- Validates UUID strings and extracts version/variant information
- Provides both ESM and CommonJS entry points with full TypeScript types
- Uses the Web Crypto API in browsers and crypto module in Node.js for secure randomness

## Architecture Overview
Each UUID version has a dedicated generator function that assembles the 128-bit value according to RFC layout rules. The v4 generator fills 122 bits with crypto-random data and sets the version/variant nibbles. The v7 generator embeds a 48-bit Unix millisecond timestamp in the high bits for natural sortability, filling the remaining 74 bits with randomness. The library detects its runtime to select the most efficient random source.

## Self-Hosting & Configuration
- Install via npm, yarn, or pnpm — zero dependencies
- Import individual version functions for tree-shaking: `import { v4 } from 'uuid'`
- Use `uuid.validate(str)` and `uuid.version(str)` for input validation in API endpoints
- For deterministic IDs, use v5 with a namespace UUID and a name string
- Works in Node.js 14+, all modern browsers, Deno, Bun, and Cloudflare Workers

## Key Features
- Full RFC 9562 compliance including the latest v6 and v7 specifications
- Cryptographically secure random generation via native platform APIs
- Tree-shakeable ESM build — import only the versions you need
- TypeScript declarations included with branded UUID type
- Over 15,000 GitHub stars and 300 million weekly npm downloads

## Comparison with Similar Tools
- **nanoid** — shorter URL-safe IDs; uuid produces standard 36-character RFC-compliant identifiers
- **cuid2** — collision-resistant sortable IDs; uuid v7 offers similar sortability with RFC standardization
- **ulid** — 26-character sortable IDs; uuid v7 is the IETF-standardized sortable alternative
- **crypto.randomUUID()** — native v4 only; uuid supports v1, v3, v5, v6, v7 and validation utilities
- **short-uuid** — translates UUIDs to shorter encodings; uuid focuses on generation and validation

## FAQ
**Q: Which version should I use for database primary keys?**
A: Use v7 for new projects. Its time-sorted nature improves B-tree index locality in databases like PostgreSQL, MySQL, and MongoDB.

**Q: Is v4 still recommended?**
A: Yes, for cases where sortability is not needed. It provides 122 bits of randomness and is the most widely deployed UUID version.

**Q: How many v4 UUIDs before a collision?**
A: You would need to generate approximately 2.7 quintillion UUIDs to have a 50% probability of a single collision.

**Q: Does it work in edge runtimes?**
A: Yes. The library uses globalThis.crypto when available, which covers Cloudflare Workers, Deno Deploy, and Vercel Edge.

## Sources
- https://github.com/uuidjs/uuid
- https://www.rfc-editor.org/rfc/rfc9562

---
Source: https://tokrepo.com/en/workflows/asset-e1756bd8
Author: AI Open Source