README.md

UUIDv7

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

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

• String.prototype.padStart

  • Included in popular frameworks:

    • Next.js
    • Nuxt
    • Gatsby

  • Polyfillable using core-js, preferably within <script nomodule>:

    import "core-js/features/string/pad-start";

• crypto.getRandomValues()

  • IE 11:

    if (typeof window !== "undefined" && !window.crypto && window.msCrypto) {
      window.crypto = window.msCrypto;
    }

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                             │
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