crypto: add uuidv7 monotonic counter by araujogui · Pull Request #62601 · nodejs/node

araujogui · 2026-04-05T16:15:41Z

Follow up #62553

nodejs-github-bot · 2026-04-05T16:15:46Z

Review requested:

@nodejs/crypto

Copilot

Pull request overview

Adds a monotonic counter to crypto.randomUUIDv7() so UUIDv7 values are strictly increasing even when multiple UUIDs are generated within the same millisecond.

Changes:

Implement monotonic rand_a counter state for UUIDv7 generation (buffered + unbuffered paths).
Write timestamp + counter into UUIDv7 bytes before serialization.
Tighten/extend tests to assert strict ordering, including burst generation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
test/parallel/test-crypto-randomuuidv7.js	Updates ordering assertions to require strict monotonic UUID string ordering and adds a burst test.
lib/internal/crypto/random.js	Adds UUIDv7-specific buffered state and monotonic timestamp/counter logic used by `randomUUIDv7()`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

harimm · 2026-04-05T17:17:27Z

Can you confirm that it’s intentional for advanceV7() to let the encoded timestamp move ahead of current clock time in order to preserve strict monotonic ordering once the 12-bit space is exhausted within a millisecond? Relatedly, under sustained high-throughput generation across multiple consecutive milliseconds, should we expect that drift from wall clock to continue accumulating until the burst subsides? Out of curiosity, is the 12-bit limit here driven strictly by any spec, or was there any consideration of alternative approaches once that per-millisecond space is exhausted?

codecov · 2026-04-05T17:36:34Z

Codecov Report

❌ Patch coverage is 92.98246% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.61%. Comparing base (dec5973) to head (e60619e).
⚠️ Report is 163 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/crypto/random.js	92.98%	4 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #62601 +/- ##
==========================================
- Coverage 89.70% 89.61% -0.10% 
==========================================
Files 695 706 +11 Lines 214524 219238 +4714 Branches 41080 41999 +919 ==========================================
+ Hits 192443 196468 +4025 - Misses 14121 14672 +551 - Partials 7960 8098 +138

Files with missing lines	Coverage Δ
lib/internal/crypto/random.js	`95.73% <92.98%> (-0.34%)`	⬇️

... and 136 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.

alexsch01 · 2026-04-08T15:30:43Z

If this gets merged, #62600 should get reversed

panva

#62553 (comment)
That can be a follow-up. It would reduce the UUID entropy so would probably need to be optional.

If this gets merged, #62600 should get reversed

In making this optional and documenting it it can also describe the nuance in the docs.

araujogui · 2026-04-08T16:06:53Z

#62553 (comment)
That can be a follow-up. It would reduce the UUID entropy so would probably need to be optional.
If this gets merged, #62600 should get reversed
In making this optional and documenting it it can also describe the nuance in the docs.

Why do you think it should be optional?

panva · 2026-04-08T16:30:34Z

Why do you think it should be optional?

First of all I don't think this is needed in the first place. Second, as @Renegade334's original comment that I've quoted says

It would reduce the UUID entropy so would probably need to be optional.

¯_(ツ)_/¯

araujogui · 2026-04-09T11:57:11Z

Why do you think it should be optional?
First of all I don't think this is needed in the first place. Second, as @Renegade334's original comment that I've quoted says
It would reduce the UUID entropy so would probably need to be optional.

I agree and made it optional via an argument, but I don't agree it's not needed, there's a lot of use cases where a counter is critical.

The most used UUID v7 library does this: https://github.com/LiosK/uuidv7/blob/main/src/index.ts#L263

panva · 2026-04-19T12:56:48Z

Is there a reason to not keep reusing uuidData/uuidBatch?

Renegade334 · 2026-04-19T13:36:24Z

+ if (now > v7LastTimestamp) {
+ v7LastTimestamp = now;
+ v7Counter = seed & 0xFFF;
+ } else {
+ v7Counter++;
+ if (v7Counter > 0xFFF) {
+ v7LastTimestamp++;
+ v7Counter = 0;
+ }
+ }


This is problematic if the clock moves backwards significantly, as the timestamp ends up frozen until such a time as the clock catches up. I don't know how other implementations handle this possibility.

From postgresql: https://raw.githubusercontent.com/postgres/postgres/dbf217c1c7c2744a18db489c255255e07cfbb110/src/backend/utils/adt/uuid.c
If the wall clock returns a value that isn't at least SUBMS_MINIMAL_STEP_NS ahead of the last call, the returned timestamp is synthetically bumped forward

