Skip to content
/ uuidv7 Public

UUIDv7 generator with millisecond precision

License

Notifications You must be signed in to change notification settings

kripod/uuidv7

Repository files navigation

UUIDv7

UUIDv7 generator based on the RFC4122 update proposal (draft-04)

npm (scoped) npm bundle size (scoped) GitHub Workflow Status (branch) Contributor Covenant

Usage

import { uuidv7 } from "@kripod/uuidv7";

let id = uuidv7();
console.log(id); // Example: 00ccebbc-13e0-7000-8b18-6150ad2d0c05

Key features

  • K-sortable with 1ms precision (Safari disallows sub-ms timing to defend against Spectre)
  • Time-ordered when sorted lexicographically
  • Collision-resistant with distributed systems in mind
  • Works until the year 10889, after which timestamps would overflow

Compatibility

Chrome Safari Firefox IE Node.js Deno
≥57 ≥10 ≥48 No (polyfillable) ≥8 ≥1

Supporting additional runtimes

Binary structure

  • unix_ts_ms: Milliseconds elapsed since the Unix epoch – 48 bits
  • ver: UUID version (7) – 4 bits
  • rand_a: Monotonic sequence counter for more precise sorting – 12 bits
  • var: UUID variant (0b10) – 2 bits
  • rand_b: Cryptographically strong random data – 62 bits
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
┌─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┐
│                          unix_ts_ms                           │
├─┴─┴─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┼─┴─┴─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤
│          unix_ts_ms           │  ver  │        rand_a         │
├─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤
│var│                        rand_b                             │
├─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤
│                            rand_b                             │
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