Skip to content

Add randomUUIDv7() method (RFC 9562) - #562

Open
gianluca-pettenon wants to merge 2 commits into
w3c:mainfrom
gianluca-pettenon:add-randomuuidv7
Open

Add randomUUIDv7() method (RFC 9562)#562
gianluca-pettenon wants to merge 2 commits into
w3c:mainfrom
gianluca-pettenon:add-randomuuidv7

Conversation

@gianluca-pettenon

Copy link
Copy Markdown

Add randomUUIDv7() method (RFC 9562)

Addresses #561.

What

Adds Crypto.randomUUIDv7(), generating [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562) version 7 UUIDs, alongside the existing randomUUID() (v4).

Why

Unlike v4 UUIDs, v7 UUIDs embed a millisecond-precision timestamp in their most significant bits, which makes them sortable by creation time when compared as byte sequences or as their lowercase hex string form. This is useful as:

  • Database primary keys / index keys (avoids the random-insert index fragmentation that v4 UUIDs cause)
  • Any client-side scenario needing time-ordered unique IDs without a server round-trip

RFC 9562 (2024) formalized v7 specifically to address the fingerprinting concerns that blocked earlier timestamp-based UUID versions (v1) from being added to this API — see the discussion in WICG/uuid#25 and WICG/uuid#36. v7 does not embed a MAC address, and millisecond resolution alone does not provide a practically exploitable fingerprinting/tracking side channel beyond what other web-exposed timers already do.

Precedent

Three independent JS runtimes now agree on the randomUUIDv7() naming and shape, which is a meaningfully stronger signal than a single-implementation precedent.

What this PR does NOT do

  • It does not add a general "pick a version" option to randomUUID() itself — per prior discussion in Supporting future UUID formats WICG/uuid#36, overloading randomUUID() with a version parameter was considered undesirable, since older implementations would silently ignore it. This PR instead adds a separate, distinctly-named method, matching the precedent set by Node.js.
  • It does not guarantee strict monotonicity for UUIDs generated within the same millisecond (some server-side v7 implementations offer this via extra state). Left as a possible, clearly-flagged future extension in a spec note, since it needs per-realm state this method doesn't otherwise require.

Open questions for reviewers

  1. Is randomUUIDv7() the right name/shape, or should this be randomUUID({version: 7}) despite the earlier objection?
  2. Should sub-millisecond clock precision restrictions be spelled out more precisely (I added a non-normative note pointing at existing precedent like Performance.now() resolution)?
  3. Does RFC 9562 already resolve cleanly via specref, or does it need a localBiblio entry (RFC4122 didn't need one, but 9562 is newer)?

Opened as a starting point for discussion — happy to iterate based on feedback before/instead of merging as-is.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for generating UUIDv7s

1 participant