🆔 @chaisser/uuid-v7

Time-ordered UUID v7 generator with full TypeScript support

✨ Features

• 🎯 Type-safe - Full TypeScript support with strict types
• ⏰ Time-ordered - UUID v7 with embedded millisecond timestamps (RFC 9562)
• 🔄 UUID v4 - Also generates UUID v4 (random, RFC 4122)
• ✅ Validation - Validate and detect UUID versions
• 🧹 Formatting - Shorten, format, and parse UUIDs
• 🪶 Zero dependencies - Lightweight and tree-shakeable
• 🏎️ ESM + CJS - Dual module format support
• 🔐 Crypto-safe - Uses crypto.getRandomValues for secure randomness

📦 Installation

npm install @chaisser/uuid-v7
# or
yarn add @chaisser/uuid-v7
# or
pnpm add @chaisser/uuid-v7

🚀 Quick Start

import {
  generateUUID,
  generateUUIDv4,
  validateUUID,
  isUUIDv7,
  isUUIDv4,
  getUUIDVersion,
  NIL_UUID,
  shortenUUID,
  formatUUID,
} from '@chaisser/uuid-v7';

// Generate UUID v7 (time-ordered)
const id = generateUUID();
console.log(id); // 01914d2c-a3b7-7d4e-8f12-5a6b7c8d9e0f

// Generate UUID v4 (random)
const v4 = generateUUIDv4();
console.log(v4); // 550e8400-e29b-41d4-a716-446655440144

// Validate and check version
console.log(validateUUID(id)); // true
console.log(getUUIDVersion(id)); // 7
console.log(isUUIDv7(id)); // true
console.log(isUUIDv4(v4)); // true

// Format utilities
console.log(shortenUUID(id)); // 01914d2ca3b77d4e8f125a6b7c8d9e0f
console.log(formatUUID('0123456789abcdef0123456789abcdef')); // 01234567-89ab-cdef-0123-456789abcdef

📖 What It Does

This package generates RFC 9562 compliant UUID v7 identifiers with embedded millisecond timestamps, making them naturally sortable by creation time. It also supports UUID v4 generation, format validation, version detection, and common formatting operations.

🎯 How It Works

The package provides utilities organized into categories:

• Generation - Create UUID v7 (time-ordered) and v4 (random) identifiers
• Validation - Check if strings are valid UUIDs and detect their version
• Formatting - Shorten (remove dashes) or format (add dashes) UUID strings
• Parsing - Extract the embedded timestamp from UUID v7
• Nil UUID - Special all-zeros UUID constant and utilities

🎨 What It's Useful For

• Database Keys - Time-ordered primary keys that sort naturally
• Distributed Systems - Generate unique IDs without coordination
• API Identifiers - Request IDs, trace IDs, session tokens
• Data Migration - Generate sortable identifiers for imported records
• Logging - Correlate log entries with time-ordered trace IDs
• URL-Safe Tokens - Shorten UUIDs for use in URLs

💡 Usage Examples

Generating UUIDs

import { generateUUID, generateUUIDSimple, generateUUIDv4, generateUUIDv7Time } from '@chaisser/uuid-v7';

// Time-ordered UUID v7 (recommended)
const id1 = generateUUID();
console.log(id1); // 01914d2c-a3b7-7d4e-8f12-5a6b7c8d9e0f

// Alias with explicit name
const id2 = generateUUIDv7Time();

// Simple UUID v7 (no timestamp, just version bits)
const id3 = generateUUIDSimple();

// Random UUID v4
const id4 = generateUUIDv4();
console.log(getUUIDVersion(id4)); // 4

// Generate multiple at once
const ids = generateUUIDs(5);
console.log(ids.length); // 5

// With nil UUID included
const idsWithNil = generateUUIDs(3, true);
console.log(idsWithNil[0]); // 00000000-0000-0000-0000-000000000000

Validation

import { validateUUID, isUUID, isUUIDv4, isUUIDv7, getUUIDVersion } from '@chaisser/uuid-v7';

const v7 = generateUUID();
const v4 = generateUUIDv4();

// General validation
validateUUID(v7);          // true
validateUUID('not-a-uuid'); // false
validateUUID(NIL_UUID);    // true

