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.

Copilot · 2026-04-05T16:19:22Z

 {
  let prev = randomUUIDv7();
  for (let i = 0; i < 100; i++) {
    const curr = randomUUIDv7();
-    // UUIDs with later timestamps must sort after earlier ones.
-    // Within the same millisecond, ordering depends on random bits,
-    // so we only assert >= on the timestamp portion.
-    const prevTs = parseInt(prev.replace(/-/g, '').slice(0, 12), 16);
-    const currTs = parseInt(curr.replace(/-/g, '').slice(0, 12), 16);
-    assert(currTs >= prevTs,
-           `Timestamp went backwards: ${currTs} < ${prevTs}`);
+    // With a monotonic counter in rand_a, each UUID must be strictly greater
+    // than the previous regardless of whether the timestamp changed.
+    assert(curr > prev,
+           `UUID ordering violated: ${curr} <= ${prev}`);
    prev = curr;
  }
 }

+// Sub-millisecond ordering: a tight synchronous burst exercises the counter
+// increment path and must also produce strictly increasing UUIDs.
+{
+  const burst = [];
+  for (let i = 0; i < 500; i++) {
+    burst.push(randomUUIDv7());
+  }
+  for (let i = 1; i < burst.length; i++) {
+    assert(burst[i] > burst[i - 1],
+           `Sub-millisecond ordering violated at index ${i}: ` +
+           `${burst[i]} <= ${burst[i - 1]}`);
+  }
+}


The new monotonic-ordering assertions only exercise the default (buffered) code path. Since this PR changes both buffered and disableEntropyCache: true (unbuffered) implementations, it would be good to add at least one ordering check for randomUUIDv7({ disableEntropyCache: true }) as well, to ensure the unbuffered counter/timestamp logic stays monotonic too.

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?

getBufferedUUIDv7 writes back into the buffer slot before serializing, getBufferedUUID is read-only.

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

crypto: add uuidv7 monotonic counter

5e312c1

Copilot AI 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

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

Copilot AI reviewed Apr 5, 2026

View reviewed changes

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 thread lib/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!

Conversation

araujogui commented Apr 5, 2026

Uh oh!

nodejs-github-bot commented Apr 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

harimm commented Apr 5, 2026

Uh oh!

codecov Bot 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!

Renegade334 Apr 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!

araujogui Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

araujogui Apr 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!

Renegade334 Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

araujogui commented Apr 22, 2026

Uh oh!

panva commented Apr 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

codecov Bot commented Apr 5, 2026 •

edited

Loading

panva left a comment •

edited

Loading

Renegade334 Apr 19, 2026 •

edited

Loading

araujogui Apr 22, 2026 •

edited

Loading