Skip to content

crypto: implement randomUUIDv7()#62553

Open
nabeel378 wants to merge 7 commits intonodejs:mainfrom
nabeel378:main
Open

crypto: implement randomUUIDv7()#62553
nabeel378 wants to merge 7 commits intonodejs:mainfrom
nabeel378:main

Conversation

@nabeel378
Copy link
Copy Markdown

@nabeel378 nabeel378 commented Apr 2, 2026 •
edited by Renegade334
Loading

Adds crypto.randomUUIDv7() which generates RFC 9562 version 7 UUIDs.

UUIDv7 encodes a millisecond-precision Unix timestamp in the most
significant 48 bits, making these UUIDs time-sortable and suitable
for use as database primary keys.

Layout (128 bits):

  • 48 bits: unix_ts_ms (UTC milliseconds)
  • 4 bits: version (0b0111)
  • 12 bits: rand_a (random)
  • 2 bits: variant (0b10)
  • 62 bits: rand_b (random)

Fixes: #62529
Refs: https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7

@nodejs-github-bot
Copy link
Copy Markdown
Collaborator

nodejs-github-bot commented Apr 2, 2026

Review requested:

  • @nodejs/crypto

@nodejs-github-bot nodejs-github-bot added crypto Issues and PRs related to the crypto subsystem. needs-ci PRs that need a full CI run. labels Apr 2, 2026
@nabeel378 nabeel378 mentioned this pull request Apr 2, 2026
Open
Renegade334
Renegade334 reviewed Apr 2, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@Renegade334 Renegade334 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! A few initial comments.

@panva
Copy link
Copy Markdown
Member

panva commented Apr 2, 2026

A lot of effort went into optimizing the v4 version. We shall make sure to use the same primitives and setup without actually disrupting the v4 one.

At the moment this proposal doesn't align with the options v4 has.

@nabeel378
Copy link
Copy Markdown
Author

nabeel378 commented Apr 2, 2026

A lot of effort went into optimizing the v4 version. We shall make sure to use the same primitives and setup without actually disrupting the v4 one.

At the moment this proposal doesn't align with the options v4 has.

I have updated the implementation to fully align with v4: Added disableEntropyCache option matching randomUUID() Same batching strategy (kBatchSize = 128, secureBuffer, randomFillSync)

@nabeel378 nabeel378 requested a review from Renegade334 April 2, 2026 11:39
@panva panva added the commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. label Apr 2, 2026
Renegade334
Renegade334 reviewed Apr 2, 2026
View reviewed changes
Renegade334
Renegade334 reviewed Apr 2, 2026
View reviewed changes
panva
panva reviewed Apr 2, 2026
View reviewed changes
@panva
Copy link
Copy Markdown
Member

panva commented Apr 2, 2026

Please change the first commit message to crypto: implement randomUUIDv7() and make sure to use -s git flag to add a Signed-off-by trailer.

@panva panva changed the title crypto: add randomUUIDv7() crypto: implement randomUUIDv7() Apr 2, 2026
nabeel378 added 6 commits April 2, 2026 17:54
@nabeel378
crypto: implement randomUUIDv7()
628715c 
Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>
@nabeel378
crypto: refactor randomUUIDv7() to use serializeUUID for improved rea…
274b11a 
…dability
@nabeel378
test: remove redundant checks for UUID version and variant bits
87dd2ac
@nabeel378
crypto: update randomUUIDv7() to construct UUID string directly from …
828867d 
…bytes
@nabeel378
crypto: update randomUUIDv7() to accept options for disabling entropy…
e3a4a06 
… cache
@nabeel378
crypto: address review feedback for randomUUIDv7
8ddc406 
- Make version/variant required params in serializeUUID
- Share buffer pools (uuidData/uuidNotBuffered) between v4 and v7

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>
@nabeel378 nabeel378 requested review from Renegade334 and panva April 2, 2026 13:15
@nabeel378
docs: update RFC 9562 link in crypto documentation
49dac43 
Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>
@Renegade334 Renegade334 added the semver-minor PRs that contain new features and should be released in the next minor version. label Apr 2, 2026
@panva panva added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 2, 2026
@Renegade334 Renegade334 added the request-ci Add this label to start a Jenkins CI on a PR. label Apr 2, 2026
@panva panva added request-ci Add this label to start a Jenkins CI on a PR. and removed request-ci Add this label to start a Jenkins CI on a PR. labels Apr 2, 2026
@github-actions github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Apr 2, 2026
@nodejs-github-bot

This comment has been minimized.

Sign in to view
@codecov
Copy link
Copy Markdown

codecov bot commented Apr 2, 2026 •
edited
Loading

Codecov Report

❌ Patch coverage is 96.22642% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.71%. Comparing base (0dfdec9) to head (49dac43).
⚠️ Report is 5 commits behind head on main.

Files with missing lines Patch % Lines
lib/internal/crypto/random.js 96.07% 2 Missing ⚠️
Additional details and impacted files 
@@           Coverage Diff           @@
##             main   #62553   +/-   ##
=======================================
  Coverage   89.71%   89.71%           
=======================================
  Files         695      695           
  Lines      214154   214202   +48     
  Branches    41009    41020   +11     
=======================================
+ Hits       192132   192181   +49     
+ Misses      14075    14069    -6     
- Partials     7947     7952    +5
Files with missing lines Coverage Δ
lib/crypto.js 93.00% <100.00%> (+0.03%) ⬆️
lib/internal/crypto/random.js 96.07% <96.07%> (-0.04%) ⬇️

... and 29 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

araujogui
araujogui reviewed Apr 2, 2026
View reviewed changes
lib/internal/crypto/random.js
return disableEntropyCache ? getUnbufferedUUID() : getBufferedUUID();
}

function writeTimestamp(buf, offset) {
Copy link
Copy Markdown
Member

@araujogui araujogui Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we could add a monotonic counter here to ensure sub-millisecond sort order

Ref: https://datatracker.ietf.org/doc/html/rfc9562#name-monotonicity-and-counters

Copy link
Copy Markdown
Member

@Renegade334 Renegade334 Apr 2, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That can be a follow-up. It would reduce the UUID entropy so would probably need to be optional.

Copy link
Copy Markdown
Member

@araujogui araujogui Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure!

@nodejs-github-bot
Copy link
Copy Markdown
Collaborator

nodejs-github-bot commented Apr 2, 2026

CI: https://ci.nodejs.org/job/node-test-pull-request/72432/

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

Reviewers

@Renegade334 Renegade334 Renegade334 approved these changes

@panva panva panva approved these changes

@jasnell jasnell jasnell approved these changes

+1 more reviewer

@araujogui araujogui araujogui left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

author ready PRs that have at least one approval, no pending requests for changes, and a CI started. commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. crypto Issues and PRs related to the crypto subsystem. needs-ci PRs that need a full CI run. semver-minor PRs that contain new features and should be released in the next minor version.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add support for generating UUIDv7s

6 participants

@nabeel378 @nodejs-github-bot @panva @jasnell @Renegade334 @araujogui