uuid-v7-tools

npm install @ferrow/uuid-v7-tools

UUID v4 + v7 generation, timestamp extraction, time-ordering, version detection.

Quick Start

import { v4, v7, extractTimestamp, compare } from "uuid-v7-tools";

// Random v4
const random = v4();         // "550e8400-e29b-41d4-a716-446655440000"

// Timestamp-based v7 (sortable by creation time)
const id1 = v7();            // "019f8f00-0000-7xxx-9xxx-xxxxxxxxxxxx"
const id2 = v7();            // "019f8f00-0001-7xxx-9xxx-xxxxxxxxxxxx"

// Extract timestamp
extractTimestamp(id1);       // Date object for creation time

// Compare v7s by timestamp
compare(id1, id2);           // negative = id1 earlier

API

v4(): string

Generate random UUID v4.

v7(): string

Generate UUID v7 with 48-bit unix millisecond timestamp prefix (per RFC 9562). Sortable by creation time.

extractTimestamp(uuid: string): Date

Extract unix timestamp from v7 UUID and return as Date.

validate(uuid: string): boolean

Validate UUID format (canonical hyphenated format).

version(uuid: string): number | null

Detect UUID version (1-5, 7) or null if invalid format.

compare(a: string, b: string): number

Compare two v7 UUIDs by their embedded timestamps. Returns: negative if a < b, zero if equal, positive if a > b. Useful for sorting v7s in creation order.

isMax(uuid: string): boolean / isNil(uuid: string): boolean

Check for all-F's or all-0's special UUIDs.

Limitations

• v7 timestamps are 48-bit milliseconds (supports dates up to year 10895).
• No custom epoch support.
• No support for UUID v3/v5 (named) generation.

---

Part of the ferrow-toolkit collection · Sponsored by Ferrow