// Version-specific checks
isUUIDv7(v7);  // true
isUUIDv4(v7);  // false
isUUIDv4(v4);  // true
isUUIDv7(v4);  // false

// Get version number
getUUIDVersion(v7);        // 7
getUUIDVersion(v4);        // 4
getUUIDVersion('invalid'); // null

Formatting

import { shortenUUID, formatUUID } from '@chaisser/uuid-v7';

const uuid = generateUUID();

// Remove dashes
const short = shortenUUID(uuid);
console.log(short); // 01914d2ca3b77d4e8f125a6b7c8d9e0f (32 chars)

// Add dashes back
const formatted = formatUUID(short);
console.log(formatted); // 01914d2c-a3b7-7d4e-8f12-5a6b7c8d9e0f

Parsing

import { parseUUIDv7 } from '@chaisser/uuid-v7';

const uuid = generateUUID();
const parsed = parseUUIDv7(uuid);

console.log(parsed?.version);    // 7
console.log(parsed?.timestamp);  // 1700000000000 (Unix ms)

// Returns null for non-v7 UUIDs
parseUUIDv7(generateUUIDv4()); // null
parseUUIDv7('invalid');        // null

Nil UUID

import { NIL_UUID, isNilUUID, generateNilUUID } from '@chaisser/uuid-v7';

console.log(NIL_UUID);        // 00000000-0000-0000-0000-000000000000
isNilUUID(NIL_UUID);          // true
isNilUUID(generateUUID());    // false
generateNilUUID();            // 00000000-0000-0000-0000-000000000000

📚 API Reference

Generation

| Function | Returns | Description | |---|---|---| | generateUUID() | string | UUID v7 with embedded timestamp | | generateUUIDv7Time() | string | Alias for generateUUID() | | generateUUIDSimple() | string | UUID v7 without timestamp | | generateUUIDv4() | string | Random UUID v4 | | randomUUID() | string | Alias for generateUUID() | | generateUUIDs(count, nil?) | string[] | Generate multiple UUIDs | | generateNilUUID() | string | Returns the nil UUID constant |

Validation

| Function | Returns | Description | |---|---|---| | validateUUID(uuid) | boolean | Validates UUID format | | isUUID(uuid) | boolean | Same as validateUUID | | isUUIDv4(uuid) | boolean | Checks format + version nibble = 4 | | isUUIDv7(uuid) | boolean | Checks format + version nibble = 7 | | isNilUUID(uuid) | boolean | Checks if uuid equals NIL_UUID | | getUUIDVersion(uuid) | 4 \| 7 \| null | Returns the UUID version |

Formatting

| Function | Returns | Description | |---|---|---| | shortenUUID(uuid) | string | Remove dashes (32 hex chars) | | formatUUID(uuid) | string | Add dashes (8-4-4-4-12) | | parseUUIDv7(uuid) | { version, timestamp } \| null | Extract timestamp from v7 |

Constants

| Name | Value | |---|---| | NIL_UUID | '00000000-0000-0000-0000-000000000000' |

🔗 Related Packages

Explore our other utility packages in the @chaisser namespace:

• @chaisser/uuid-v7 (this package) - Time-ordered UUID v7 generator
• @chaisser/string-wizard - Advanced string manipulation
• @chaisser/type-guard - Runtime type guards and validators
• @chaisser/human-time - Human-readable time formatting
• @chaisser/obj-path - Object path traversal
• @chaisser/regex-humanizer - Regex pattern explanation
• @chaisser/debounce-throttle - Rate limiting utilities
• @chaisser/color-utils - Color conversion utilities
• @chaisser/deep-clone - Deep cloning functions
• @chaisser/array-group-by - Array grouping utilities
• @chaisser/password-strength - Password strength checker
• @chaisser/wait-for - Promise-based wait utilities
• @chaisser/merge-objects - Object merge utilities
• @chaisser/chunk-array - Array chunking functions
• @chaisser/event-emitter - Typed event emitter

🔒 License

MIT - Free to use in personal and commercial projects

👨 Developed by

Doruk Karaboncuk [email protected]

📄 Repository

• GitHub: @chaisser
• NPM: @chaisser/uuid-v7

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📞 Support

For issues, questions, or suggestions, please reach out through:

• Email: [email protected]
• GitHub Issues: Create an issue

Made with ❤️ by @chaisser