from uuidjs https://github.com/uuidjs/uuid/blob/main/src/v7.ts#L65 just ignored

Renegade334 · 2026-04-19T13:38:42Z

+ if (v7Counter > 0xFFF) {
+ v7LastTimestamp++;
+ v7Counter = 0;
+ }


Prematurely incrementing the timestamp is a permissible way to handle counter overflow in the RFC, but I think we need to be really clear in the documentation that the potential timestamp drift in the generated UUIDs is effectively unbounded, and could diverge ad infinitum if generating UUIDs at very high frequency.

araujogui · 2026-04-22T23:56:31Z

Is there a reason to not keep reusing uuidData/uuidBatch?

Fixed!

panva · 2026-04-23T07:22:02Z

Is there a reason to not keep reusing uuidData/uuidBatch?
getBufferedUUIDv7 writes back into the buffer slot before serializing, getBufferedUUID is read-only.
Is there a reason to not keep reusing uuidData/uuidBatch?
Fixed!

I'm confused. Is the reason sound enough so that the split is needed or not? presumably not if you reverted to use the existing batches

araujogui · 2026-04-23T12:38:19Z

Is there a reason to not keep reusing uuidData/uuidBatch?
getBufferedUUIDv7 writes back into the buffer slot before serializing, getBufferedUUID is read-only.
Is there a reason to not keep reusing uuidData/uuidBatch?
Fixed!
I'm confused. Is the reason sound enough so that the split is needed or not? presumably not if you reverted to use the existing batches

My bad, it was not needed, that's why I reverted.

zdm · 2026-05-30T04:23:30Z

Will this PR be merged?
What is the problem?

bricss · 2026-08-02T10:00:18Z

That would be great ✨ to make it move ✈️ towards the landing 🛬

crypto: add uuidv7 monotonic counter
5e312c1

CopilotAI review requested due to automatic review settings April 5, 2026 16:15

nodejs-github-bot added crypto Issues and PRs related to the crypto subsystem. needs-ci PRs that need a full CI run. labels Apr 5, 2026

Copilotstarted reviewing on behalf of araujogui April 5, 2026 16:16 View session

CopilotAI reviewed Apr 5, 2026
View reviewed changes

Comment threadtest/parallel/test-crypto-randomuuidv7.js

crypto: fix flaky test
19bb93c

theoludwig mentioned this pull request Apr 7, 2026
doc: note non-monotonic clock in crypto.randomUUIDv7 #62600
Merged

panva previously requested changes Apr 8, 2026
View reviewed changes

crypto: make monotonic counter optional
a5f3be5

panva reviewed Apr 9, 2026
View reviewed changes

Comment threadlib/internal/crypto/random.js Outdated

araujogui added 2 commits April 9, 2026 09:01

crypto: disable monotonic counter by default
2f90718

crypto: add monotonic counter doc
c798973

panva requested a review from tniessen April 19, 2026 11:58

Renegade334 reviewed Apr 19, 2026
View reviewed changes

crypto: reuse uuid buffer
e60619e

Uh oh!

Uh oh!

Conversation

araujogui commented Apr 5, 2026

Uh oh!

nodejs-github-bot commented Apr 5, 2026

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

harimm commented Apr 5, 2026

Uh oh!

codecovBot commented Apr 5, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

alexsch01 commented Apr 8, 2026

Uh oh!

panva left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

araujogui commented Apr 8, 2026

Uh oh!

panva commented Apr 8, 2026

Uh oh!

Uh oh!

araujogui commented Apr 9, 2026

Uh oh!

panva commented Apr 19, 2026

Uh oh!

Renegade334Apr 19, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

araujoguiApr 22, 2026

Choose a reason for hiding this comment

Uh oh!

araujoguiApr 22, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Renegade334Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

araujogui commented Apr 22, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

panva commented Apr 23, 2026

Uh oh!

araujogui commented Apr 23, 2026

Uh oh!

zdm commented May 30, 2026

Uh oh!

bricss commented Aug 2, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

codecovBot commented Apr 5, 2026•
edited
Loading

panva left a comment •
edited
Loading

Renegade334Apr 19, 2026•
edited
Loading

araujoguiApr 22, 2026•
edited
Loading

araujogui commented Apr 22, 2026•
edited
Loading

bricss commented Aug 2, 2026•
edited
Loading